mcp-hub

<!-- badges: start -->

<br> <br>

<!-- badges: end -->

A dual-era Model Context Protocol (MCP) gateway: it serves many stdio MCP servers from one container, published over HTTPS, and speaks both MCP revisions on every endpoint — 2026-07-28 and 2025-11-25. The client picks, and cannot tell which one it is on from the answers. On the 2026 revision that includes elicitation — a child server's question reaches the person at the far end instead of dying at the gateway (how) — and subscriptions: the hub serves subscriptions/listen to its clients and subscribes to its children on whichever revision they speak, so a server that has never heard of it still reaches a client that speaks nothing else (how).

Lets MCP clients that cannot spawn a local process — ChatGPT connectors, Claude on the Web and in Code, Mistral Le Chat, Cursor, LibreChat and any other Streamable-HTTP client — reach every server behind it, with a built-in OAuth 2.1 login protected by a single password, plus long-lived API tokens for clients that cannot do OAuth (OpenAI Responses API, xAI API, Gemini API). Per-client recipes: client compatibility.

<!-- <picture> is resolved against the colour scheme of the page showing it, so GitHub picks the variant that matches its own theme toggle. npm strips <picture> and <source> when it sanitises the README and keeps the <img>, which is why that fallback brings its own dark card instead of relying on a media query. --> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://mcp-hub.ni-c.de/architecture-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="https://mcp-hub.ni-c.de/architecture-light.svg"> <img src="https://mcp-hub.ni-c.de/architecture.svg" alt="MCP clients connect through a reverse proxy to mcp-hub: one Node process with an OAuth 2.1 authorization server, one path per server plus the /hub aggregate, and a supervisor keeping the stdio children and remote upstreams alive" width="800"> </picture>

Want to poke at it first? demo/ is a throwaway hub with three fake servers — docker compose up -d, then point the MCP Inspector or MCPJam at it. Nothing to configure, nothing to clean up but a volume.

Why

Wrapping each stdio MCP server in its own auth-proxy container costs a full image, an OAuth stack, a hostname and a compose stack per server. mcp-hub replaces N containers with one process:

