MCPHub
MCPHub is a self-hosted gateway between AI clients and multiple MCP servers, combining endpoint aggregation, group routing, access control, credential isolation, runtime logs, and optional vector-based smart routing.
Project overview
MCPHub is a self-hosted gateway and control plane placed between AI clients and multiple MCP servers. It exposes all servers, a group, one server, or Smart Routing through separate unified endpoints, while one web dashboard manages authentication, visibility, personal credentials, runtime status, and logs. It is team-level MCP infrastructure rather than a single tool server. Before adoption, define the upstream permission, secret-storage, activity-log, and network-exposure boundaries.
Core capabilities
Unified MCP endpoints
Aggregate configured servers at /mcp, or restrict access to a group or one server through /mcp/{group} and /mcp/{server}.
Authentication and access control
Supports bearer keys, JWT, MCP OAuth, and Better Auth, with server visibility set to private, group, or public.
Per-user credential isolation
Administrators declare environment-variable or header credential slots; each user's values are encrypted with AES-256-GCM and injected into an isolated runtime.
Smart tool routing
Indexes tool names, descriptions, and parameters, searches them by vector similarity at the $smart endpoint, and can restrict discovery to a group.
Dashboard and runtime visibility
The web dashboard shows server status, logs, and activity; /health is unauthenticated, while database mode can persist tool-call activity.
Setup and connection
The recommended starting point is one Docker instance with a persistent data directory and a least-privilege upstream test server. Add PostgreSQL, pgvector, and an embedding service only when Smart Routing or multiple instances are required.
Let an AI Agent install it
Send this prompt to Codex, Claude Code, or another AI agent that can work with your local environment.
Help me deploy MCPHub v1.0.36 from https://github.com/samanhappy/mcphub. First read the README plus the quickstart, authentication, per-user-credentials, and monitoring documents. Prefer Docker with a persistent data directory. Generate strong random ADMIN_PASSWORD, JWT_SECRET, and MCPHUB_CREDENTIAL_ENCRYPTION_KEY values and inject them through secret management; do not write them to version control or chat. Start with one low-privilege test MCP server, then verify /health, administrator login, the server list, and the tool list. Do not enable skipAuth, Smart Routing, or production credentials unless I explicitly authorize it. Ask before exposing a public port, mounting a sensitive directory, changing existing configuration, calling an external embedding service, or requesting extra permissions.- Docker is available and host port 3000 is free
- Prepare a strong random dashboard password and inject it through the environment or a secret manager
- If mounting a configuration file, prepare mcp_settings.json in the current directory
- Review the file, command, network, and credential permissions required by every upstream MCP server
- Smart Routing additionally requires PostgreSQL, pgvector, and a compatible embedding service
docker run -p 3000:3000 -v ./mcp_settings.json:/app/mcp_settings.json -v ./data:/app/data samanhappy/mcphub- 1Prepare minimal configuration and secrets
Check the port and persistent data directory, then prepare separate random secrets for the administrator, JWT sessions, and personal-credential encryption. Keep them out of Git.
- 2Start a persistent Docker instance
Run the documented Docker command. If no custom server is ready, omit the mcp_settings.json mount initially but keep the persistent data volume.
- 3Sign in and add a low-privilege server
Open http://localhost:3000, sign in as the administrator, add a test server that needs no production secret, and restrict its visibility.
- 4Connect a client and verify scope
Point an MCP client at http://localhost:3000/mcp or a narrower group or server endpoint. Confirm it lists and calls only the expected tools.
- 5Upgrade the operating mode only when needed
Move to PostgreSQL only for multiple instances, persistent activity, Better Auth, or Smart Routing. Review the embedding provider's data policy before enabling Smart Routing.
After the container starts, open http://localhost:3000 and sign in with the password from first-run logs or the configured password. Add one minimal test server, then run `mcphub servers list` and `mcphub tools list`. The base installation is verified when that server and its tools appear and /health reports a healthy service.
- Without ADMIN_PASSWORD, first launch prints a random administrator password to logs; save it promptly and restrict log access.
- Set JWT_SECRET explicitly in production, because a generated value invalidates sessions after restart and cannot be shared across replicas.
- Persist and back up the credential-encryption key; losing it makes existing personal credentials unreadable.
- Never enable skipAuth where untrusted users can reach the service.
Use cases
One MCP ingress for a team
Several clients maintain one gateway address while administrators centrally update server definitions, aliases, and visibility.
Groups by team or environment
Use /mcp/{group} to isolate development, staging, production, or department tools behind distinct endpoints and access scopes.
Shared server definitions with personal secrets
A team shares one upstream server template while each user supplies a private API key or header that is isolated at runtime.
Semantic discovery across large tool catalogs
In PostgreSQL mode, query $smart in natural language and use progressive disclosure to avoid loading every full parameter schema into context.
Assessment
MCPHub turns scattered MCP servers into centrally governed shared infrastructure. Unified endpoints, groups, per-user credentials, and a straightforward Docker path make gradual team adoption practical. The tradeoff is that one gateway now concentrates privileged tools, secrets, and call content, so operational and audit responsibility also becomes centralized. The repository is active and v1.0.36 continues to improve credential handling and stability, but activity is not a substitute for an independent security review.
Why it may be useful
- Covers stdio, SSE, and Streamable HTTP upstream transports
- Provides global, group, single-server, and Smart Routing endpoints
- Encrypted per-user credentials reduce secret mixing in shared configuration
- Documents Docker, npm, and local-development paths
- Uses a clear Apache-2.0 license and has recent releases and commits
What to know first
- No SECURITY.md or public vulnerability-reporting workflow
- Database activity records can persist complete request inputs and response outputs
- Smart Routing depends on a database and an external or self-hosted embedding service
- Built-in visibility is not a complete metrics, tracing, and alerting stack
- An overprivileged centralized gateway amplifies upstream MCP permission risk
README
MCPHub
Overview
MCPHub is a self-hosted gateway between AI clients and multiple MCP servers, combining endpoint aggregation, group routing, access control, credential isolation, runtime logs, and optional vector-based smart routing. Self-hosted MCP gateway and control plane for connecting, controlling, and operating MCP servers.
Getting started
- The recommended starting point is one Docker instance with a persistent data directory and a least-privilege upstream test server. Add PostgreSQL, pgvector, and an embedding service only when Smart Routing or multiple instances are required.
- The project is a self-hosted MCP gateway and control plane that exposes all servers, a group, one server, or Smart Routing through separate MCP endpoints.
- Servers can use stdio, SSE, or Streamable HTTP. The dashboard manages servers, groups, aliases, access control, logs, health, and hot updates.
- After the container starts, open http://localhost:3000 and sign in with the password from first-run logs or the configured password. Add one minimal test server, then run `mcphub servers list` and `mcphub tools list`. The base installation is verified when that server and its tools appear and /health reports a healthy service.
Configuration
docker run -p 3000:3000 -v ./mcp_settings.json:/app/mcp_settings.json -v ./data:/app/data samanhappy/mcphub