MCPHubs

The MCP gateway that doesn't overwhelm your AI.

中文文档

Why MCPHubs?

MCP is powerful — but naive aggregation is not. When you wire up 10+ MCP Servers, your LLM is force-fed hundreds of tool definitions on every single request — burning tokens, inflating costs, and degrading decision quality.

MCPHubs fixes this with Progressive Disclosure.

Instead of dumping every tool into the system prompt, MCPHubs exposes a lean surface of just 3 meta-tools. Your AI discovers servers, inspects their capabilities, and calls the right tool — all on demand, with zero upfront overhead.

┌─────────────────────────────────────────────────────────────────────┐
│                        Without MCPHubs                              │
│                                                                     │
│  AI System Prompt:                                                  │
│  ├── tool_1 definition (search)              }                      │
│  ├── tool_2 definition (fetch_article)       }  150 tool schemas    │
│  ├── tool_3 definition (create_issue)        }  = ~8,000 tokens     │
│  ├── ...                                     }  EVERY request       │
│  └── tool_150 definition (run_analysis)      }                      │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                         With MCPHubs                                │
│                                                                     │
│  AI System Prompt:                                                  │
│  ├── list_servers    "discover servers (with search)" }              │
│  ├── list_tools      "inspect a server's tools"      }  3 tools     │
│  └── call_tool       "invoke any tool"               }  ≈ 300 tokens│
│                                                                     │
│  AI discovers and calls the right tool when needed. Not before.     │
└─────────────────────────────────────────────────────────────────────┘

How Progressive Disclosure Works

MCPHubs collapses all your MCP Servers into 3 meta-tools:

The AI explores your tool ecosystem on demand — it calls list_servers to see what's available, drills into a server with list_tools, and invokes the right tool via call_tool. No upfront cost, no bloat.

Scales to hundreds of servers. list_servers returns up to 20 results by default, along with the total count. When the AI sees more servers exist than shown, it automatically narrows results with the optional query parameter — no extra tools needed.

Don't need progressive disclosure? Set MCPHUBS_EXPOSURE_MODE=full and MCPHubs becomes a straightforward aggregation gateway — all tools from all servers exposed directly.

✨ Features

ModelScope Integration

🏗 Architecture

AI Client ──▶ Streamable HTTP ──▶ MCPHubs Gateway ──┬─ stdio servers
                                       │            ├─ SSE servers
                                  PostgreSQL         └─ HTTP servers
                                       │
                                  Web Dashboard

🚀 Quick Start

Docker Compose (Recommended)

git clone https://github.com/7-e1even/MCPHubs.git && cd MCPHubs
cp .env.example .env        # edit as needed
docker compose up -d

Open http://localhost:3000 — login with admin / admin123.

Local Development

Backend:

pip install -r requirements.txt
cp .env.example .env
python main.py serve

Frontend (dev):

cd web
npm install
npm run dev

Frontend (production):

cd web && npm install && npm run build && npm run start

🔌 Connect Your AI Client

Add MCPHubs as a single MCP endpoint:

Cursor / Windsurf

{
  "mcpServers": {
    "mcphubs": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Claude Code

claude mcp add --transport http mcphubs http://localhost:3000/mcp

With API Key authentication:

claude mcp add --transport http --header "Authorization: Bearer YOUR_API_KEY" mcphubs http://localhost:3000/mcp

VS Code

{
  "mcp": {
    "servers": {
      "mcphubs": {
        "type": "streamable-http",
        "url": "http://localhost:3000/mcp"
      }
    }
  }
}

That's it. Your AI now has access to every tool on every server through progressive discovery — without seeing any of them upfront.

⚙️ Configuration

📡 Management API

# List all servers
curl http://localhost:8000/api/servers

# Register a new server
curl -X POST http://localhost:8000/api/servers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -d '{"name": "my-server", "transport": "sse", "url": "http://10.0.0.5:3000/sse"}'

# Export config (claude / vscode / generic)
curl http://localhost:8000/api/servers/export?format=claude

# Health check
curl http://localhost:8000/api/health

📄 License

MIT