Yatmo MCP quick start

From zero to a working Yatmo MCP call in five minutes — with curl, then with a real AI client.

Prerequisites

A Yatmo LicenceKey (the same one you use for the REST API). Don’t have one yet? Get a licence.
curl in your terminal, or any HTTP client.

The MCP protocol uses a small JSON-RPC handshake: initialize → notifications/initialized → tools/list / tools/call. The server returns a Mcp-Session-Id header on initialize that you echo back on every subsequent call.

1. Initialize a session

curl -sS -i -X POST https://mcp.yatmo.com/mcp/v1 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'LicenceKey: YOUR_KEY' \
  --data '{
    "jsonrpc":"2.0","id":1,"method":"initialize",
    "params":{
      "protocolVersion":"2025-06-18",
      "capabilities":{},
      "clientInfo":{"name":"yatmo-probe","version":"0.1"}
    }
  }'

Read the Mcp-Session-Id header from the response — you will need it on every subsequent call:

HTTP/1.1 200 OK
Content-Type: text/event-stream
Mcp-Session-Id: 1A19wBTW1Uabnn-mfZ5QvA

event: message
data: {"result":{"protocolVersion":"2025-06-18","serverInfo":{"name":"Yatmo.McpServer","version":"1.0.0.0"},...},"id":1,"jsonrpc":"2.0"}

Then send the “initialized” notification (no response body, returns 202):

curl -sS -X POST https://mcp.yatmo.com/mcp/v1 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'LicenceKey: YOUR_KEY' \
  -H 'Mcp-Session-Id: 1A19wBTW1Uabnn-mfZ5QvA' \
  --data '{"jsonrpc":"2.0","method":"notifications/initialized"}'

2. List the tools

curl -sS -X POST https://mcp.yatmo.com/mcp/v1 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'LicenceKey: YOUR_KEY' \
  -H 'Mcp-Session-Id: 1A19wBTW1Uabnn-mfZ5QvA' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

The response (inside data: ...) advertises the four Yatmo MCP tools.

3. Call a tool

Get a neighbourhood summary on a real Brussels coordinate (Grand-Place area):

curl -sS -X POST https://mcp.yatmo.com/mcp/v1 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'LicenceKey: YOUR_KEY' \
  -H 'Mcp-Session-Id: 1A19wBTW1Uabnn-mfZ5QvA' \
  --data '{
    "jsonrpc":"2.0","id":3,"method":"tools/call",
    "params":{
      "name":"yatmo_get_location_summary",
      "arguments":{
        "latitude":50.8503,"longitude":4.3517,
        "language":"fr","country":"BE"
      }
    }
  }'

You get back the common envelope — a quotable text paragraph, structured facts, optional warnings and metadata:

{
  "text": "Transports: Ce bien, situé près de Quartier Saint-Jacques …",
  "facts": {
    "nearestSchool":     { "name": "Maria-Boodschaplyceum",        "distanceMeters": 581 },
    "nearestNursery":    { "name": "Crèche Du Béguinage",          "distanceMeters": 473 },
    "nearestSupermarket":{ "name": "Carrefour Express City Anspach","distanceMeters": 129 },
    "transport":         { "linesCount": 14, "nearestStopDistanceMeters": 46 },
    "place":             { "street": "Quartier Saint-Jacques - Sint-Jacobswijk", "city": "Bruxelles - Brussel", "zip": "1000" }
  },
  "warnings": [],
  "metadata": { "country": "BE", "language": "FR", "generatedAtUtc": "…" }
}

Same key as the REST API

Your existing LicenceKey already works here. No separate sign-up, no OAuth. See Authentication for error codes.

Connect an AI client (no shell)

Most MCP-capable AI clients accept a generic remote-MCP configuration:

{
  "mcpServers": {
    "yatmo": {
      "url": "https://mcp.yatmo.com/mcp/v1",
      "headers": { "LicenceKey": "YOUR_KEY" }
    }
  }
}

See Connect an AI client for Claude, Cursor and security guidance.