• Config is exactly Claude Code's mcpServers format — copy entries 1:1.
• Path-based routing: https://host/paperless, https://host/homeassistant, …
• /hub aggregate: register a single connector and reach every server through 6 meta-tools (list_servers, list_tools, get_tool_schema, call_tool, wake_server, sleep_server) without flooding the model context with N×tools schemas.
• Per-server tool filtering: allowTools / denyTools on any server decide which of its tools the hub exposes — exact names or list_* prefixes. A filtered tool is hidden from tools/list and refused if a client calls it anyway, before the server is even woken, so a client holding a stale schema cannot reach it.
• Also without HTTP: mcp-hub --stdio serves that same aggregate on stdin/stdout for clients that can only spawn a local process (Claude Desktop, Codex, …) — same mcp.json, no TLS, no reverse proxy, no login. Auth exists for the network endpoints; over stdio the trust boundary is the local user.
• On-demand lifecycle: stdio and docker servers start when used and sleep after 60 idle minutes, answering initialize/tools/list from a persistent snapshot meanwhile — a dozen servers cost only the memory of the ones in use. keepAlive: true exempts a server, IDLE_TIMEOUT_MINUTES=0 the hub.
• CIMD-first OAuth 2.1: clients identify themselves with a Client ID Metadata Document — the registration-free path the MCP spec now prefers — including private_key_jwt against the keys in their own document (metadata-document clients only). RFC 7591 dynamic registration stays advertised beside it for older clients, mcp-hub-admin clients add issues credentials by hand for anything that can do neither, and CLIENT_REGISTRATION turns either mechanism off.
• OAuth outwards, too: a remote server that speaks OAuth gets an oauth block instead of a static header. The hub registers itself — with credentials the upstream issued, via RFC 7591, or with its own client metadata document — then obtains and refreshes the token. client_credentials upstreams need no attention at all; where a person must sign in, mcp-hub-admin upstream login prints one URL. An upstream that needs re-authorizing shows up as one server unauthorized, not as a confusing 401 in your client.
• Supervision: children are pinged and restarted with exponential backoff when they die. A down server answers 503, not silence; a crash-looping server nobody uses is parked instead of restarted forever.
• Hot reload: edits to mcp.json start/stop/restart only the affected servers.
• Stateless Streamable HTTP: no session state, so claude.ai's reconnect-without-DELETE behaviour cannot leak processes or memory.
• Dual-era: every endpoint — /hub, /<name>/mcp and --stdio — answers MCP 2026-07-28 and 2025-11-25 alike; the client picks and cannot tell from the answers which it got. On the 2026 revision that includes elicitation: a server asking the user something returns the question rather than pushing it, so it reaches the person at the far end instead of dying at the gateway. The hub attributes it to the server that asked, strips what could lie about that, drops embedded sampling and roots requests, and seals the resumption state against the call it belongs to. passthrough: "off" withdraws one server's right to ask; details.
• Change notifications, in both eras: a client opens a subscriptions/listen stream and hears when a child's tools, prompts or resources change. The hub subscribes to each child the way that child understands — subscriptions/listen to a 2026 server, resources/subscribe to a 2025 one — so the era gap is the gateway's problem rather than either end's. The state is the open response, not a session table, so this costs the stateless design nothing. A sleeping server watches nothing and is told to re-read on waking; subscriptions: "off" withdraws one server's right to push; details.
• Lightweight by design: one Node process, no database (state is one JSON file plus a signing key under /data), ten runtime dependencies, and multi-arch images — a stated project goal is to run comfortably on a single-board computer like a Raspberry Pi.

Servers to run behind it

The hub is server-agnostic — it serves any stdio MCP server whose entry fits Claude Code's mcpServers format, which is most of them. These nineteen are built and maintained alongside it, so their documentation carries the hub entry you need and their tool filters line up with the hub's own allowTools / denyTools:

| Server | npm | What it reaches | | ---------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------ | | audiobookshelf-mcp | audiobookshelf-mcp | Audiobookshelf — libraries, listening progress, collections and playlists | | caldav-mcp | @ni-c/caldav-mcp | CalDAV — events, tasks and journal entries on any server that speaks it | | calibreweb-mcp | calibreweb-mcp | Calibre-Web — read-only library access through the OPDS feed | | carddav-mcp | @ni-c/carddav-mcp | CardDAV — contacts, groups and photos on any server that speaks it | | freshrss-mcp | @ni-c/freshrss-mcp | FreshRSS — feeds, categories and articles as plain text, not stream ids | | google-search-console-mcp | @ni-c/google-search-console-mcp | Google Search Console — properties, sitemaps, search analytics, URL inspection | | healthchecks-mcp | healthchecks-mcp | Healthchecks — cron and uptime checks, and why one failed | | hetzner-dns-mcp | hetzner-dns-mcp | Hetzner Cloud DNS — zones, record sets and BIND import/export | | imap-mcp | @ni-c/imap-mcp | IMAP mailboxes — read, search, organise and draft mail; it cannot send | | linkwarden-mcp | linkwarden-mcp | Linkwarden — bookmarks, collections and the article text it preserved | | mealie-mcp | @ni-c/mealie-mcp | Mealie — recipes, meal plans, shopping lists and cookbooks | | ntfy-mcp | @ni-c/ntfy-mcp | ntfy — publish and update notifications, manage users and topic access | | opengist-mcp | opengist-mcp | Opengist — gists, revisions, commit history and raw files | | osm-mcp | osm-mcp | OpenStreetMap — geocoding, routing, isochrones and POI search | | rustpad-mcp | rustpad-mcp | Rustpad — collaborative pads edited through real OT, not