Kervan
Search
Color theme

Search

Search Kervan's documentation and guides, or browse the full list of pages; the framework, Kervan Studio, the guides and the changelog.

    All pages

    Kervan framework documentation

    • Kervan framework documentation: Concepts of the Kervan MCP framework, a TypeScript layer over the official MCP SDK; tools from a kervan.yaml spec or code, transports, the CLI.
    • Quickstart: Build Kervan from source, serve the example kervan.yaml spec as an MCP server, call its tools from a REPL, and create a TypeScript project of your own.
    • How Kervan works: The packages of the Kervan MCP framework and what each one does, what happens to a tool call from client to result, and how tools change while a server runs.
    • YAML or TypeScript?: When to describe an MCP tool in kervan.yaml and when to write it in TypeScript with Kervan; the same tool both ways, what each gives you, and how to mix them.
    • kervan.yaml reference: Every field of a kervan.yaml spec with its type, default and limits, generated from the editor JSON Schema, plus how templates and errors work.
    • HTTP tools: How a kervan.yaml tool turns its arguments into an HTTP request; methods, URL paths, query strings, headers, JSON bodies, timeouts, redirects and limits.
    • Input and output: How a spec tool's input schema becomes the arguments a model sends, and how select, output schemas and raw output turn an API response into the tool result.
    • select and its limits: Use JMESPath select expressions in kervan.yaml to pick and reshape API responses, with examples, limits and the sandboxed process they run in.
    • Secrets and environment variables: How a kervan.yaml spec uses API keys and other secrets from environment variables, binds them to hosts, and keeps them out of results, errors and logs.
    • Tools in TypeScript: Write MCP tools in TypeScript with @kervan/core, Zod input and output schemas, the tool context, ToolError, middleware and a registry that changes at runtime.
    • Errors: How a Kervan MCP tool reports failures; ToolError messages reach the model, every other error is logged with a reference and masked from the client.
    • Middleware: Run code around every Kervan MCP tool call or around one tool's calls; logging, timing, permission checks and result changes, inside the call's timeout.
    • A registry that changes at runtime: Add, replace and remove Kervan MCP tools while clients are connected; the tool registry, list_changed notifications, and custom registries for many tenants.
    • Testing: Test Kervan MCP tools in memory with createTestClient and the official SDK client, for 2026-07-28 and 2025-era clients, without starting a server.
    • Programmatic API: Every export of @kervan/core, @kervan/transport, @kervan/spec-runtime and the kervan CLI package, with its stability; stable exports follow semver from 0.1.
    • Transports and authentication: Serve a Kervan MCP server over stdio or stateless Streamable HTTP, on Node or as a standard fetch handler, with Host and Origin checks and authentication.
    • MCP 2026-07-28 notes: What the stateless MCP 2026-07-28 revision changes and how Kervan serves it next to 2025-era clients; _meta on every request, server/discover, list_changed.
    • CLI reference: The kervan command line, generated from its --help output; kervan create for new projects, kervan dev with hot reload and a REPL, kervan run to serve a spec.
    • Deployment: Run a Kervan MCP server in production; supported Node.js versions, a Dockerfile draft for a spec server, binding and allowed hosts, a TLS reverse proxy.
    • Security model: What the Kervan MCP framework protects against: SSRF protection for spec tools, Host and Origin checks, limits, error masking and secret redaction.
    • Troubleshooting: Common Kervan errors and their fixes: Node.js versions, spec load errors, refused addresses, Host checks, secrets, timeouts and missing tools.
    • Versioning and upgrades: How Kervan versions its packages and the kervan.yaml format; semver for stable exports from 0.1, specVersion and schema versions, and how to upgrade a project.

    Guides

    • Guides: Step-by-step guides to building MCP servers with Kervan; from a YAML file, from a REST API, connecting Claude Code, and self-hosting a multi-user gateway.
    • What MCP is, and what Kervan adds: The Model Context Protocol explained in plain terms; servers, tools, clients and transports, and what the Kervan framework adds on top of the official MCP SDK.
    • Build an MCP server from a YAML file: Step by step, write a kervan.yaml that turns the public Hacker News API into two MCP tools, check it, try it in a REPL, and serve it over stdio or HTTP.
    • Expose a REST API as MCP tools: Turn REST endpoints into MCP tools with Kervan: query strings, path parameters, a JSON POST body, an output schema, and API keys kept out of logs.
    • Connect a Kervan server to Claude Code: Add a Kervan MCP server to Claude Code with claude mcp add, as a local stdio server or over HTTP, check that it connects, and remove it; with Windows notes.
    • Self-host a multi-user MCP gateway: Run Kervan Studio as a self-hosted MCP gateway for a team: install, master key, first admin, a published server, an API key and Claude Code.

    Kervan Studio documentation

    • Kervan Studio documentation: Kervan Studio is an optional self-hosted web app to write, publish and serve kervan.yaml MCP servers for a team, with a secret vault and audit.
    • Install and the first admin: Run Kervan Studio from a clone, set the master key, create the first admin with the one-time setup token or the create-admin command, and sign in.
    • The data directory and the master key: Kervan Studio keeps its data in one SQLite file and encrypts secrets with a master key you hold. Lose the key and stored secrets are gone; back up both, apart.
    • Create and edit servers: Create a server in Kervan Studio, write its kervan.yaml in the editor with completion and validation, save immutable versions and compare them line by line.
    • Publish, roll back and disable: Publishing a version in Kervan Studio updates the gateway in place; roll back by publishing an older version, or disable a server without deleting anything.
    • The secret vault: Kervan Studio stores upstream API keys encrypted and write-only, bound to the hosts they may be sent to, and checks every call and redirect against the binding.
    • API keys, the gateway and connecting: Every published Kervan Studio server is an MCP endpoint at /s/<serverId>/mcp. Create an API key, connect Claude Code with bash, zsh or PowerShell, revoke keys.
    • Playground: Kervan Studio's playground connects a real MCP client to any version of a server, drafts too, through the gateway with a 15-minute token; list and call tools.
    • Leaving Studio, export as kervan.yaml: Every Kervan Studio server exports as a kervan.yaml file that runs with kervan run, with its secret bindings and without secret values; nothing is locked in.
    • Users and roles: Kervan Studio has admins and members; what each role may do, adding users, role changes, password resets, deactivation and the last-admin rule.
    • Profile, sessions and theme: Each Kervan Studio user's profile; the display name, changing the password, the list of active sessions to sign out, and a light, dark or system theme.
    • Call logs: Kervan Studio logs every tool call through its gateway with tool, caller, status and duration; arguments and results only if an admin enables it, redacted.
    • Audit log: Kervan Studio's append-only audit log records sign-ins, user changes, servers, publishes, secrets and API keys; never a password, key or secret value.
    • Settings and configuration: Kervan Studio's settings page and environment variables: public URL, host, port, data directory, master keys, proxies and log retention.
    • Backup, restore and upgrades: Back up Kervan Studio's SQLite database while it runs, restore it with the right master key, and upgrade Studio with forward-only migrations.
    • Security and threat model: Kervan Studio's full threat model: actors, assets, the attacks it is designed against, from secret exfiltration and SSRF to CSRF, and known limits.
    • Known limits: What Kervan Studio does not do: one process, API keys instead of OAuth, no push to 2025-era HTTP clients, 100 audit entries, no sub-path.
    • Troubleshooting: Common Kervan Studio problems; it does not start, the setup page is unreachable, sign-in is locked, clients get 401 or 404, or a publish is refused.

    Project