Yatmo MCP authentication

The Yatmo MCP server uses the same LicenceKey as the REST API. No OAuth, no separate sign-up, no per-tool credentials.

Every request to https://mcp.yatmo.com/mcp/v1 must carry a LicenceKey HTTP header:

LicenceKey: YOUR_KEY

The same header used by the REST API works here. The MCP server forwards the header to the upstream Yatmo API, which is where the key is actually validated — so quotas and country authorisation are counted once, not twice.

Never expose the key to a browser

The LicenceKey grants quota-bearing access to your Yatmo account. Keep it on a server you control or in an MCP client’s secret store. Never embed it in a public website or a mobile client.

Error codes

The server returns standard HTTP status codes. The response body is the common MCP envelope with an error field added — never a stack trace, never an internal field name.

Name	Type	Description
400	bad_request	Invalid input: latitude/longitude out of range, unknown language, unknown country, unknown category, or radius/maxResults out of bounds.
401	unauthorized	Missing or unknown `LicenceKey` header.
403	forbidden	Valid key, but this licence is not allowed to access the requested country or the Summary feature.
429	too_many_requests	Quota or rate-limit exceeded for the 24-hour period.
500	internal_error	Unexpected server error. The response message is intentionally generic; no internal detail is leaked.

Example error envelope:

{
  "text":     "Missing or invalid LicenceKey.",
  "facts":    {},
  "warnings": [],
  "metadata": { "country": "BE", "language": "fr", "generatedAtUtc": "…" },
  "error":    { "code": 401, "type": "unauthorized", "message": "Missing or invalid LicenceKey." }
}

Quotas and rate limits

MCP calls count against the same per-account daily quota as the REST API summary endpoint. The MCP server reuses the upstream cache (7 days per location/language pair), so identical calls return instantly and do not consume extra quota.

Adding a short local cache inside the MCP façade (1 hour) dampens bursty AI-agent traffic on the same coordinate.

Country authorisation

Each tool call must include a country argument (BE, FR, NL, LU, DE, CH, ES, IT, PT, UK, IE, AT). The upstream API rejects the call with 403 if your licence does not include that country — the response will list the countries your licence does cover.

Where to (not) put the key

Do put the key in your MCP client’s secret store, in a server-side proxy you control, or in a CI secret.
Don’t embed the key in front-end JavaScript, mobile apps, public repositories, or chat transcripts.
Don’t pass the key as a tool argument (that would expose it to the LLM’s conversation history). The header pattern keeps it out of the model context.

Yatmo MCP authentication

The LicenceKey header

Error codes

Quotas and rate limits

Country authorisation

Where to (not) put the key