MCP gateway

The MCP gateway puts BitRouter between an agent or model request and the third-party MCP servers it uses. Configure upstreams once, then expose each server directly or combine them behind one aggregate endpoint.

BitRouter OSS is the client and gateway on this path. It does not add BitRouter-owned administrative tools to the catalog.

Configure upstream servers

Add servers under mcp_servers in bitrouter.yaml. Stdio entries launch a child process; HTTP entries connect to a Streamable HTTP endpoint.

mcp_servers:
  filesystem:
    name: filesystem
    transport:
      type: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/data"]
  context7:
    name: context7
    transport:
      type: http
      url: https://mcp.context7.com/mcp
      headers:
        Authorization: "Bearer ${CONTEXT7_TOKEN}"

A stdio child inherits the ambient environment, with its configured env values added or overridden. HTTP headers are sent to that upstream on every request.

Direct and aggregate routes

The aggregate is enabled by default and can be moved or disabled:

mcp:
  aggregate:
    enabled: true
    route: /mcp

To avoid collisions, aggregate tool and prompt names are prefixed with the server id. A tool named search from context7 is advertised as context7__search. Override the prefix or exclude one server from aggregation without disabling its direct route:

mcp_servers:
  context7:
    name: context7
    transport:
      type: http
      url: https://mcp.context7.com/mcp
    tool_prefix: "docs__"
    aggregate: false

Diagnose upstreams

bro mcp check is the canonical diagnostic. It performs a tools/list round trip and reports transport, reachability, latency, negotiated tool capability, and advertised tool names.

bro mcp check             # every configured upstream
bro mcp check context7    # one upstream

The configuration remains the source of truth; the check does not maintain a separate global tool registry.

Cache discovery, not execution

Aggregate list calls use bounded TTL caches by default. Tool execution is never cached.

Set an individual TTL to 0, or disable the cache as a whole:

mcp:
  cache:
    enabled: false

Execute tools inside a model request

The gateway normally lets an external agent call MCP tools. To let BitRouter run the tool loop, list selected upstream ids under server_tools.mcp_servers:

server_tools:
  mcp_servers: [filesystem, context7]
  max_iterations: 6

BitRouter then advertises those tools to the model, executes selected calls, returns results to the model, and continues until the model stops requesting tools or the iteration bound is reached. Merely declaring an upstream under mcp_servers does not put it into this loop. See Server tools for approval and iteration behavior.

Connect a coding agent

bro launch injects the aggregate endpoint into supported native harnesses without editing their user configuration. Claude, Codex, OpenCode, and Hermes have an injectable MCP surface; other harnesses may not.

bro launch codex

The launch summary states whether model routing and MCP injection were applied. Local filesystem skills use the agent host's normal plugin/skill mechanism; they are not served by a BitRouter origin MCP process.