# mcp-broker

A local proxy daemon standing before multiple MCP servers. It cuts context overhead by loading upstream tool schemas only on demand.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5
- Author: doricstack
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/doricstack/mcp-broker
- Updated: 2026-10-14
- HTML: https://affpapa.org/en/nevibecode/mcp/mcp-broker

## What it 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`.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add mcp-broker -- uvx mcp-broker
```
uvx runs the command named after the package; if the README names another one, use uvx --from mcp-broker <command>

### Codex

**Platform CLI**
```bash
codex mcp add mcp-broker -- uvx mcp-broker
```
uvx runs the command named after the package; if the README names another one, use uvx --from mcp-broker <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add mcp-broker uvx mcp-broker
```
uvx runs the command named after the package; if the README names another one, use uvx --from mcp-broker <command>

## When to use it
- 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
- 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`.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 392262
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33989
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81163
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119231
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47577
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43902

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md