Serveur MCP de 2GIS : comment empêcher les LLM d'inventer des adresses et des coordonnées

2GIS a publié un serveur MCP (mcp-2gis) — un outil qui connecte directement les agents IA aux services de géolocalisation de la plateforme API de 2GIS. Il comporte actuellement six outils : recherche de lieux et d'organisations, géocodage direct, géocodage inverse, calcul d'itinéraires, isochrones et cartes statiques.

Le problème que résout ce serveur est classique pour les LLM : sans outils connectés, un modèle interrogé sur un itinéraire ou l'organisation la plus proche répond avec assurance — et invente tout. L'étape suivante semble évidente : donner au modèle un accès aux données géographiques réelles. En pratique, l'accès seul ne suffit pas : une fois doté d'outils, le modèle commence à mentir différemment. Il peut appeler l'outil de manière incorrecte, transmettre des paramètres erronés ou mal interpréter le résultat. Et c'est bien plus difficile à repérer, car cela paraît plus convaincant.

Architecture : un socle commun et des adaptateurs légers

La décision clé est une architecture scalable. Plutôt que de rendre chaque outil entièrement autonome avec sa propre gestion des erreurs, sa journalisation et ses pools HTTP, 2GIS a divisé le système en couches :

1. Middleware FastMCP — authentification, liste blanche, métriques, timeouts 2. tools/<domain>.py — schéma MCP, validation Pydantic des entrées/sorties, mapping du résultat 3. tools/gis.py — dépendances de lifespan et frontière commune de gestion des erreurs 4. integrations/<domain>_api.py — URL, paramètres et interaction JSON avec l'API 2GIS spécifique 5. integrations/gis_client.py — pool httpx commun pour toutes les requêtes, injection de la clé API, conversion des erreurs HTTP

Chaque couche ne gère que sa propre responsabilité. Le module d'intégration reçoit l'URL et le schéma d'interaction avec l'API, mais ne voit ni les en-têtes, ni l'environnement, ni le MCP lui-même. L'outil ne crée pas de pools HTTP et ne lit pas de variables d'environnement. Cette séparation réduit la duplication et permet d'ajouter de nouveaux outils ou serveurs MCP sans copier-coller des tonnes de code.

Côté appelant

Une fonction d'assistance unique, `run_gis_tool`, rassemble toutes les dépendances, ouvre un span pour l'outil et traduit les erreurs selon deux contrats distincts. C'est l'implémentation d'une exigence critique : une erreur métier (clé invalide, absence d'accès) doit parvenir à l'agent comme résultat d'outil avec un code lisible par machine, et non comme une panne de protocole. Sinon, le modèle ne comprend pas quoi faire et rappelle l'outil indéfiniment.

Une panne réseau ou un timeout, en revanche, doit impérativement rester une erreur MCP — il n'y a rien à raisonner là-dessus, il suffit de réessayer la requête.

Un contrat plutôt que des instructions persuasives

Ajouter un nouvel outil nécessite :

• Des modèles Pydantic d'entrée/sortie avec types et validation • Un schéma JSON — le contrat des paramètres (ce qui est obligatoire, optionnel, les valeurs autorisées) • Une description de l'outil — le texte que le modèle lit pour décider s'il doit appeler l'outil et avec quels arguments • Des tests unitaires et des tests d'intégration in-process

La description (description) dans MCP n'est pas un simple commentaire, c'est une partie du produit. Avec une description mal rédigée, le modèle peut soit ne pas comprendre qu'il doit utiliser l'outil, soit l'appeler incorrectement. Le schéma JSON rejette les valeurs inconnues avant même la requête, pas après.

Conclusion

Cette approche résout deux problèmes profonds à l'interface entre LLM et API de géolocalisation : d'abord, le modèle invente purement et simplement des adresses ; ensuite, il les invente différemment, même en disposant d'outils. Le premier problème se résout avec des outils, le second avec un contrat typé strict, une validation rigoureuse et une séparation intelligente des erreurs entre protocole et logique métier.