mcp-unify

Unify multiple MCP servers behind a single endpoint. Lazy loading, auto-cleanup, Python plugins, role-based filtering.

The Problem

If you use Claude Code or any MCP client with 3+ servers, you get:

• Multiple subprocesses (~50MB each)
• Duplicated config
• No centralized control
• No way to add custom Python tools without a full MCP server

The Solution

mcp-unify runs one process that proxies N MCP servers on-demand:

Claude Code / MCP Client
  │
  ▼
mcp-unify (1 process)
  ├─ [plugin] Python @tool functions     ← in-process, 0 overhead
  ├─ [lazy]   filesystem-server          ← subprocess spawned on first call
  ├─ [lazy]   github-server              ← subprocess spawned on first call
  └─ [lazy]   playwright                 ← subprocess spawned on first call
      ↑
      5 min idle → auto-kill

Install

pip install mcp-unify

Quick Start

1. Create gateway.yaml

servers:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"
    enabled: false

idle_timeout: 300

2. Run

stdio (for Claude Code):

mcp-unify stdio --config gateway.yaml

SSE (for remote clients):

mcp-unify serve --config gateway.yaml --port 8765

3. Add to Claude Code

{
  "mcpServers": {
    "gateway": {
      "command": "mcp-unify",
      "args": ["stdio", "--config", "/path/to/gateway.yaml"]
    }
  }
}

Python Plugins

Add custom tools with zero boilerplate:

from mcp_gateway import tool

@tool(description="Add two numbers")
def add(a: float, b: float) -> float:
    return a + b

Reference in your config:

plugins:
  - module: my_tools.calculator

Or register programmatically:

from mcp_gateway import MCPGateway

gw = MCPGateway()
gw.register_tool(add)
await gw.serve_stdio()

Sync functions run via asyncio.to_thread(). Async functions run natively. Schemas are auto-generated from type hints.

Role-Based Filtering

Control which tools each client sees:

roles:
  admin: null        # all tools
  readonly: ["filesystem_*", "gateway_status"]
  developer: ["github_*", "filesystem_*", "gateway_*"]

Set the role via environment variable:

MCP_GATEWAY_ROLE=readonly mcp-unify stdio

Uses glob patterns — filesystem_* matches all tools from the filesystem server.

How It Works

1. Lazy Loading: Servers aren't started until a tool is called. Each server gets a _<name>_connect placeholder tool. Calling it spawns the subprocess and discovers real tool schemas via session.list_tools().

2. Auto-Cleanup: A background task checks every 60s and kills server subprocesses idle for longer than idle_timeout (default: 5 min).

3. Real Schemas: Tool schemas are discovered from the actual server via the MCP SDK, not hardcoded. You always get accurate inputSchema.

4. Plugin Tools: Python functions decorated with @tool run in the gateway process. Type hints are introspected to generate JSON Schema automatically.

API

from mcp_gateway import MCPGateway, tool

# From YAML
gw = MCPGateway.from_config("gateway.yaml")

# Programmatic
gw = MCPGateway()
gw.register_tool(my_function, name="my_tool", description="...")

# Serve
await gw.serve_stdio()    # stdio mode
await gw.serve_sse()      # SSE mode on :8765

# Context manager
async with MCPGateway() as gw:
    await gw.serve_stdio()

CLI

mcp-unify serve [--config FILE] [--host HOST] [--port PORT]
mcp-unify stdio [--config FILE]
mcp-unify list  [--config FILE]

Config discovery: --config > ./gateway.yaml > ./mcp-unify.yaml

Requirements

• Python >= 3.10
• mcp >= 1.0.0
• starlette >= 0.27.0
• uvicorn >= 0.23.0
• pyyaml >= 6.0

License

MIT