MCP Orchestrator

A central hub that connects to multiple downstream MCP servers, aggregates their tools, and provides unified access with powerful tool search capabilities.

Built arounddeferred tool loading— search across all your servers without blowing Claude's context window.

- Config-based Server Registration: Add downstream MCP servers via JSON config file
- Tool Namespacing: Automaticserver_name__tool_nameformat
- Tool Search: Unified BM25/regex search with deferred loading support
- Flexible Authentication: Static saved headers or token forwarding
- Multiple Transports: stdio or HTTP
- Tool Definition Caching: Cached definitions, raw result passthrough
- Storage Backends: In-memory (development) or Redis (production)

# Run as stdio MCP server (for Claude Desktop, Cursor, etc.) mcp-orchestrator # Or run with Python directly python -m mcp_orchestrator.main

ORCHESTRATOR_TRANSPORT=http ORCHESTRATOR_PORT=8080 python -m mcp_orchestrator.main

This starts the server onhttp://localhost:8080/mcpwith CORS enabled.

Add downstream MCP servers inserver_config.json:

{ "servers": [ { "name": "my-server", "url": "http://localhost:8080/mcp", "transport": "http", "auth_type": "static", "auth_headers": { "Authorization": "Bearer my-token" } }, { "name": "my-stdio-server", "url": "server.py", "transport": "stdio", "command": "uv", "args": ["run", "python", "server.py"] } ] }

The orchestrator provides unified tool search (BM25 by default, regex optional):

# BM25 search (default - natural language) results = await mcp_client.call_tool("tool_search", { "query": "get weather information", "max_results": 3 }) # Regex search (set use_regex=true) results = await mcp_client.call_tool("tool_search", { "query": "weather|forecast", "use_regex": true, "max_results": 3 })

┌─────────────────────────────────────────────────────┐ │ MCP Orchestrator │ │ │ │ ┌──────────────────────────────────────────────┐ │ │ │ FastMCP Server │ │ │ │ ┌─────────────┐ ┌──────────────────┐ │ │ │ │ │ tool_search │ │ call_remote_tool │ │ │ │ │ └─────────────┘ └──────────────────┘ │ │ │ └──────────────────────────────────────────────┘ │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ │ │ Server │ │ Tool │ │ Storage │ │ │ │ Registry │ │ Search │ │(Memory/Redis)│ │ │ └──────────┘ └──────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────┘ │ ┌───────────────────┼───────────────────┐ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ MCP Svr │ │ MCP Svr │ │ MCP Svr │ │ #1 │ │ #2 │ │ #N │ └─────────┘ └─────────┘ └─────────┘

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{ "mcpServers": { "mcp-orchestrator": { "command": "mcp-orchestrator", "env": { "STORAGE_BACKEND": "memory", "ORCHESTRATOR_LOG_LEVEL": "INFO" } } } }

Search for tools using BM25 relevance ranking or regex pattern matching.

@mcp.tool() async def tool_search( query: str, max_results: int = 3, use_regex: bool = False, ) -> dict: """Search for tools using BM25 or regex. By default uses BM25 natural language search. Set use_regex=True to search using Python regex patterns instead. """

Discover tools from a registered downstream server.

@mcp.tool() async def discover_tools( server_name: str, ) -> dict: """Discover tools from a registered server and index them for search. Returns the list of discovered tools with their schemas. """

Call a tool directly on a downstream MCP server.

@mcp.tool() async def call_remote_tool( tool_name: str, arguments: Optional[dict] = None, auth_header: Optional[str] = None, ) -> Any: """Call a tool on a downstream server. Args: tool_name: Namespaced tool name (server_name__tool_name) arguments: Tool arguments auth_header: Optional auth header to override server's configured auth """

The search tools return results in the format expected by Claude's tool search system:

{ "success": true, "tool_references": [ { "type": "tool_reference", "tool_name": "server_name__tool_name" } ], "total_matches": 5, "query": "weather" }

mcp-orchestrator/ ├── src/mcp_orchestrator/ │ ├── __init__.py │ ├── main.py # Entry point │ ├── models.py # Pydantic models │ ├── mcp_server.py # FastMCP server │ ├── config_loader.py # Config file loader │ ├── server/ │ │ └── registry.py # Server registry │ ├── tools/ │ │ ├── router.py # Tool router │ │ └── search.py # Tool search service │ └── storage/ │ ├── base.py # Storage interface │ ├── memory.py # In-memory backend │ └── redis.py # Redis backend ├── tests/ │ ├── test_registry.py │ ├── test_search.py │ ├── test_storage.py │ ├── test_models.py │ └── test_integration.py ├── server_config.json # Pre-configured downstream servers ├── pyproject.toml ├── README.md └── .env # Environment variables (not committed)

Contributions are welcome! Please seeCONTRIBUTING.mdfor guidelines.

MCP bridge that lets Claude Code delegate heavy tasks to the Antigravity CLI (agy) — purpose-built tools, model routing with fallback, session continuity, and output truncation to save Claude's context and tokens.