Self-host a multi-user MCP gateway

One Studio process gives a team a shared set of MCP servers behind one gateway, with users, an encrypted secret vault and an audit log. This guide goes from nothing to a connected client.

Kervan Studio is the optional web app of the Kervan project. The commands below are checked against a fresh data directory, except the HTTPS steps, which need a public DNS name; the screenshots come from a Studio filled with demo data.

1. Build and start

git clone https://github.com/aligoren/getkervan.git kervan
cd kervan
corepack enable
pnpm install
pnpm build

Create a master key and keep it outside the data directory. Without it, stored secrets cannot be recovered (why).

The first command writes a new key into .env.studio (not on screen, not in shell history; copy it to your password manager), the second starts Studio with it:

node -e "require('fs').writeFileSync('.env.studio', 'KERVAN_STUDIO_MASTER_KEY=' + require('crypto').randomBytes(32).toString('base64') + '\n', { mode: 0o600, flag: 'wx' })"

node --env-file=.env.studio apps/studio/bin/kervan-studio.js start

2. The first admin

Studio prints a one-time setup token and listens on 127.0.0.1:4310 only. Open http://127.0.0.1:4310/setup and create the admin, or do it from the shell (also how it works in a container):

node --env-file=.env.studio apps/studio/bin/kervan-studio.js create-admin --email admin@example.com

It asks for the password twice without showing it. Studio then listens on KERVAN_STUDIO_HOST.

3. Put it behind HTTPS

For a team, run Studio behind a TLS proxy with its public URL. With Caddy on the same machine:

studio.example.com {
	reverse_proxy 127.0.0.1:4310
}

KERVAN_STUDIO_PUBLIC_URL=https://studio.example.com KERVAN_STUDIO_TRUST_PROXY=1 node --env-file=.env.studio apps/studio/bin/kervan-studio.js start

Details and the other settings: configuration.

4. A server, its secrets, published

Create a server, paste or write its kervan.yaml, save, and publish. Secrets the spec uses are added by an admin on the Secrets tab, bound to the hosts they may reach.

Try it in the playground before anyone connects.

5. An API key, and a client

On API keys, create a key for the server. Studio shows it once, with commands that add the server to Claude Code; the bash/zsh and PowerShell versions read the key without echoing it.

claude mcp add --transport http weather https://studio.example.com/s/<serverId>/mcp \
  --header "Authorization: Bearer $KERVAN_API_KEY"

6. Add the team

Admins add people on Users: members write and publish specs, admins also manage people, secrets and keys. See users and roles.

What you get

• One endpoint per server, /s/<serverId>/mcp, with per-server keys you can revoke.
• Call logs and an audit log.
• No lock-in: every server exports as kervan.yaml.