MCP connections

Declare upstream MCP servers in bitrouter.yaml. The router connects to these servers and exposes their capabilities through direct or aggregate routes. MCP servers explains the gateway behavior and how agents consume it.

Configure upstream servers

Add servers under mcp_servers in the bitrouter.yaml router policy. 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 configured env values added or overridden. HTTP headers are sent to that upstream on every request.

Configure the aggregate gateway

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

mcp:
  aggregate:
    enabled: true
    route: /mcp

Aggregate tool and prompt names are prefixed with the server id to avoid collisions. 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

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

Enable use by server tools

Declaring an upstream makes it available to the gateway. To use its tools inside BitRouter's model loop, also select it under Server tools configuration.

Validate and check

bro config validate -c bitrouter.yaml
bro reload -c bitrouter.yaml
bro mcp check
bro mcp check context7

The check performs a tools/list round trip against configured upstreams; it does not create a separate registry. Configuration file covers applying changes and when a restart is required.