- TypeScript 95.8%
- Nix 2.6%
- CSS 0.6%
- JavaScript 0.6%
- Dockerfile 0.2%
- Other 0.2%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
Some checks failed
CI / check (push) Failing after 1m29s
Reviewed-on: #61 |
||
| .claude | ||
| .forgejo/workflows | ||
| .trail | ||
| apps | ||
| docs | ||
| nix | ||
| packages/shared | ||
| scripts | ||
| .dockerignore | ||
| .editorconfig | ||
| .env.example | ||
| .envrc | ||
| .gitattributes | ||
| .gitignore | ||
| .nvmrc | ||
| AGENTS.md | ||
| biome.json | ||
| CLAUDE.md | ||
| compose.gvisor.yaml | ||
| compose.yaml | ||
| Dockerfile | ||
| flake.lock | ||
| flake.nix | ||
| lefthook.yml | ||
| opencode.json | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| tsconfig.base.json | ||
mcphub
mcphub hosts MCP servers (stdio packages run through npx/uvx in a sandbox container, plus remote HTTP servers) and exposes all of them to each user through one OAuth-protected /mcp endpoint.
Admins decide who can use which server, users fill in their own credentials, and agents (Claude Code, Codex, Claude Desktop, ChatGPT) connect once and see every tool they are allowed to use.
Features
- One
/mcpendpoint (Streamable HTTP) with OAuth 2.1: dynamic client registration, Client ID Metadata Documents, PKCE, refresh token rotation. - stdio servers from npm and PyPI run inside a hardened runner container: per-process uid, no host mounts, cpu/memory/pid limits, no route to the database.
- Remote Streamable HTTP and SSE servers with templated URLs and headers.
- Per-server variables with instance scope (admin) or user scope (each user), secrets encrypted at rest and write-only through the API.
- Admin UI for servers, access, users and clients; a portal where users set their own values, follow their own tool calls, and connect or revoke clients.
- Everything the admin UI does is also a REST API (OpenAPI 3, Swagger UI at
/api/docs, personal API tokens) and, when switched on, an admin MCP endpoint at/mcp/admin. - One-click update of a stdio server to its newest release (or the newest commit of a git branch).
- Local accounts or OIDC single sign-on with group-based admin promotion.
- Audit log of admin actions and a per-call usage log (never arguments or results).
Stack
- TypeScript, npm workspaces:
packages/shared,apps/api,apps/runner,apps/web - Fastify, Drizzle ORM, PostgreSQL 18
- React, Vite, Tailwind, daisyUI
- Docker Engine 28+ for the runner container (Podman through the NixOS module; optionally gVisor)
Quick start
1. Docker Compose (production-like)
Needs Docker Engine 28.0 or later: the sandbox network uses an option older engines refuse or ignore (docs/deployment.md).
cp .env.example .env
# set ENCRYPTION_KEY, RUNNER_TOKEN, POSTGRES_PASSWORD and PUBLIC_URL in .env (commands are in the file)
docker compose --profile prod up -d --build # postgres, migrate, mcphub, runner, egress
docker compose logs mcphub | grep -i "setup token"
Open http://localhost:8080/setup and create the first admin with the setup token from the log. See docs/deployment.md for TLS, backups and upgrades. On NixOS, the flake exports nixosModules.default, which builds both images with Nix and runs them as OCI containers (docs/deployment.md#nixos).
2. Plain npm on the host
Prerequisites: Node 24, Docker (or Podman), see docs/installation.md.
docker compose up -d postgres
cp .env.example .env # fill ENCRYPTION_KEY and RUNNER_TOKEN
npm ci
npm run db:migrate
docker compose --profile dev up -d runner-dev # the runner on 127.0.0.1:58090
npm run dev:api # terminal 1, prints the setup token
npm run dev:web # terminal 2
Open http://localhost:5173.
3. Nix
nix develop # node 24, psql 18, docker client, uv, trail, ...
docker compose up -d postgres
cp .env.example .env && npm ci && npm run db:migrate
npm run dev:api & npm run dev:web
Connecting an agent
Every client needs only the URL https://<your-host>/mcp (PUBLIC_URL plus /mcp) and signs in through the browser the first time.
| Client | How |
|---|---|
| Claude Code | claude mcp add --transport http mcphub https://<your-host>/mcp, then /mcp inside Claude Code to authenticate |
| Codex | codex mcp add mcphub --url https://<your-host>/mcp, then codex mcp login mcphub |
| Claude Desktop | Settings, Connectors, Add custom connector, paste the URL |
| ChatGPT | Settings, Connectors, developer mode, create a connector with the URL (needs a publicly reachable https PUBLIC_URL) |
Tools appear as <server-slug>__<tool>. A built-in mcphub__status tool tells the agent which servers still need setup in the portal.
Common commands
| Task | Command |
|---|---|
| Dev database | docker compose up -d postgres |
| Dev API / web | npm run dev:api, npm run dev:web |
| Build everything | npm run build |
| Test | npm test (API tests need the dev database) |
| Lint, format, typecheck | npm run lint, npm run format, npm run typecheck |
| Migrate, seed | npm run db:migrate, npm run db:seed -w @mcphub/api |
| New migration | npm run db:generate -- --name <what> |
Layout
apps/api Fastify API, OAuth server, /mcp gateway
apps/runner sandbox supervisor that runs inside the runner container
apps/web React SPA
packages/shared Zod contracts shared by all three
docs/ installation, development, deployment, configuration, architecture
Documentation
Configuration comes from the environment; .env.example lists every variable.