mcp-broker MCP server

mcp-broker

<!-- mcp-name: io.github.doricstack/mcp-broker -->

mcp-broker is a local Model Context Protocol process broker for MCP clients.

Think PgBouncer for MCP: one stable local endpoint in front of many upstream MCP servers. The broker owns upstream startup, reuse, cleanup, profile exposure, status, and safe tool routing.

The core idea is simple: do not make every agent session load every upstream tool definition before the user asks a task.

Why this exists

AI coding sessions with many MCP servers tend to accumulate the same problems:

• every client config repeats the same MCP server list
• every new session can start duplicate upstream processes
• OAuth, browser state, local files, and database handles spread across tools
• raw tool lists consume context before the task begins
• hosted connector caches can duplicate local MCP tools
• orphaned MCP processes survive after client sessions exit

mcp-broker puts a small broker facade in front of those upstreams. It is not a hosted workflow builder; it is local infrastructure for keeping MCP clients small, predictable, and under one config contract.

Client profile
        |
        | one local MCP entry
        v
  mcp-broker-client
        |
        | Unix socket
        v
  mcp-broker-daemon
        |
        | profile gates, namespace routing, status, cleanup
        v
  upstream MCP servers

The client sees a small set of broker tools:

broker_search_tools
broker_describe_tool
broker_call_tool
broker_status
broker_close_session

The upstream MCPs still exist. They are discovered and called through the broker when a task needs them.

Measured context reduction

On 2026-05-24, the measured Codex setup went from many raw MCP and hosted app tool definitions to one broker facade plus a pruned codex_apps cache.

The 92.94% number is a tool-definition count reduction. The 83.65% number is a token reduction for canonical serialized tool payloads measured with tiktoken o200k_base.

See docs/context-reduction-measurement.md for evidence and caveats.

What it does

• Runs one local broker daemon over a Unix socket.
• Exposes one lightweight stdio client shim to MCP clients.
• Starts upstream MCP servers on demand.
• Reuses shared upstreams across sessions when configured.
• Isolates per-session upstreams when state must not be shared.
• Maps upstream tools into stable namespaces.
• Exposes compact search, describe, call, status, and caller-bound session-close tools.
• Enforces profile-level tool budgets and exposure gates.
• Blocks mutating upstream exposure unless a profile allowlist grants it.
• Stores runtime state under $HOME/mcp/mcp-broker, outside the repo.
• Renders MCP client config entries with dry-run, backup, and rollback.
• Provides LaunchAgent install and uninstall flows for macOS.

Core differentiators:

Shortened. The full README is on GitHub.