mcp-broker — Claude Code MCP server: what it does, how to install
A local proxy daemon standing before multiple MCP servers. It cuts context overhead by loading upstream tool schemas only on demand.
claude mcp add mcp-broker -- uvx mcp-brokerWhat mcp-broker does
The project acts like PgBouncer for the Model Context Protocol. A lightweight stdio client passes requests across a Unix socket to a background daemon. Rather than loading hundreds of raw definitions into the prompt at startup, clients get five core tools for discovery, inspection, execution, status, and session shutdown. In benchmark runs, always-loaded definitions dropped from 609 down to 43.
The daemon boots external servers when called and reaps orphaned child processes after work finishes. You can split tooling across client profiles or keep shared long-running processes alive. Mutating tools remain disabled until you allow them in the YAML configuration. Runtime sockets and logs stay in $HOME/mcp/mcp-broker.
What it helps with
- slash prompt token consumption caused by bloated tool lists
- prevent duplicate background processes across separate agent sessions
- restrict mutating tool actions using profile allowlists
- manage upstream process shutdowns without leaving orphaned tasks
Example prompts for the agent
- Search for an active database tool using broker search.
- Check the current connection status with
broker_status. - Execute a schema migration task using
broker_call_tool.
How to install mcp-broker
Platform CLI
claude mcp add mcp-broker -- uvx mcp-brokeruvx runs the command named after the package; if the README names another one, use uvx --from mcp-broker <command>
Platform CLI
codex mcp add mcp-broker -- uvx mcp-brokeruvx runs the command named after the package; if the README names another one, use uvx --from mcp-broker <command>
Config file
{
"mcpServers": {
"mcp-broker": {
"command": "uvx",
"args": [
"mcp-broker"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from mcp-broker <command>
Config file
{
"servers": {
"mcp-broker": {
"type": "stdio",
"command": "uvx",
"args": [
"mcp-broker"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from mcp-broker <command>
Platform CLI
gemini mcp add mcp-broker uvx mcp-brokeruvx runs the command named after the package; if the README names another one, use uvx --from mcp-broker <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-broker
How to install mcp-broker in Claude Code?
Run claude mcp add mcp-broker -- uvx mcp-broker.
What does mcp-broker do?
It provides a local facade that multiplexes upstream MCP servers behind a Unix socket daemon. Clients query and invoke tools dynamically instead of parsing all definitions at launch.
Where does mcp-broker keep its state and config?
Configuration lives in config/broker.private.yaml, while runtime logs, sockets, and session records reside under $HOME/mcp/mcp-broker.
