MCPHubs

The MCP gateway that doesn't overwhelm your AI.

中文文档 · Quick Start · Connect AI · Configuration

The Problem

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.

The Solution: 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 It 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

💻 CLI

Call MCP tools directly from your terminal — no AI client needed.

npm i -g mcphubs
mcphubs config --url http://localhost:8000 --token "YOUR_ADMIN_TOKEN"

# Install and manage servers
mcphubs install github -e GITHUB_TOKEN=xxx -- npx -y @modelcontextprotocol/server-github
mcphubs install --transport sse remote-server http://example.com/sse
mcphubs install --from claude_desktop_config.json
mcphubs remove github

# Call and run
mcphubs list                                        # List all servers
mcphubs tools github                                # List tools for a server
mcphubs call github.search_repositories query=test  # Call a tool

The CLI uses the Admin Token (Settings → Security), not the MCP API Key. See CLI docs for details.

🚀 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

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

cd web
npm install
npm run dev

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

🤝 Contributing

Contributions are welcome! Feel free to open issues and pull requests.

📄 License

MIT