broker_search_toolsLABSCO SUMMARY
The mutating-tool gate is the part worth adopting on its own.
Context reduction is the headline, and the published numbers back it. The quieter win is that write tools stay invisible unless a profile allowlist names them, which makes "this client may read but not act" a configuration rather than a hope. What you take on in exchange is real: a daemon to run and watch, and a YAML contract that is now the source of truth for every client's tool surface.
What it is
A process broker for MCP, in the mould of a connection pooler. A small daemon owns the upstream servers — starting them on demand, sharing them across sessions or isolating them when state must not be shared, and cleaning them up afterwards — while each client sees one stable local entry and a compact set of broker tools instead of the full inventory.
What you get
- Four tools in place of every upstream tool definition: search the inventory, read one tool's schema, call it, and inspect broker state —
broker_search_tools,broker_describe_tool,broker_call_tool,broker_status - Profile-scoped exposure, so each client gets a configured view of the upstreams rather than everything by default, with per-profile tool budgets enforced
- Mutating-tool gates: an upstream's write tools stay hidden until a profile allowlist explicitly grants them
- Lifecycle ownership — shared and per-session upstreams are started, watched, stopped and reaped by the broker, which is what stops orphaned MCP processes surviving a client exit
- One place for the state that otherwise spreads across tools: OAuth, browser state, sockets, logs and cleanup, kept under a runtime directory outside the repository
- Client config rendering with a dry run, a backup at apply time and a rollback, for Codex, Claude and AGY profiles
- Service installation flows per platform — a macOS LaunchAgent, a Linux systemd user service, and a Windows scheduled task — each with render, install and removal steps
- Upstreams configured as stdio, HTTP, streamable HTTP or SSE connectors, with a YAML contract validated both structurally and against a published JSON Schema
- A published measurement of what this buys: on one Codex setup the direct MCP server entries went from 11 to 1, always-loaded tool definitions from 609 to 43, and serialized tool tokens from 276,989 to 45,281
Requirements
No account and no key — everything is local. Python 3.10 or newer available as python3, make, and Node.js with npx for npm-based upstream servers. macOS needs launchctl for the LaunchAgent path. Install the package with pipx, uv or Homebrew, which give you the same console scripts; a Docker image exists for container-friendly configs. Configuration is a private YAML file created from the bundled example — installing the package deliberately does not write your MCP client config, that stays an explicit action. The package publishes as mcp-broker on PyPI (2.0.0) with a client shim, a daemon and a CLI entry point.
Setup effort
One command — pipx install mcp-broker
USE CASES
01
Cutting what every session loads
Replace a long list of client MCP entries with one broker entry, and let tool definitions be fetched when a task needs them.
02
Giving one client read access and another write access
Define a profile per client and grant mutating upstreams only where an allowlist names them, instead of relying on the model not to call them.
03
Stopping duplicate and orphaned upstream processes
Let the broker own startup and reuse, so several sessions share one upstream and nothing survives after the client exits.
04
Changing client configuration without breaking it
Render the config as a dry run first, apply with a backup, and roll back if the client does not come up clean.
4 tools
Listed in project docs. Your client may show a different list.
broker_describe_toolbroker_call_toolbroker_statusBEFORE YOU INSTALL
What to know first
Tools you get
4 tools named in the project's documentation.
Requires
- pipx on PATH
- Python 3.10 or later
- make and a clone of the repository for the Codex, Claude and AGY config renderers
- Node.js with npx for npm-based upstream servers
INSTALLATION
Connect your client
Server setup
TERMINAL
pipx install mcp-brokerMCP Clients
Codex
CODEX · TERMINAL
git clone https://github.com/doricstack/mcp-broker.git
cd mcp-broker
make setup
make config-initEdit config/broker.private.yaml to list your upstream servers — keep secret values out of it, as environment variable names under upstreams.<YOUR_NAME>.env or files under $HOME/mcp/mcp-broker/secrets/
CODEX · TERMINAL
make config-validate
make broker-start
make config-render CLIENT=codex CONFIG_RENDER_APPLY=0Review the rendered file under $HOME/mcp/mcp-broker/renders/, then apply it:
CODEX · TERMINAL
make config-render CLIENT=codex CONFIG_RENDER_APPLY=1The client-config renderers are Makefile targets, so this route runs from a clone of the repository, not from the pipx package. Use CLIENT=claude or CLIENT=agy the same way once that profile passes validation; make config-rollback CLIENT=codex restores the backup.
Any MCP client
In your MCP client's settings, add a stdio server whose command is mcp-broker with the arguments stdio --init-if-missing. It is the project's line for direct stdio clients: it starts the broker daemon and its stdio facade in one process, using the configured runtime root, config and profile.
