Synsema docsENES

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.

mcp-server.syn
-- 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)

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: [...]}:

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:

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).

Safety — run untrusted tool input sandboxed

If your MCP server runs code or input you don't trust, put a host ceiling 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.