NavinAgrawal/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.
The client sees a small set of broker tools:
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.
| Surface | Before | After | Reduction |
|---|---:|---:|---:|
| Direct Codex MCP server entries | 11 | 1 | 90.91% |
| MCP tool definitions | 414 | 4 | 99.03% |
| Hosted codex_apps tool definitions | 195 | 39 | 80.00% |
| Combined always-loaded tool definitions | 609 | 43 | 92.94% |
| Combined serialized tool payload bytes | 1,026,171 | 185,877 | 81.89% |
| Combined o200k_base tool tokens | 276,989 | 45,281 | 83.65% |
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.
- Provides Linux systemd user-service render, install, unload, and removal flows.
- Provides Windows PowerShell Scheduled Task render, install, and removal flows.
- Includes unit, journey, live, and e2e tests through Makefile targets.
Core differentiators:
- Profile-scoped exposure: each MCP client gets a configured view of upstreams instead of every tool by default.
- Mutating-tool gates: mutating upstreams stay hidden until a profile allowlist grants access.
- Lifecycle ownership: shared and per-session upstreams are started, watched, stopped, and reaped by the broker.
- Client parity checks: rendered profiles can be validated through the same compact broker facade before config is applied.
Who this is for
Use mcp-broker if you:
- use Codex, Claude Code, AGY CLI, or other MCP clients
- have more MCP tools than you want in every session
- need shared local MCP servers without duplicate process startup
- want one place for OAuth state, browser state, sockets, logs, and cleanup
- need per-client profiles instead of the same tool list everywhere
- want a small broker facade instead of raw upstream tool dumps
This repo is not an enterprise MCP control plane. It is local desktop infrastructure for developer-agent workflows.
Current status
Implemented:
- YAML config loading from config/broker.private.yaml, created from config/broker.example.yaml.
- Strict YAML contract validation for runtime, clients, profiles, upstreams, and policy blocks.