Kervan
Search
Color theme

Kervan framework documentation

Kervan is a TypeScript framework for Model Context Protocol (MCP) servers, built on the official MCP SDK. Tools come from a kervan.yaml spec or from code, on the same validated, timed core.

Where this fits: The start of the framework book. Every other page goes deeper into one part; the quickstart runs a server first.

On this page

What Kervan is

An MCP server offers tools that a model can call: a name, a description, a JSON Schema for the arguments, and a handler that returns a result. Kervan is the layer between your tools and the official SDK (@modelcontextprotocol/server v2):

  • You describe tools, either in a kervan.yaml file (an HTTP request per tool, no code) or in TypeScript with Zod schemas.
  • Kervan handles the rest: argument validation, output schemas, error masking, timeouts, size limits, change notifications, and the stdio and Streamable HTTP transports.
  • The protocol is the SDK’s. Kervan does not reimplement MCP.

How it is organized

Three libraries (@kervan/core, @kervan/transport, @kervan/spec-runtime), the kervan command line and create-kervan. How Kervan works shows which does what and the path a tool call takes; YAML or TypeScript? helps you choose how to write your tools.

This book follows the same order:

Concepts

  • Tool: a name ([A-Za-z0-9_.-], up to 128 characters), a description the model reads, an input schema, an optional output schema, annotations (readOnlyHint, destructiveHint, …) and a handler.
  • Spec: a kervan.yaml file that declares tools as HTTP requests. Every spec tool compiles to an ordinary code tool, so anything a spec does can also be done in code. See the kervan.yaml reference.
  • App: what createApp() returns: the tools, middleware and limits of one server.
  • Transport: how clients reach the app: stdio (a client starts your server as a process) or Streamable HTTP. See transports and authentication.
  • Registry: the set of tools an app serves. It can change while the server runs; connected clients are told with list_changed.

Looking for the optional web UI? See Studio docs.