MCP Hub

What mcp-hub MCP server does

The mcp-hub MCP server places multiple MCP backends behind one gateway instead of requiring a separate container and authentication layer for each server. It accepts server definitions in the same mcpServers structure used by Claude Code, allowing existing entries to be reused with little restructuring.

Each configured server receives a path-based HTTP endpoint such as https://host/server-name. The /hub endpoint offers one aggregate connection with six meta-tools: list_servers, list_tools, get_tool_schema, call_tool, wake_server, and sleep_server. This lets a client discover and call backend tools without loading every server's complete schema into its context.

The gateway can also expose the aggregate over standard input and output with --stdio. That mode is intended for clients able to launch a local process, while HTTPS endpoints serve remote or connector-style clients.

How it works

The mcp-hub MCP server starts stdio and Docker-backed servers when they are needed and can put them to sleep after 60 idle minutes. A persistent snapshot lets the hub answer initialization and tool-list requests while a server is asleep. keepAlive: true prevents an individual server from sleeping, and IDLE_TIMEOUT_MINUTES=0 disables the hub's idle behavior.

A supervisor pings child processes, restarts failed processes with exponential backoff, and returns HTTP 503 when a server is unavailable. A server that repeatedly crashes without active users is parked rather than restarted indefinitely. Changes to mcp.json are hot-reloaded, with only affected servers being started, stopped, or restarted.

Tool exposure can be narrowed per server with allowTools and denyTools. These settings accept exact tool names or list_* prefixes. Filtered tools are omitted from listings and rejected if called directly, including before the target server is started.

Every endpoint supports MCP revisions 2026-07-28 and 2025-11-25; the client selects the revision. The gateway translates subscription behavior for children speaking either revision and can relay elicitation on the newer revision. Per-server settings can disable subscriptions or elicitation passthrough.

Setup and configuration

Configuration is supplied as mcp.json using Claude Code's mcpServers format. The repository also includes a disposable demo with three fake servers. Running docker compose up -d starts that demo, which can then be inspected with MCP Inspector or MCPJam.

For network access, the mcp-hub MCP server publishes Streamable HTTP endpoints and includes an OAuth 2.1 authorization server protected by one password. Client registration can use a Client ID Metadata Document, dynamic registration, or credentials issued with mcp-hub-admin clients add. The CLIENT_REGISTRATION setting can disable the registration mechanisms.

Remote upstreams may define an oauth block. The hub can register with an upstream and refresh its token, including support for upstream client_credentials. When interactive authorization is needed, mcp-hub-admin upstream login prints a URL. Clients that cannot use OAuth can use long-lived API tokens.

Local process clients can run the aggregate with --stdio; this path does not use TLS or login because its trust boundary is the local user. The gateway stores state in one JSON file and a signing key under /data, and does not require a database.

Tools and capabilities

• Aggregate discovery through list_servers, list_tools, and get_tool_schema.
• Backend invocation through call_tool.
• Explicit process lifecycle control through wake_server and sleep_server.
• Path-based access to individual configured servers.
• Per-server allowlists and denylists for exposed tools.
• OAuth 2.1 for client access and OAuth handling for remote upstreams.
• Change notifications for child tools, prompts, and resources.
• Elicitation relay on the newer MCP revision.
• Stateless Streamable HTTP without session tables.