No description
  • TypeScript 95.8%
  • Nix 2.6%
  • CSS 0.6%
  • JavaScript 0.6%
  • Dockerfile 0.2%
  • Other 0.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Martí Comas Canal 2fe0b0d8c2
Some checks failed
CI / check (push) Failing after 1m29s
Merge pull request 'develop' (#61) from develop into main
Reviewed-on: #61
2026-11-16 22:56:05 +01:00
.claude build: wire trail for agents 2026-11-05 21:21:13 +01:00
.forgejo/workflows ci: run checks on the forgejo nix runner 2026-11-05 21:30:21 +01:00
.trail docs(trail): learnings on change events, /mcp auth, runner capabilities and SPA freshness 2026-11-16 22:43:56 +01:00
apps refactor(api): name LATEST_VERSION and ARGS_RULE instead of repeating them 2026-11-16 22:43:28 +01:00
docs refactor: a shared process's connect error lives in its tool-list row only 2026-11-16 22:40:42 +01:00
nix test(nix): cover nftables and an old Docker in the sandbox VM tests 2026-11-13 01:22:02 +01:00
packages/shared refactor: a shared process's connect error lives in its tool-list row only 2026-11-16 22:40:42 +01:00
scripts fix(ci): put the throwaway Postgres where nobody can reach it 2026-11-06 01:06:00 +01:00
.dockerignore build: add mcphub dockerfile 2026-11-05 21:22:51 +01:00
.editorconfig build: scaffold npm workspaces, biome and dev postgres 2026-11-05 21:14:18 +01:00
.env.example test(nix): cover nftables and an old Docker in the sandbox VM tests 2026-11-13 01:22:02 +01:00
.envrc build: wire trail for agents 2026-11-05 21:21:13 +01:00
.gitattributes build: scaffold npm workspaces, biome and dev postgres 2026-11-05 21:14:18 +01:00
.gitignore build: scaffold npm workspaces, biome and dev postgres 2026-11-05 21:14:18 +01:00
.nvmrc build: scaffold npm workspaces, biome and dev postgres 2026-11-05 21:14:18 +01:00
AGENTS.md test(nix): cover nftables and an old Docker in the sandbox VM tests 2026-11-13 01:22:02 +01:00
biome.json build: keep markdown out of biome and fix remaining lint 2026-11-05 21:49:03 +01:00
CLAUDE.md docs: describe the architecture and agent workflow 2026-11-05 21:14:18 +01:00
compose.gvisor.yaml feat!: remove RUNNER_MODE=docker; compose runs a locked-down runner 2026-11-06 09:39:24 +01:00
compose.yaml test(nix): cover nftables and an old Docker in the sandbox VM tests 2026-11-13 01:22:02 +01:00
Dockerfile build: add mcphub dockerfile 2026-11-05 21:22:51 +01:00
flake.lock build(nix): drop trail-code from the flake and devShell 2026-11-14 02:40:29 +01:00
flake.nix build(nix): drop trail-code from the flake and devShell 2026-11-14 02:40:29 +01:00
lefthook.yml ci: add workflow, dependabot and lefthook hooks 2026-11-05 21:21:07 +01:00
opencode.json build: keep markdown out of biome and fix remaining lint 2026-11-05 21:49:03 +01:00
package-lock.json refactor: remove dead code and unused exports 2026-11-16 20:06:39 +01:00
package.json fix(crypto): make an encryption key rotation safe to finish 2026-11-13 00:41:16 +01:00
README.md docs: state the Docker Engine 28 requirement of the prod profile 2026-11-13 00:58:12 +01:00
tsconfig.base.json build: scaffold npm workspaces, biome and dev postgres 2026-11-05 21:14:18 +01:00

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 /mcp endpoint (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.