MCP Hub

MCP Hub acts as a central coordinator that lets you manage multiple MCP servers and connect MCP clients to a single, unified endpoint. It provides a management REST API and a dedicated MCP endpoint, making it easier to control and observe all servers from one place while clients access capabilities through one connection.

How to use

Connect MCP clients to a single endpoint to access all server capabilities. Use the MCP endpoint at /mcp to route requests to the appropriate server and enjoy real-time updates as servers come online, change capabilities, or update resources.

How to install

Prerequisites: You need Node.js (version 18.0.0 or newer) installed on your system.

npm install -g mcp-hub

Configuration and usage notes

You configure MCP Hub using JSON configuration files that describe managed MCP servers. The hub supports two server connection styles: local STDIO servers and remote HTTP/SSE servers. You can provide multiple configuration files, which are merged in order, with later files overriding earlier ones. The hub also supports environment variable substitution and command execution within the configuration using a universal placeholder syntax.

A basic local STDIO server example shows how to run a local MCP server with a command, arguments, and environment variables. A remote HTTP server example shows how to point to a remote MCP endpoint with optional headers.

{
  "mcpServers": {
    "local-server": {
      "command": "${MCP_BINARY_PATH}/server",
      "args": [
        "--token", "${API_TOKEN}",
        "--database", "${DB_URL}",
        "--secret", "${cmd: op read op://vault/secret}"
      ],
      "env": {
        "API_TOKEN": "${cmd: aws ssm get-parameter --name /app/token --query Parameter.Value --output text}",
        "DB_URL": "postgresql://user:${DB_PASSWORD}@localhost/myapp",
        "DB_PASSWORD": "${cmd: op read op://vault/db/password}",
        "FALLBACK_VAR": null
      }
    }
  }
}

Security and authentication

MCP Hub supports OAuth 2.0 with PKCE flow and header-based authentication for API keys or tokens. It also manages authentication and connection management across all managed MCP servers.

Real-time events and monitoring

Real-time updates are delivered to clients via Server-Sent Events (SSE). You can observe hub state changes, server capability updates, tool/resource/prompts list changes, and active workspace events as they happen.

REST API overview

The REST API provides health/status endpoints, server management operations (start/stop/refresh), tool execution, resource access, prompt retrieval, and marketplace interactions. It also streams status updates and events for connected clients.

Troubleshooting tips

Check the health endpoint to verify hub readiness and monitor connected servers. Review SSE events for real-time changes and ensure your configuration files are merged correctly when using multiple config files.

Available tools

tools

Execute MCP tools from any connected server through the unified API

resources

Access resources and resource templates from managed MCP servers

prompts

Get and run prompts from MCP servers and receive structured responses