> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reasonos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Integration

> rbs speaks the Model Context Protocol in both directions: serve rbs tools to any MCP client, and connect external MCP servers to the rbs agent.

rbs integrates with the [Model Context Protocol](https://modelcontextprotocol.io) 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

```bash theme={null}
# 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:

```json theme={null}
{
  "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`:

```bash theme={null}
# 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
```

<Warning>
  `--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.
</Warning>

### 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:

```bash theme={null}
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](/agents/skills):

* 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.

```python theme={null}
# 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:

```python theme={null}
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](/agents/using-the-agent#headless-agent-tasks-in-the-build-graph) name the servers they need with the `mcp` attribute; only those servers are connected for the run:

```python theme={null}
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](/agents/overview#engines), 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.