# mcp-hub [Health: Active]

**Category:** 🔗 Aggregators  
**Repository:** https://github.com/ni-c/mcp-hub  
**GitHub Stars:** 5  
**npm Downloads (last month):** 2145  
**Views:** 8  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-hub

## Description
Many stdio MCP servers from one container, published over HTTPS with OAuth 2.1 for any MCP client

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-hub": {
    "command": "npx",
    "args": ["-y","@ni-c/mcp-hub"]
  }
}
```

## Documentation

## What mcp-hub does

mcp-hub consolidates multiple MCP servers behind one gateway. It can launch stdio and Docker-based servers on demand, connect to remote upstreams, and publish the resulting tools through Streamable HTTP. Each configured server receives a path such as `/paperless`, while `/hub` presents one aggregate endpoint for reaching all configured servers.

The aggregate endpoint avoids loading every server's tool schema into the model context at once. Its six meta-tools let a client list servers, inspect available tools and schemas, call a tool, or wake and sleep a server. Clients that can run a local process can use the same aggregate through `mcp-hub --stdio`.

## How it works

Configuration follows the `mcpServers` structure used by Claude Code, allowing existing server entries to be reused. The gateway supervises child processes, restarts failed children with exponential backoff, and returns a 503 response when a server is unavailable. Configuration changes are hot-reloaded, affecting only the servers that changed.

Stdio and Docker servers can be started when first needed and put to sleep after 60 minutes without activity. Their tool metadata remains available from a persistent snapshot while they are asleep. `keepAlive: true` prevents an individual server from sleeping, while `IDLE_TIMEOUT_MINUTES=0` disables the hub-wide idle behavior.

Every endpoint supports the MCP revisions `2026-07-28` and `2025-11-25`, with the client selecting the revision. The gateway translates subscription behavior between these revisions and can forward elicitation requests from child servers on the newer revision. Server-level settings can disable elicitation or subscriptions.

## Setup and configuration

The deployment is a single Node process or container. Network access uses HTTPS and OAuth 2.1, protected by one password. Client registration supports Client ID Metadata Documents and dynamic registration for older clients; administrator-issued credentials are available for clients that support neither approach. `CLIENT_REGISTRATION` can disable either registration mechanism.

Remote servers can define an `oauth` configuration so the hub obtains and refreshes upstream tokens. Depending on the upstream, authentication can use issued credentials, dynamic registration, a client metadata document, or the client-credentials flow. Interactive upstream authorization is initiated with `mcp-hub-admin upstream login`.

The local `--stdio` mode does not use TLS or login because its trust boundary is the local user. It uses the same MCP server configuration and exposes the aggregate endpoint through standard input and output.

## Tools and capabilities

- Route each configured server through its own HTTP path.
- Aggregate servers behind `/hub` with `list_servers`, `list_tools`, `get_tool_schema`, `call_tool`, `wake_server`, and `sleep_server`.
- Restrict exposed tools with `allowTools` and `denyTools`, including exact names and `list_*` prefixes.
- Apply filtering both when listing tools and when rejecting direct calls to filtered tools.
- Keep child processes alive, restart failed processes, and park unused crash-looping servers.
- Pass tool, prompt, and resource change notifications between clients and children.
- Support long-lived API tokens for clients that cannot use OAuth.
- Store state in a JSON file and signing key under `/data`, without a database.

## Limitations and notes

Tool filtering is configured per server and applies before a sleeping server is woken. A server that requires reauthorization is reported as `unauthorized` through the hub. Sleeping servers do not maintain active subscriptions; they are prompted to re-read state when they wake.

The gateway is designed for MCP servers whose entries fit the Claude Code `mcpServers` format. Its HTTP endpoints are stateless Streamable HTTP endpoints, so connection state is not kept in a session table. Clients that cannot spawn local processes should use the HTTP deployment, while clients that support local process spawning can use `--stdio`.

_Full upstream README: https://allmcps.com/mcp/mcp-hub/readme_

