DEV Community

Cover image for Kervan: MCP servers from a YAML file or TypeScript
Itachi Uchiha
Itachi Uchiha

Posted on

Kervan: MCP servers from a YAML file or TypeScript

#ai #opensource #mcp #showdev

I've been building Kervan for a while.

It turns HTTP APIs into tools AI assistants can use. You describe the API in a short YAML file (or write tools in TypeScript if you prefer) and Kervan serves them as an MCP server that your AI client, such as Claude Code, can call.

The same tool, two ways

Here's a weather tool written in YAML. This is a complete kervan.yaml:

specVersion: 1
name: weather
version: 0.1.0
tools:
  - name: get_current_weather
    description: Current temperature (°C) and wind speed (km/h) at a latitude and longitude.
    input: { type: object, properties: { lat: { type: number }, lon: { type: number } }, required: [lat, lon] }
    http:
      url: https://api.open-meteo.com/v1/forecast
      query: { latitude: "{{input.lat}}", longitude: "{{input.lon}}", current: "temperature_2m,wind_speed_10m" }
    output: { select: "current" }
Enter fullscreen mode Exit fullscreen mode

And the same tool in TypeScript, on the official MCP SDK:

import { createApp, z } from "@kervan/core"
import { serve } from "@kervan/transport/node"

const app = createApp({ name: "weather", version: "0.1.0" })
app.tool("get_current_weather", {
  description: "Current temperature (°C) and wind speed (km/h) at a latitude and longitude.",
  input: z.object({ lat: z.number(), lon: z.number() }),
  handler: async ({ lat, lon }) => {
    const url = `https://api.open-meteo.com/v1/forecast?latitude=${lat}&longitude=${lon}&current=temperature_2m,wind_speed_10m`
    return JSON.stringify((await (await fetch(url)).json()).current)
  },
})

await serve(app)
Enter fullscreen mode Exit fullscreen mode

Use YAML when the tool is just an HTTP call. Use TypeScript when you want to write the handler yourself. Both get the same checks.

Try it 

npm create kervan@latest my-server
npx kervan@latest dev kervan.yaml
Enter fullscreen mode Exit fullscreen mode

The server runs over stdio or HTTP. There's a guide for connecting it to Claude Code on the site.

Safe by default

  • Spec tools can only reach public addresses
  • Secrets stay out of results, errors and logs
  • Every call has a timeout

Also

  • It speaks the stateless MCP 2026-07-28 revision and serves clients of the 2025 revisions from the same app.
  • Kervan Studio is an optional self-hosted web UI for managing servers, secrets, users and logs. The framework works without it.

It's version 0.1, so feedback is very welcome.

Top comments (0)