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.846714,"longitude":4.352514,
        "language":"fr","country":"BE"
      }
    }
  }'

You get back the common envelope: a quotable text paragraph (shortened here), structured facts, warnings and metadata. Every distance comes with the mode it was measured in, see how distances are computed.

{
  "text": "Transports: Vivre près de la Grand-Place - Grote Markt offre un cadre de vie pratique, avec un accès facilité aux commerces, transports et services [...]",
  "facts": {
    "nearestSchool": {
      "name": "Cefa - Centre Scolaire Eperonniers-Mercelis",
      "distanceMeters": 363,
      "travelMode": "cycling"
    },
    "nearestNursery": {
      "name": "César De Paepe",
      "distanceMeters": 551,
      "travelMode": "transit"
    },
    "nearestSupermarket": {
      "name": "Carrefour Express Gare Central",
      "distanceMeters": 257,
      "travelMode": "transit"
    },
    "transport": {
      "linesCount": 14,
      "nearestStopDistanceMeters": 233,
      "nearestStopTravelMode": "walking"
    },
    "place": {
      "street": "Grand-Place - Grote Markt",
      "city": "Bruxelles - Brussel",
      "zip": "1000"
    }
  },
  "warnings": [],
  "metadata": {
    "country": "BE",
    "language": "FR",
    "generatedAtUtc": "2026-09-21T12:45:41Z"
  }
}

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.