Serveur MCP

unmap expose un serveur Model Context Protocol à https://api.unmap.dev/mcp, pour qu'un agent puisse chercher des lieux canadiens et calculer des trajets sans que vous écriviez un client HTTP. C'est la même API derrière la même clé : un client MCP n'est qu'un client de plus, authentifié, limité en débit et facturé exactement comme curl.

Le transport est Streamable HTTP et la clé voyage en jeton porteur. La plupart des clients attendent ce bloc JSON :

{
  "mcpServers": {
    "unmap": {
      "type": "http",
      "url": "https://api.unmap.dev/mcp",
      "headers": { "Authorization": "Bearer um_live_..." }
    }
  }
}

Il vous faut d'abord une clé ; Authentification explique comment en créer une. Il n'y a ni accès anonyme ni parcours OAuth : un humain crée la clé dans le tableau de bord et la confie à l'agent, ce que /auth.md explique à un agent qui arrive sans clé.

Pour vérifier la connexion à la main :

curl https://api.unmap.dev/mcp \
  -H "Authorization: Bearer $UNMAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Les huit outils

identify n'est pas geocode_reverse. Le géocodage inverse trouve les lieux nommés les plus proches d'un point; identify retourne les polygones qui contiennent ce point. Pour « dans quelle municipalité suis-je », c'est identify; pour « quelle est l'adresse ici », c'est geocode_reverse.

Il vaut la peine d'appeler list_layers avant de promettre une couche à un utilisateur. La couverture est décrite honnêtement couche par couche et plusieurs ne couvrent qu'une province : le catalogue fait la différence entre un agent qui dit « Colombie-Britannique seulement » et un qui ne retourne rien sans explication.

Tous sont en lecture seule. Aucun outil n'écrit quoi que ce soit, et aucun ne peut engager de dépense au-delà de l'appel facturé lui-même.

Les arguments reprennent ceux des points de terminaison REST sous des noms plus clairs : query pour q, language pour lang, et un seul coordinate, near, from, to ou center sous forme de tableau [longitude, latitude] (la forme chaîne "lng,lat" est également acceptée). geocode_nearby prend categories sous forme de tableau, et isochrone prend minutes de même. Un mauvais argument revient dans un résultat en erreur que le modèle peut lire et corriger, plutôt qu'en erreur de protocole qu'il ne voit pas.

Ce qui est volontairement absent

• Tuiles, styles, glyphes et sprites. La seule chose utile qu'un outil pourrait renvoyer est une URL de style contenant votre clé, ce qui est un identifiant à fuiter, pas un outil à appeler. Pour afficher une carte, construisez l'URL vous-même. La page est l'API de cartes, et la compétence unmap-map-styles ci-dessous dit la même chose pour un agent.
• /geocode/autocomplete. Il classe uniquement sur la correspondance des termes et la notoriété : c'est le bon point de terminaison pour une frappe dans un champ de saisie et le mauvais pour tout le reste. L'offrir à côté de geocode_search le ferait surtout choisir par erreur.
• Ressources et invites. Le serveur déclare tools et rien d'autre.

Facturation

Un tools/call est une requête facturée, comptée sur le service utilisé : un geocode_search tombe dans votre usage de géocodage, un route dans votre usage de routage, exactement comme l'appel REST. Le trafic de protocole (initialize, tools/list) est compté aussi, sous mcp. Voir Forfaits et limites.

Contrairement aux points de terminaison REST, les appels d'outils MCP n'utilisent pas le cache de géocodage de 24 heures. Le trafic d'agents est de faible volume, et un second cache indexé autrement que le premier est une seconde chose susceptible de servir un corpus périmé.

Détails du protocole

Le serveur est sans état : pas d'identifiant de session, un message JSON-RPC par requête, une réponse par requête. Un GET sur le point de terminaison répond 405, car en Streamable HTTP un GET ouvre un flux d'événements du serveur vers le client, et il n'y a rien à y pousser.

Les révisions 2025-03-26, 2025-06-18, 2025-11-25 et 2026-07-28 du protocole sont toutes négociées, et initialize comme son remplaçant de 2026-07-28, server/discover, reçoivent une réponse : un client d'une génération récente se connecte sans cas particulier.

Trois documents décrivent le serveur à une machine, tous sans authentification :

curl https://api.unmap.dev/mcp/server-card        # carte de serveur SEP-2127
curl https://unmap.dev/.well-known/ai-catalog.json # découverte au niveau du domaine
curl https://unmap.dev/.well-known/agent-skills/index.json

La carte de serveur porte l'identité du serveur, son transport et les révisions du protocole qu'il parle. Elle est servie à l'emplacement réservé <streamable-http-url>/server-card et, à l'identique, à /.well-known/mcp/server-card.json sur les deux hôtes. Elle n'énumère délibérément pas les outils : un document statique ne peut pas décrire honnêtement une surface qui peut varier, donc tools/list sur une connexion vivante fait autorité.

Le catalogue IA à unmap.dev/.well-known/ai-catalog.json est le point d'entrée au niveau du domaine ; il nomme la carte plutôt que de la répéter.

L'index Agent Skills n'est pas du MCP. Il publie quatre compétences en Markdown (unmap-quickstart, unmap-geocoding, unmap-routing, unmap-map-styles) qui apprennent à un agent à appeler l'API HTTPS ordinaire, y compris les parties que MCP ne couvre pas. Un agent sans client MCP, ou qui doit afficher une carte, peut les lire à la place.

Prochaines étapes

• API de géocodage et API de routage pour ce que fait chaque outil en dessous, y compris les lacunes de couverture à connaître avant de s'y fier.
• Erreurs pour tous les statuts que l'API peut renvoyer.