---
slug: 42-mcp
title: MCP servers
description: Build MCP (Model Context Protocol) servers in Synsema — expose tools, data and existing APIs to any AI agent (Claude, Cursor…) over JSON-RPC, safely sandboxed.
example_ids: [mcp-server]
---

# MCP servers

**MCP** (Model Context Protocol) lets an AI agent — Claude, Cursor, any MCP client — call **tools** and read **data** you expose. It's **JSON-RPC**, and Synsema's native `serve` + JSON make it a **one-route** server.

```synsema
-- Doc example: a minimal MCP server (Model Context Protocol) in Synsema. MCP is JSON-RPC;
-- the `serve` wiring is one route (shown in the prose). Here the handler is a pure function,
-- so it's doctestable — press Test.
intent: "doc example: MCP server handler"

task rpc(id, result)
    give {"jsonrpc": "2.0", "id": id, "result": result}

-- one tool: greet(name)
task tool_greet(args)
    give {"content": [{"type": "text", "text": "Hello, " + args["name"] + "!"}]}

-- the JSON-RPC dispatcher: initialize / tools/list / tools/call
task mcp(req)
    let id be req["id"]
    when req["method"] == "initialize"
        give rpc(id, {"protocolVersion": "2025-06-18", "serverInfo": {"name": "demo", "version": "1.0"}, "capabilities": {"tools": {}}})
    otherwise when req["method"] == "tools/list"
        give rpc(id, {"tools": [{"name": "greet", "description": "Greet someone", "inputSchema": {"type": "object", "properties": {"name": {"type": "string"}}, "required": ["name"]}}]})
    otherwise when req["method"] == "tools/call"
        let p be req["params"]
        when p["name"] == "greet"
            give rpc(id, tool_greet(p["arguments"]))
        otherwise
            give rpc(id, {"content": [{"type": "text", "text": "unknown tool"}], "isError": true})
    otherwise
        give rpc(id, {})

test "initialize returns serverInfo + protocol version"
    let r be mcp({"id": 1, "method": "initialize", "params": {}})
    assert_eq((r["result"])["protocolVersion"], "2025-06-18")

test "tools/call greet returns text content"
    let r be mcp({"id": 2, "method": "tools/call", "params": {"name": "greet", "arguments": {"name": "Ada"}}})
    assert_eq((((r["result"])["content"])[0])["text"], "Hello, Ada!")
```

## Wire it to `serve` (one route)

```synsema
require serve(8080)
serve on 8080
    route "POST /mcp"
        give mcp(json of request)
```

That's a complete MCP server: any MCP client that speaks HTTP connects to `http://…/mcp`. The core methods are `initialize`, `tools/list` and `tools/call`.

## Tools that do real work

A tool is just a task. Give it a real body — query a DB, compute, call an API — and return `{content: [...]}`:

```synsema
task tool_orders(args)
    require db("./store.db")
    let rows be sql("SELECT id, total FROM orders WHERE customer = ?", [args["customer"]])
    give {"content": [{"type": "text", "text": json_encode(rows)}]}
```

Add it to `tools/list` (with an `inputSchema`) and dispatch it in `tools/call`.

## Turn an old API into MCP (a converter)

Wrap an existing REST API as an MCP tool — the agent gets a clean, typed tool; you keep your API untouched:

```synsema
require net("api.legacy.com")
require secret("LEGACY_KEY")

task tool_weather(args)
    let r be http_get("https://api.legacy.com/v1/weather",
        {"x-api-key": secret("LEGACY_KEY")}, {"city": args["city"]})
    give {"content": [{"type": "text", "text": body of r}]}
```

Register it, dispatch it — your legacy API is now MCP-native, and the secret stays redacted (see **[Secrets](/en/0.6.x/21-secrets)**).

## Safety — run untrusted tool input sandboxed

If your MCP server runs code or input you don't trust, put a **[host ceiling](/en/0.6.x/20-capabilities)** on the execution (`--cap-set`). This docs site's own MCP endpoint (`/mcp`) exposes `run_synsema`/`test_synsema` tools that run snippets in exactly that sandbox — so an agent can **verify** the Synsema it writes, safely.