multi-mcp

multi-mcp

A production-ready MCP proxy server that aggregates multiple backend MCP servers into a single endpoint — with lazy loading, per-tool filtering, and a unified YAML config that doubles as a live control plane.

All your AI tools → multi-mcp → github, obsidian, exa, tavily, context7, ...

Why

Most MCP setups require configuring every server individually in every tool (Claude Code, Codex, Cursor, etc.). Each server starts eagerly at boot. You have no easy way to disable specific tools from a server you otherwise want.

multi-mcp solves all three:

• One endpoint — configure it once, every tool connects to multi-mcp
• Lazy loading — servers only connect when a tool is actually called
• Tool control — flip enabled: false on any individual tool in a YAML file

Features

• Unified YAML config — single file serves as cache, config, and control plane
• Startup discovery — connects to every server briefly at first run, caches tool lists, disconnects lazy servers
• Lazy loading — lazy servers reconnect on first tool call, auto-disconnect after idle timeout
• Always-on servers — stays connected permanently, auto-reconnects if dropped
• Per-tool enable/disable — expose exactly the tools you want from each server
• Smart refresh — re-discovers tools without overwriting your settings
• Stale tool cleanup — tools that disappear from a server and were disabled get pruned automatically
• Supports all transports — stdio, SSE, and Streamable HTTP (2025 spec)
• Tool namespacing — server::tool_name prevents conflicts across servers
• Runtime HTTP API — add/remove servers without restarting (SSE mode)
• Audit logging — JSONL log of every tool call
• API key auth — optional Bearer token for SSE mode

Quick Start

Requirements: Python 3.10+, uv

git clone https://github.com/itstanner5216/multi-mcp
cd multi-mcp
uv sync

First run — auto-discovers all your servers and writes ~/.config/multi-mcp/servers.yaml:

uv run python main.py start

Or refresh manually to re-discover tools and update the YAML:

uv run python main.py refresh

Config

On first run, multi-mcp creates ~/.config/multi-mcp/servers.yaml by connecting to every server you've configured, fetching its tool list, then disconnecting. The resulting file looks like:

servers:
  github:
    command: /path/to/run-github.sh
    always_on: true          # stays connected at all times
    idle_timeout_minutes: 5
    tools:
      search_repositories:
        enabled: true
      delete_repository:
        enabled: false        # hidden from all AI tools
      create_gist:
        enabled: false

  exa:
    url: https://mcp.exa.ai/mcp?tools=web_search_exa,get_code_context_exa
    always_on: false          # lazy: connects only when called
    idle_timeout_minutes: 5
    tool_call_timeout_seconds: 60   # optional: fail hung tool calls after 60s
    tools:
      web_search_exa:
        enabled: true
      linkedin_search_exa:
        enabled: false        # don't need this

  obsidian:
    command: /path/to/run-obsidian.sh
    always_on: true
    tools: {}                 # auto-populated on first run

Tool control rules:

To disable a tool, just set enabled: false and save. Takes effect on next multi-mcp start.

Per-server timeouts: set tool_call_timeout_seconds on a server to bound how long a tool call may take. When unset (default), calls wait indefinitely. When set, a hung backend returns a timeout error instead of stalling the request, and repeated timeouts trip the proxy's circuit breaker (auto-quarantine after 3 consecutive failures).

CLI

# Start the proxy (stdio mode — used by Claude Code, Codex, etc.)
uv run python main.py start

# Start in SSE mode (network accessible)
uv run python main.py start --transport sse --port 8085

# Re-discover tools from all servers, smart-merge into YAML
uv run python main.py refresh

# Re-discover tools from one server only
uv run python main.py refresh github

# Show server status and tool counts
uv run python main.py status

# List all tools with enabled/disabled status
uv run python main.py list

# Filter to one server
uv run python main.py list --server github

# Show only disabled tools
uv run python main.py list --disabled

Connecting Your AI Tools

Once multi-mcp is running, replace all individual server entries in your tool configs with a single entry:

Claude Code / Cursor / any JSON-based config:

{
  "mcpServers": {
    "multi-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--project", "/path/to/multi-mcp", "python", "main.py", "start"]
    }
  }
}

SSE mode (if running as a background service):

{
  "mcpServers": {
    "multi-mcp": {
      "type": "sse",
      "url": "http://localhost:8085/sse"
    }
  }
}

Transport Support

multi-mcp connects to backend servers over any transport:

For url-based servers, multi-mcp tries Streamable HTTP first and falls back to legacy SSE automatically.

Runtime API (SSE mode)

When running with --transport sse, a management API is available:

# List active servers
GET /mcp_servers

# Add a server at runtime
POST /mcp_servers
{"name": "new-server", "command": "/path/to/server"}

# Remove a server
DELETE /mcp_servers/{name}

# List all tools by server
GET /mcp_tools

# Health check
GET /health

Authenticate with Authorization: Bearer <key> (set MULTI_MCP_API_KEY env var to enable).

Architecture

┌──────────────────────────────────────────────────┐
│  Claude Code / Codex / Cursor / any MCP client   │
└─────────────────────┬────────────────────────────┘
                      │ stdio or SSE
              ┌───────▼────────┐
              │   multi-mcp    │
              │                │
              │ • YAML config  │
              │ • namespacing  │
              │ • tool filter  │
              │ • lazy loading │
              │ • audit log    │
              └──┬──────┬──────┘
                 │      │
    ┌────────────┘      └──────────────┐
    │                                  │
┌───▼──────────┐              ┌────────▼──────┐
│ always_on    │              │     lazy      │
│              │              │               │
│ github       │              │ exa (SSE)     │
│ obsidian     │              │ tavily        │
│              │              │ context7      │
│ (connected   │              │ seq-thinking  │
│  always)     │              │               │
└──────────────┘              │ (connects on  │
                              │  first call,  │
                              │  disconnects  │
                              │  after idle)  │
                              └───────────────┘

Development

# Run tests
uv run python -m pytest

# Run specific test file
uv run python -m pytest tests/test_cache_manager.py -v

# Check what's configured
uv run python main.py status
uv run python main.py list

Test coverage: 30 tests across YAML config, merge logic, startup discovery, idle timeout, startup flow, CLI, and reconnect behavior.

Environment Variables

License

MIT