What MCP is, and what Kervan adds

The Model Context Protocol (MCP) is an open protocol that lets AI applications use tools and data from other programs. Kervan is a framework for writing the server side.

On this page

MCP in one paragraph

An AI application such as Claude Code is an MCP client. It connects to MCP servers, asks what tools they offer, and lets the model call them. A tool has a name, a description the model reads to decide when to use it, a JSON Schema for its arguments, and a result. The messages are JSON-RPC, carried over stdio (the client starts the server as a process) or Streamable HTTP (the server listens on a URL). The specification is at modelcontextprotocol.io.

What a server answers

This is what a real server answers when a client asks for its tools: the example server of this project, recorded from a run of kervan run.

tools/list result (recorded)

{
  "_meta": {
    "io.modelcontextprotocol/serverInfo": {
      "name": "open-meteo",
      "version": "0.1.0"
    }
  },
  "cacheScope": "private",
  "resultType": "complete",
  "tools": [
    {
      "annotations": {
        "openWorldHint": true,
        "readOnlyHint": true
      },
      "description": "Finds up to 5 places by name and returns their coordinates.",
      "inputSchema": {
        "properties": {
          "name": {
            "description": "City name, e.g. Ankara",
            "maxLength": 100,
            "minLength": 2,
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "type": "object"
      },
      "name": "search_city",
      "title": "Search city"
    },
    {
      "annotations": {
        "openWorldHint": true,
        "readOnlyHint": true
      },
      "description": "Current temperature (°C), wind speed (km/h) and WMO weather code at a coordinate.",
      "inputSchema": {
        "properties": {
          "latitude": {
            "maximum": 90,
            "minimum": -90,
            "type": "number"
          },
          "longitude": {
            "maximum": 180,
            "minimum": -180,
            "type": "number"
          }
        },
        "required": [
          "latitude",
          "longitude"
        ],
        "type": "object"
      },
      "name": "get_current_weather",
      "outputSchema": {
        "properties": {
          "temperatureC": {
            "type": "number"
          },
          "weatherCode": {
            "type": "integer"
          },
          "windKmh": {
            "type": "number"
          }
        },
        "required": [
          "temperatureC",
          "windKmh",
          "weatherCode"
        ],
        "type": "object"
      },
      "title": "Current weather"
    }
  ],
  "ttlMs": 0
}

And a call of one of those tools, with its result:

tools/call request (recorded)

{
  "id": 4,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/clientCapabilities": {},
      "io.modelcontextprotocol/protocolVersion": "2026-07-28"
    },
    "arguments": {
      "latitude": 39.92,
      "longitude": 32.85
    },
    "name": "get_current_weather"
  }
}

tools/call result, October 8, 2026

{
  "_meta": {
    "io.modelcontextprotocol/serverInfo": {
      "name": "open-meteo",
      "version": "0.1.0"
    }
  },
  "content": [
    {
      "text": "{\"temperatureC\":21.1,\"windKmh\":5.9,\"weatherCode\":2}",
      "type": "text"
    }
  ],
  "resultType": "complete",
  "structuredContent": {
    "temperatureC": 21.1,
    "weatherCode": 2,
    "windKmh": 5.9
  }
}

What Kervan adds

The official MCP SDK implements the protocol. Kervan is a thin layer over it (@modelcontextprotocol/server v2) that takes care of what every server needs:

Tools without code. A kervan.yaml spec turns HTTP API calls into tools: templates for the request, a JMESPath select for the result.
Tools in TypeScript with Zod schemas, when you need logic: tools in TypeScript.
Validation and error masking. Invalid arguments come back to the model as an error it can fix; internal errors are masked with a reference.
Limits and protection on by default: timeouts, size and rate limits, Host and Origin checks, and for spec tools SSRF protection and secret redaction.
Both protocol eras from one app: the stateless 2026-07-28 revision and the 2025 revisions.
A development loop: kervan dev reloads on save without dropping the client, with a REPL.