MCPHub: one JSON config, five client routes, and two auth switches that do not match
Self-hosted MCP gateway and control plane for connecting, controlling, and operating MCP servers.
At a glance
- What is it?
- MCPHub puts a stable endpoint in front of many MCP servers and adds bearer keys, a dashboard and per user credentials. The happy path is well trodden, while the committed build files show the parts that need a decision first: architecture dependent browsers, zeros that switch limits off, and a first run password printed to the log.
- Who is it for?
- MCPHub fits a team that already juggles several MCP servers and wants one address for clients, one place for keys, and one log to read; it does not fit a single server setup, where the gateway costs more configuration than it saves.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- samanhappy/mcphub2,692 ★ · +285
| Repository | 2026-09-11 | 2026-11-15 |
|---|---|---|
| samanhappy/mcphub | 2.4k | 2.7k |
285 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
One mounted directory holds settings, users and credentials
The Docker command is one line, and the only thing it mounts is a directory:
docker run -p 127.0.0.1:3000:3000 -v ./data:/app/data samanhappy/mcphubIn the default file-backed mode, the mounted directory holds settings, users and credential bindings. Protect that directory and backups because they can contain sensitive configuration. The dashboard is then served at http://localhost:3000. Servers can be declared two ways, and the order matters. Before the first launch you can write data/mcp_settings.json yourself, and the smallest version is a map of server names to a command and its arguments:
{
"mcpServers": {
"time": {
"command": "npx",
"args": ["-y", "time-mcp"]
},
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
}
}
}Those two entries explain why the published image is as heavy as it is: one shells out through npx to a package name, the other through uvx, so the runtime needs both Node and a Python package runner present. After the first launch the dashboard takes over, or you edit the same file and restart. A four file examples directory covers the cases the two line sample cannot, including mcp_settings_with_env_vars.json, oauth-server-config.json, oauth-dynamic-registration-config.json, and openapi-schema-config.json.
Five client routes, and one of them starts with a dollar sign
Clients are pointed at five path shapes under the same port:
http://localhost:3000/mcp # All servers
http://localhost:3000/mcp/{group} # Specific group
http://localhost:3000/mcp/{server} # Specific server
http://localhost:3000/mcp/$smart # Smart routing
http://localhost:3000/mcp/$smart/{group} # Smart routing within groupThe point of the scheme is that a client keeps one address while servers are added, removed, or regrouped underneath it, since aliases and routing decide what each path exposes. The fifth entry is the odd one. Smart routing is not a query parameter or a flag, it is a literal path segment with a dollar sign in front of it, and it can also be narrowed to a group. The feature list describes that mode as AI powered tool discovery using vector semantic search, which means the hub has to pick one server's tools out of many before the client asks for them. The dependency list carries a Hugging Face tokenizers package and a Google generative AI client alongside the MCP client library, so the embedding side of that search lives in this process. Whatever the ranking returns is still an ordinary tool call, so a wrong pick shows up as a wrong tool rather than an error.
Two authentication switches that do not control the same thing
The security surface is governed by settings whose names read alike and cover different ground. MCP endpoints require authentication by default so that a gateway is not accidentally exposed. Turning off Enable Bearer Authentication in the Keys section is what allows unauthenticated MCP access. Skip Authentication is a separate control, and it only affects dashboard login. Someone reading the two labels quickly could easily protect the wrong one, and the readme's own guidance is to use unauthenticated access only in trusted environments.
A second switch decides whether there is a web surface at all. Setting DISABLE_WEB=true skips serving the bundled dashboard and leaves the backend, the API, and the MCP endpoints, which suits deployments where servers are managed straight from mcp_settings.json.
Credentials have their own rough edge. The dashboard login uses the username admin, and if no ADMIN_PASSWORD environment variable is set on first launch, a random password is generated and printed to the server logs. That password can be set up front instead:
# Docker: set admin password via environment variable
docker run -p 127.0.0.1:3000:3000 -v ./data:/app/data -e ADMIN_PASSWORD samanhappy/mcphubSet ADMIN_PASSWORD securely in the environment before running the command, and avoid putting the value in shell history. If a password is generated instead, protect the log stream that contains it. Either way the guidance is to change that password after the first login.
A zero rate limit removes the cap here and does the reverse upstream
The shipped .env.example documents eight rate limiters, all commented out, with the defaults visible:
# AUTH_RATE_LIMIT_MAX=20
# AUTH_RATE_LIMIT_WINDOW_MS=900000
# REGISTER_RATE_LIMIT_MAX=20
# REGISTER_RATE_LIMIT_WINDOW_MS=900000
# API_RATE_LIMIT_MAX=600
# API_RATE_LIMIT_WINDOW_MS=900000
# MCP_RATE_LIMIT_MAX=480
# MCP_RATE_LIMIT_WINDOW_MS=60000
# TEMPLATE_RATE_LIMIT_MAX=200
# TEMPLATE_RATE_LIMIT_WINDOW_MS=900000
# SPA_RATE_LIMIT_MAX=600
# SPA_RATE_LIMIT_WINDOW_MS=60000
# HOSTED_EVENT_RATE_LIMIT_MAX=600
# HOSTED_EVENT_RATE_LIMIT_WINDOW_MS=60000Three details in the surrounding comments are worth carrying into a deployment plan. First, the login limiter counts failed attempts only, so service accounts that re-authenticate when a token expires are never locked out, while the registration limiter counts every request because a successful registration is the thing its cap exists to limit. Second, setting any maximum to 0 or to the string off removes that limit entirely here, and the file says outright that this is not passed through the same way to express-rate-limit, where a limit of 0 rejects every request instead of allowing all of them. Third, disabling a limiter logs a warning at startup, so the log line is the only trace that a cap is gone.
The same zero convention shows up elsewhere in the file. STARTUP_CONNECT_CONCURRENCY=0, or leaving it unset, connects every upstream server in parallel, which the comment calls the previous behaviour. Alongside it sit DEFAULT_REQUEST_TIMEOUT=60000 and INIT_TIMEOUT=300000.
latest-full drops the browsers on anything that is not amd64
Two image variants are published under samanhappy/mcphub, and the difference is bigger than the tag name suggests. latest carries Node.js and pnpm, Python, uv and uvx, Git, and build tools, which covers most MCP servers. latest-full adds a Rust toolchain with Cargo and rustc, the Docker Engine including its CLI and daemon, and Playwright browsers. The build decides all of this behind one argument:
ARG INSTALL_EXT=false
RUN if [ "$INSTALL_EXT" = "true" ]; then \
ARCH=$(uname -m); \
if [ "$ARCH" = "x86_64" ]; then \
npx -y playwright install --with-deps chrome firefox; \
else \
echo "Skipping Chrome and Firefox installation on non-amd64 architecture: $ARCH"; \
fi; \The browser install is the only part inside the architecture check. On arm64 hosts, latest-full still delivers Rust and the Docker Engine, and it prints that it is skipping Chrome and Firefox. The readme describes the extended image as adding Playwright browsers for Chrome and Firefox with amd64 only noted in parentheses, which is accurate but easy to skim past. A Rust MCP server on an Apple Silicon machine will work in latest-full; a browser driven one will not, and the failure will look like a missing browser rather than a wrong tag.
The base layer is equally specific. The build starts from python:3.13-slim-trixie and copies uv and uvx out of a floating tag:
FROM python:3.13-slim-trixie AS base
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/Node comes from a setup script piped into bash, which installs version 22 even though the stated requirement for running from source is Node.js 20.0.0 or newer.
procps was added to stop a stdio process crash
One dependency in the image exists to answer a specific bug report, and the build recipe says so in a comment:
# procps provides `ps`, which tree-kill needs to walk stdio process trees
# (missing it caused spawn ps ENOENT crashes — issue #1072)That single line explains a lot about how stdio servers are run here. A stdio MCP server is a child process, and when a client disconnects or a user binding is revoked the hub has to tear that process down, often as a tree. Walking a process tree means shelling out to ps, which means the container needs procps installed, and leaving it out turned into a spawn ps ENOENT failure at runtime rather than a clean error. The same architecture shows up in the per user credentials feature, where personal keys are bound to one shared server with encrypted storage and isolated stdio runtimes, so several users of the same server get separate process instances to kill.
Two smaller things are visible in the recipe. The extended install block covers Rust, the Docker Engine, and browser downloads in one shell block, and the visible part of that block ends partway through its own cleanup step, after the package index is cleared and a removal begins. And package management is pinned through corepack to pnpm 10.12.4, which matches the version the prerequisites section asks contributors to have.
The manifest ships a CLI, a built frontend, and version dev
The committed package.json describes a package that is assembled at release time rather than authored ready to run. Its version field reads dev while the published tags move through v1.0.45, v1.0.46, and v1.1.0, and three of those releases landed across two days in October 2026 with the newest tag seconds after the last commit. The name is @samanhappy/mcphub, main points at dist/index.js, and type is module.
The files array is the interesting part. A publish carries dist, bin, mcp_settings.json, servers.json, frontend/dist, README.md, and LICENSE, so the tarball ships a compiled frontend and two configuration files rather than source. prepublishOnly runs the build and then node scripts/verify-dist.js, which is the check that the dist directory is real before anything leaves the machine.
The bin field registers a command called mcphub pointing at bin/cli.js, and the scripts block has a cli entry that runs tsx against src/cli/main.ts. No section of the readme walks through that command. The same asymmetry runs through the root directory: there is an articals directory spelled with an a after the t, both .eslintrc.json and eslint.config.mjs side by side, a pnpm-workspace.yaml next to a frontend directory, nginx.conf.example for reverse proxy setups, docker-compose.db.yml for database mode, locales alongside README.fr.md and README.zh.md, and a set of agent instruction files in AGENTS.md, CLAUDE.md, CONTEXT.md, .agents, and .claude.
Single server routes carry the apps proxy, group routes do not
Two transparency features sit next to each other in the feature list, and they do not apply everywhere. The MCP Apps Proxy forwards interactive MCP Apps transparently, but only on single server routes. The /mcp path that exposes everything, and the group paths, are outside that claim. If a client needs the interactive apps to work, the client configuration has to name one server at a time rather than the pooled route, which trades away the main benefit of a gateway for a subset of servers.
Tool Result Compression is broader: it reduces large text tool outputs before they reach clients, and the readme describes it as transparent. Since it acts on responses rather than on a route, it applies wherever tool calls are served, though no threshold or format is stated in the repository.
Persistence has a second mode beyond the mounted directory. Setting DB_URL switches on database mode, which the file says is auto detected, and USE_DB=true overrides the detection. The example value that ships in .env.example is postgresql://mcphub:password@localhost:5432/mcphub, a placeholder credential meant to be replaced, and docker-compose.db.yml at the root wires the same mode as a compose file. Social login is the feature most tied to this: GitHub and Google sign in run through a Better Auth integration, and the readme states that path requires Database Mode, so social login and a single mounted data directory cannot both be had without adding a database.
Editorial conclusion
MCPHub fits a team that already juggles several MCP servers and wants one address for clients, one place for keys, and one log to read; it does not fit a single server setup, where the gateway costs more configuration than it saves. Before deploying, decide whether the MCP endpoints stay behind bearer keys, set ADMIN_PASSWORD yourself instead of reading the first run password out of server logs, pick the image variant that matches your CPU architecture, and check the rate limit defaults against how your clients re-authenticate, because several of those limiters count every request rather than failures.
Frequently asked questions
What is an MCP hub?
The project positions itself as a self hosted MCP gateway and control plane: connect local and remote MCP servers once, then expose them through stable endpoints with authentication, scoped credentials and per user visibility. It names Claude Code, Cursor, Cherry Studio and OpenWebUI as clients it works with.
How do I use docker with mcphub?
Run docker run -p 3000:3000 -v ./data:/app/data samanhappy/mcphub, open http://localhost:3000, and log in as admin. If ADMIN_PASSWORD is not set, a random password is generated and printed to the server logs on first launch.
Do mcphub MCP endpoints require authentication?
Yes, by default, to prevent accidental exposure. Disabling Enable Bearer Authentication in the Keys section is what allows unauthenticated MCP access, while Skip Authentication only affects dashboard login. The readme limits that to trusted environments.
Is MCP a JSON file?
The repository does not define the protocol. What it does ship is JSON configuration: mcp_settings.json holds an mcpServers map of names to a command and args, examples add OAuth and environment variable forms, and servers.json is included in the published file list.
What node and package manager does mcphub need for source runs?
Node.js 20.0.0 or newer and pnpm 10.12.4, and those are only needed to run from source or develop locally. The Docker image handles both for you and installs Node 22 through a setup script, with pnpm 10.12.4 activated through corepack.
What does mcphub do about killing stdio server processes?
Per user credentials use isolated stdio runtimes, and tearing those down means walking process trees. The image installs procps for exactly that reason, since without the ps binary tree-kill hit spawn ps ENOENT crashes, which the build recipe ties to issue #1072.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/samanhappy-mcphub)Star history chart for your README
[](https://hysenlabs.com/projects/samanhappy-mcphub)Was this useful?