@NavinAgrawal
Basic information
mcp-broker is a local Model Context Protocol process broker for MCP clients.
Add this server to your MCP-compatible client using the configuration below.
{
"mcpServers": {
"mcp-broker": {
"command": "uvx",
"args": [
"mcp-broker",
"stdio",
"--profile",
"docker",
"--init-if-missing"
],
"env": {}
}
}
}Search the profile-visible upstream MCP tool catalog without advertising every upstream tool to the client. Use this first when the task mentions a capability, service, keyword, or upstream prefix and you need candidate broker-qualified tool names before describing or calling one of them.
Describe one profile-visible upstream MCP tool by broker-qualified name. Use this after broker_search_tools and before broker_call_tool so the client can inspect the exact description, input schema, upstream owner, transport, and mutating metadata instead of guessing arguments.
Call one profile-visible upstream MCP tool through the broker using its broker-qualified name and exact argument object. The broker's mutating-tool policy remains gated by the active profile's allowlist, so call broker_describe_tool first and pass only arguments accepted by the described upstream schema.
Report broker and upstream status for the active profile without starting hidden or denied upstreams. Use this for health checks, support tickets, and client validation because it returns the profile name, broker socket path, aggregate status, upstream runtime state, auth state, transport, process id, restarts, and mutating exposure.
Release the broker-owned per-session upstream processes for the current client session. Use this after shutting down a client session when its session-scoped MCP subprocesses must exit promptly. This never stops shared upstreams or another client's session.
Mcp Broker is a local Model Context Protocol process broker that sits as a facade in front of many upstream MCP servers. It manages upstream startup, reuse, cleanup, profile exposure, status, and safe tool routing — analogous to PgBouncer for MCP. It is designed for developers using MCP clients (Codex, Claude Code, Gemini CLI) who have more tools than they want in every session and need a single stable local endpoint.
Install via pipx install mcp-broker, uv tool install mcp-broker, or brew install mcp-broker. After installation, run make setup to create a local venv, then make config-init to create a private config from the public template. Edit config/broker.private.yaml for local upstreams, then make config-validate to validate the YAML contract. Start the broker with make broker-start and check status with make broker-status. Wire MCP clients using make config-render CLIENT=<client> (e.g., codex, claude, gemini) after reviewing rendered files.
It solves the problems of duplicated MCP server configurations, duplicate upstream processes across sessions, scattered state, large raw tool lists consuming context, and orphaned processes — by placing a small broker facade in front of upstream servers.
It replaces many raw upstream tool definitions with four broker facade tools (`broker_search_tools`, `broker_describe_tool`, `broker_call_tool`, `broker_status`). Measured with a Codex setup: tool definitions dropped from 609 to 43 (92.94% reduction), and serialized tool tokens from 276,989 to 45,281 (83.65% reduction).
The broker exposes four tools to clients: `broker_search_tools` (search upstream tools by query), `broker_describe_tool` (return schema and metadata), `broker_call_tool` (call an upstream tool), and `broker_status` (show profile-visible upstream state and errors).
macOS (LaunchAgent install/uninstall), Linux (systemd user‑service render, install, unload, removal), and Windows (PowerShell Scheduled Task render, install, removal). Docker image support is also available for container-friendly configs.
Via `pipx install mcp-broker`, `uv tool install mcp-broker`, or `brew install mcp-broker` (tap: `NavinAgrawal/tap`). Docker build is also possible. Package installs do not write client config; wiring is a separate Makefile action.
Model Context Protocol Servers
A good sequence diagram can solve almost any communication problem in engineering. Volley lets your agent write them as plain text, with the real request and response payloads on every arrow. It checks its own syntax wi
🔥 MaxKB is an open-source platform for building enterprise-grade agents. 强大易用的开源企业级智能体平台。
Painless E2E Automation for Mobile and Web
B2B competitive intelligence, live sales battlecards, 5-axis ICP prospect fit scoring, and tech stack teardowns over MCP and REST with cited public-web evidence.
Comments