mcphub MCP — Use Cases, Install & Live Demo

Why use it

Key features

Unified /mcp endpoint with per-group (/mcp/{group}) and per-server (/mcp/{server}) routing
Smart router ($smart) uses vector semantic search to pick tools across all servers
Hot-swap config — add/remove servers without restart
OAuth 2.0 (client + server), GitHub/Google social login
Postgres backend for production, SQLite for local

Live Demo

What it looks like in practice

mcphub.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcphub": {
      "command": "npx",
      "args": [
        "-y",
        "mcphub"
      ],
      "_inferred": true
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcphub": {
      "command": "npx",
      "args": [
        "-y",
        "mcphub"
      ],
      "_inferred": true
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcphub": {
      "command": "npx",
      "args": [
        "-y",
        "mcphub"
      ],
      "_inferred": true
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcphub": {
      "command": "npx",
      "args": [
        "-y",
        "mcphub"
      ],
      "_inferred": true
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcphub",
      "command": "npx",
      "args": [
        "-y",
        "mcphub"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcphub": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "mcphub"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add mcphub -- npx -y mcphub

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use mcphub

How to expose 20 MCP servers through one URL for your team

👤 Platform engineers, team leads ⏱ ~30 min intermediate

When to use: Engineers keep copy-pasting local configs and breaking each other's setups.

Prerequisites

Docker and a server with a DNS name — Any cheap VPS works; use Caddy or nginx for TLS
mcp_settings.json listing your servers — Start from the MCPHub sample and add one entry per MCP

Flow

Deploy the hub

Run: docker run -p 3000:3000 -v $PWD/mcp_settings.json:/app/mcp_settings.json samanhappy/mcphub✓ Copied

→ Admin login URL + generated password in logs
Create groups

In the admin UI, create groups 'dev' (github, filesystem, postgres) and 'data' (postgres, bigquery).✓ Copied

→ Groups visible at /mcp/dev and /mcp/data
Distribute the URL

Share https://mcp.yourco.internal/mcp/dev with the team; they add it as a single HTTP MCP in their client.✓ Copied

→ Team members connect with one config line

Outcome: A single operable endpoint replaces 20 per-machine setups.

Pitfalls

Leaking the admin password from Docker logs — Set ADMIN_PASSWORD env var explicitly; rotate on first login
Exposing the hub to the public internet — Put it behind a VPN or require bearer tokens per user

How to let $smart pick the right MCP for a prompt automatically

👤 Teams running too many tools to fit in a single context ⏱ ~15 min advanced

When to use: You have 200+ tools across MCPs and blow past your model's tool budget.

Flow

Enable the $smart endpoint

Point your client at https://hub.example.com/mcp/$smart instead of a specific server.✓ Copied

→ Single meta-tool exposed that routes on intent
Prompt naturally

Find PRs in github.com/org/repo that are waiting on me and put them on my calendar as a 30-min review slot.✓ Copied

→ Hub picks github + google-calendar tools behind the scenes

Outcome: Fewer tools in context, same capability.

Pitfalls

Smart router picks the wrong MCP on ambiguous prompts — Keep the per-group endpoints available as a fallback

How to add a new MCP server to the hub without downtime

👤 Operators ⏱ ~5 min beginner

When to use: A new MCP just dropped and you want it live today without kicking everyone off.

Flow

Edit mcp_settings.json via the UI

In the MCPHub dashboard, add a new server entry and save.✓ Copied

→ Hot reload notification, new tools appear
Assign to a group

Add the new server to the 'data' group.✓ Copied

→ /mcp/data now includes the new tools

Outcome: New MCP online in under a minute, no client reconnects required.

Combinations

Pair with other MCPs for X10 leverage

mcphub + toolhive

Use ToolHive to containerize the individual MCPs, MCPHub to route to them

Register my ToolHive-run github MCP in MCPHub under the 'dev' group.✓ Copied

mcphub + proxy

Expose stdio-only MCPs over HTTP for the hub

Use mcp-proxy to bridge my local stdio MCP to HTTP so MCPHub can mount it.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
(meta) route-by-group	HTTP path /mcp/{group}	Regular use — narrow your blast radius	free
(meta) route-by-server	/mcp/{server}	When you want exactly one server's surface	free
(meta) $smart semantic router	/mcp/$smart	When you have too many tools for context	1 vector search per call

Cost & Limits

What this costs to run

API quota: None imposed by the hub; downstream MCPs keep their own quotas
Tokens per call: Adds ~50 tokens of tool metadata overhead
Monetary: Free (open source, Apache 2.0)
Tip: Use group routes, not $smart, for deterministic behavior and zero extra vector-search cost.

Security

Permissions, secrets, blast radius

Minimum scopes: Bearer token per user Network-level restriction to trusted clients

Credential storage: ADMIN_PASSWORD env var; downstream MCP secrets via mcp_settings.json or secret manager

Data egress: The hub only proxies — your data goes wherever each downstream MCP sends it

Never grant: Public exposure without auth Admin UI on the open internet

Do not check mcp_settings.json into git if it contains credentials — mount as a volume.

Troubleshooting

Common errors and fixes

Cannot log in / password unknown

Check the container logs on first boot for the generated password or set ADMIN_PASSWORD.

Verify: docker logs mcphub | grep -i password

New MCP shows up but no tools

The downstream MCP probably failed to start. Click 'Logs' on the server card.

Smart router returns 'no matching tool'

Reindex the vector store from Settings > Index tools.

OAuth redirect mismatch

Register the exact callback URL in your OAuth provider (must match hub's public URL).

Alternatives

mcphub vs others

Alternative	When to use it instead	Tradeoff
Unla (MCP Gateway)	You want YAML-driven REST-to-MCP conversion plus multi-tenant	Go-based, different operator model
ToolHive	You want container-level isolation per MCP	Focuses on running MCPs, less on routing/aggregation
mcp-proxy	You just need transport bridging, not multi-server aggregation	Single-server; no UI

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills