MCP Integration - ReasonOS Documentation

rbs integrates with the Model Context Protocol in both directions:

As a server — rbs mcp serve exposes the agent’s tool surface (graph queries, build/test, search, skills) to any MCP client: Claude Desktop, Claude Code, ChatGPT, or your own tooling.
As a client — MCP servers declared in your workspace give the rbs agent extra tools (a browser, a database, an internal API) for its sessions and for ai_task targets.

Serving rbs as an MCP server

# stdio mode — for Claude Desktop, Claude Code, and similar clients
rbs mcp serve

# HTTP mode — a streamable HTTP server
rbs mcp serve --http :3001

In stdio mode the server speaks MCP on stdin/stdout. In HTTP mode, point your client at http://localhost:3001/mcp. A Claude Desktop configuration looks like:

{
  "mcpServers": {
    "rbs": {
      "command": "rbs",
      "args": ["mcp", "serve"]
    }
  }
}

Run it from (or configure the client to start it in) your workspace directory — the server loads the workspace so graph and authoring tools answer from your real target graph.

The curated tool surface

By default the server exposes a curated subset of the agent’s tools: file reading, search, the graph and knowledge-graph queries, build/test, dependency inspection, and skills. Several tool categories are excluded on purpose:

Interactive tools that block waiting on the rbs UI (they would hang your client)
Agent-loop internals (todo management, plan mode) that only make sense inside the rbs agent’s own loop
Agent-spawning tools (delegation, background agents) that would issue LLM calls from inside the server
Write tools that mutate the workspace or run commands — excluded unless you opt in

Adjust the surface with flags shared by serve and list:

# Include mutating tools (write_file, str_replace, delete_file,
# run_command, rbs_run, task/lesson writers) in the curated surface
rbs mcp serve --allow-write

# Expose every runtime tool
rbs mcp serve --tools full

# Drop specific tools by name (applies in both modes)
rbs mcp serve --exclude-tools rbs_run,delete_file

--allow-write and --tools full let a connected client edit files and execute commands in your workspace. Only enable them for clients you trust, and prefer --exclude-tools to trim anything you don’t want reachable.

Previewing the surface

rbs mcp list prints exactly what a connected client would see, honoring the same flags — including which tools are excluded and why:

rbs mcp list
rbs mcp list --tools full
rbs mcp list --allow-write --exclude-tools rbs_run

Skills as resources and prompts

Beyond tools, the server publishes the agent’s skill corpus:

every skill is an MCP resource under rbs://skills/<name> (for example rbs://skills/bootstrap-workspace, rbs://skills/using-go-rules)
two composed prompts let a client bootstrap rbs context in one call: rbs-onboarding (workspace bootstrap, monorepo conventions, verification discipline) and rbs-build-file-authoring (how rules and BUILD.rbs files work)

This is how an external agent working in your workspace gets the same maintained guidance the built-in agent runs on.

Connecting external MCP servers to the agent

Declare MCP servers in your WORKSPACE.rbs with native.define_mcp_server(). The agent connects to them at session start and their tools appear alongside the built-ins.

# A stdio server, launched as a subprocess
native.define_mcp_server(
    name = "postgres",
    command = "npx",
    args = ["-y", "@modelcontextprotocol/server-postgres"],
    env = {"DATABASE_URL": "postgres://localhost:5432/dev"},
    toolchain = "nodejs",
)

# A streamable-HTTP server, reached by URL
native.define_mcp_server(
    name = "internal-api",
    url = "http://localhost:8080/mcp",
)

One of command (stdio) or url (HTTP) is required. The optional toolchain names a registered rbs toolchain whose runtime should resolve the command — so npx above runs from the workspace’s hermetic Node toolchain rather than whatever is on PATH. Skip connecting for a session with rbs agent --no-mcp.

The Chrome DevTools server

For browser automation, rbs bundles a helper that registers a Chrome DevTools MCP server — this is what powers ai_qa_test browser tests:

load("@rbs//agent/mcp/chrome/mcp.rbs", "chrome_mcp_server")

chrome_mcp_server(
    name = "chrome",
    headless = True,
    # Set install_chrome = True to download Chrome for Testing via the
    # toolchain system — useful in CI where no browser is installed.
)

MCP in `ai_task` targets

Headless agent tasks name the servers they need with the mcp attribute; only those servers are connected for the run:

native.ai_task(
    name = "qa_checkout",
    todos = ["open the store", "add an item to the cart", "verify the total"],
    mcp = ["chrome"],
    run_targets = [":dev"],
)

MCP and the external engines

When a session runs on the Claude Code or Codex engine, rbs forwards the full MCP picture automatically: the external agent is configured with your workspace’s declared MCP servers plus rbs itself — the running binary serving its curated tool surface over stdio. An external engine session therefore gets the same graph, build/test, and skills tools as the native engine, with no configuration on your part.

​Serving rbs as an MCP server

​The curated tool surface

​Previewing the surface

​Skills as resources and prompts

​Connecting external MCP servers to the agent

​The Chrome DevTools server

​MCP in ai_task targets

​MCP and the external engines

Serving rbs as an MCP server

The curated tool surface

Previewing the surface

Skills as resources and prompts

Connecting external MCP servers to the agent

The Chrome DevTools server

MCP in `ai_task` targets

MCP and the external engines