El servidor MCP de 2GIS: cómo evitar que los LLM inventen direcciones y coordenadas

2GIS ha lanzado un servidor MCP (mcp-2gis), una herramienta que conecta a los agentes de IA directamente con los servicios de geolocalización de la plataforma API de 2GIS. Por ahora incluye seis herramientas: búsqueda de lugares y organizaciones, geocodificación directa, geocodificación inversa, cálculo de rutas, isócronas y mapas estáticos.

El problema que resuelve el servidor es clásico en los LLM: sin herramientas conectadas, un modelo que recibe una pregunta sobre una ruta o la organización más cercana responde con total seguridad, y de forma completamente inventada. El siguiente paso parece obvio: dar al modelo acceso a datos geográficos reales. En la práctica se descubrió que el acceso no basta: al recibir herramientas, el modelo empieza a mentir de otra manera. Puede invocar la herramienta de forma incorrecta, pasar parámetros erróneos o interpretar mal el resultado. Y es mucho más difícil de detectar, porque suena más convincente.

Arquitectura: un núcleo más adaptadores ligeros

La decisión clave fue una arquitectura escalable. En lugar de hacer que cada herramienta fuera completamente autónoma, con su propio manejo de errores, logging y pools HTTP, 2GIS dividió el sistema en capas:

1. Middleware de FastMCP — autenticación, listas de acceso, métricas, timeouts 2. tools/<domain>.py — el esquema MCP, validación Pydantic de entrada/salida, mapeo de resultados 3. tools/gis.py — dependencias de ciclo de vida y el límite común de manejo de errores 4. integrations/<domain>_api.py — URLs, parámetros e interacción JSON específicos de cada API de 2GIS 5. integrations/gis_client.py — un pool httpx compartido para todas las solicitudes, inyección de la clave de API y conversión de errores HTTP

Cada capa es responsable solo de su parte. El módulo de integración recibe una URL y un esquema de interacción con la API, pero nunca ve cabeceras, variables de entorno ni el propio MCP. Una herramienta no crea pools HTTP ni lee variables de entorno. Esta separación reduce la duplicación y permite añadir nuevas herramientas o servidores MCP sin copiar toneladas de código.

Cómo funciona el lado que invoca

Una única función auxiliar, `run_gis_tool`, reúne todas las dependencias, abre un span para la herramienta y traduce los errores en dos contratos distintos. Esto implementa un requisito crítico: un error de negocio (clave inválida, falta de acceso) debe llegar al agente como resultado de la herramienta, con un código legible por máquina, y no como una caída del protocolo. De lo contrario, el modelo no entiende qué hacer y vuelve a invocar la herramienta.

Un fallo de red o un timeout, en cambio, deben seguir siendo un error de MCP: no tiene sentido razonar sobre ellos, solo reintentar la solicitud.

Contrato en lugar de persuasión

Añadir una nueva herramienta requiere:

• Modelos Pydantic de entrada/salida con tipos y validación • Un JSON Schema — el contrato de parámetros (qué es obligatorio, qué es opcional, qué valores son válidos) • Una descripción de la herramienta — el texto que lee el modelo para decidir si invocarla y con qué argumentos • Pruebas unitarias y pruebas de integración in-process

La descripción en MCP no es un comentario, es parte del producto. Con una descripción mal escrita, el modelo puede no darse cuenta de que necesita la herramienta, o invocarla de forma incorrecta. El JSON Schema rechaza valores desconocidos antes de la solicitud, no después.

Conclusión

Este enfoque resuelve dos problemas profundos en la intersección de los LLM y las API de geolocalización: primero, que el modelo inventa direcciones; segundo, que las inventa de otra forma incluso teniendo herramientas. El primero se resuelve dándole herramientas; el segundo, con un contrato tipado estricto, validación y una separación sensata entre errores de protocolo y de negocio.