Kervan
Search
Color theme

Kervan Studio

An optional, self-hosted web app on top of the Kervan framework. People write specs in the browser, keep upstream API keys in an encrypted vault, publish versions, and MCP clients connect through one gateway.

Not required: the framework works without it. Studio is a separate app in the same repository. It uses only the framework's public API, and nothing in the framework depends on it. Every server exports as kervan.yaml and runs with kervan run.

When it helps

  • Several people write and change tools, and you want roles (admins and members) instead of shared files.
  • Upstream API keys should live in one encrypted place, bound to the hosts that may receive them, and never be shown again.
  • MCP clients should connect through one gateway with an API key per server, and you want to see the calls.
  • You want versions you can publish and roll back, with a record of who did what.

If you write specs in a repository and run kervan run, you do not need Studio.

The weather server's editor with its kervan.yaml, published as version 2, and the playground beside it.
Edit a spec with completion and validation from the editor schema.
The playground calling the search_city tool of the weather server: the tool list, the arguments and the result from Open-Meteo.
Try any version in the playground before clients see it.
The versions tab: saved versions with their validation state, the published one marked.
Every save is a version; publish one, roll back to an older one.
The secrets tab of a server: two secrets with the hosts they may be sent to; values are never shown.
Secrets are write-only and bound to the hosts that may receive them.
The calls tab: recent tool calls with the caller, status, duration and the logged arguments.
Calls through the gateway are logged; payloads only when an admin turns it on.
The audit log: who created servers, secrets and API keys, published versions and signed in, with the client address.
An audit log of who changed what.

What it does

  • Servers and versions: a kervan.yaml per server, edited in the browser; saving makes an unchangeable version; publishing validates it strictly and updates the gateway in place; rolling back publishes an older version.
  • Gateway: each published server at /s/<server id>/mcp, for any MCP client, with an API key per server (only its hash is stored).
  • Secret vault: AES-256-GCM under a master key you keep outside the database; each secret bound to hosts; values never shown again.
  • Playground: a real MCP client for any version, drafts included, with a 15-minute token.
  • Users and roles: admins and members, deactivation, password resets, sessions you can see and end.
  • Call logs and audit log: metadata for every call, arguments and results only when turned on; a log of changes the database refuses to edit or delete.
  • Export: any version as kervan.yaml, to run with kervan run.

Getting started

Studio runs from a clone of the repository, with Node.js 22.23.3 or a later 22.x, or 24.21.0 or later, and pnpm. It keeps its data in one SQLite file and needs a master key you create once and keep safe. Install Studio and create the first admin, then read the data directory and the master key.

Security

Studio adds to the framework's protections: sign-in throttling, sessions in HttpOnly cookies, CSRF tokens and exact origin checks on every change, the admin's own password for sensitive changes, and Host and Origin checks on the gateway. Spec tools served through it get the same SSRF protection and secret redaction as anywhere else. The Studio threat model lists what it protects against and what it does not.

Documentation