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 around deferred tool loading — search across all your servers without blowing Claude's context window.

Features

• Config-based Server Registration: Add downstream MCP servers via JSON config file
• Tool Namespacing: Automatic server_name__tool_name format
• 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)

Quick Start

Installation

pip install mcp-orchestrator

Running the MCP Server

# Run as stdio MCP server (for Claude Desktop, Cursor, etc.)
mcp-orchestrator

# Or run with Python directly
python -m mcp_orchestrator.main

HTTP Transport:

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

This starts the server on http://localhost:8080/mcp with CORS enabled.

Configuring Servers

Add downstream MCP servers in server_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"]
    }
  ]
}

Searching for Tools

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
})

Architecture

┌─────────────────────────────────────────────────────┐
│                  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    │
   └─────────┘    

... [View full README on GitHub](https://github.com/rupinder2/mcp-orchestrator#readme)