Servidor MCP da 2GIS: como impedir que LLMs inventem endereços e coordenadas

A 2GIS lançou um servidor MCP (mcp-2gis) — uma ferramenta que conecta agentes de IA diretamente aos geosserviços da plataforma de API da 2GIS. Por enquanto, são seis ferramentas: busca de lugares e organizações, geocodificação direta, geocodificação reversa, cálculo de rotas, isócronas e mapas estáticos.

O problema que o servidor resolve é clássico em LLMs: sem ferramentas conectadas, um modelo questionado sobre uma rota ou a organização mais próxima responde com total confiança — e de forma totalmente inventada. O próximo passo parece óbvio: dar ao modelo acesso a dados geográficos reais. Na prática, descobriu-se que o acesso não basta: ao receber ferramentas, o modelo passa a mentir de outra forma. Ele pode chamar a ferramenta incorretamente, passar parâmetros errados ou interpretar mal o resultado. E isso é muito mais difícil de perceber, porque soa mais convincente.

Arquitetura: um núcleo mais adaptadores enxutos

A decisão-chave foi uma arquitetura escalável. Em vez de tornar cada ferramenta totalmente autônoma, com seu próprio tratamento de erros, logging e pools HTTP, a 2GIS dividiu o sistema em camadas:

1. Middleware do FastMCP — autenticação, allowlist, métricas, timeouts 2. tools/<domain>.py — o schema MCP, validação Pydantic de entrada/saída, mapeamento de resultados 3. tools/gis.py — dependências de lifespan e o limite comum de tratamento de erros 4. integrations/<domain>_api.py — URLs, parâmetros e interação JSON específicos de cada API da 2GIS 5. integrations/gis_client.py — um pool httpx compartilhado para todas as requisições, injeção da chave de API e conversão de erros HTTP

Cada camada é responsável apenas pela sua parte. O módulo de integração recebe uma URL e um schema de interação com a API, mas nunca vê cabeçalhos, variáveis de ambiente ou o próprio MCP. Uma ferramenta não cria pools HTTP nem lê variáveis de ambiente. Essa separação reduz a duplicação e permite adicionar novas ferramentas ou servidores MCP sem copiar toneladas de código.

Como funciona o lado que chama

Uma única função auxiliar, `run_gis_tool`, reúne todas as dependências, abre um span para a ferramenta e traduz os erros em dois contratos distintos. Isso implementa um requisito crítico: um erro de negócio (chave inválida, falta de acesso) deve chegar ao agente como resultado da ferramenta, com um código legível por máquina, e não como uma queda de protocolo. Caso contrário, o modelo não entende o que fazer e simplesmente chama a ferramenta de novo.

Já uma falha de rede ou timeout deve continuar sendo um erro de MCP — não faz sentido raciocinar sobre isso, só tentar de novo.

Contrato em vez de persuasão

Adicionar uma nova ferramenta exige:

• Modelos Pydantic de entrada/saída com tipos e validação • Um JSON Schema — o contrato de parâmetros (o que é obrigatório, o que é opcional, quais valores são permitidos) • Uma descrição da ferramenta — o texto que o modelo lê para decidir se a chama e com quais argumentos • Testes unitários e testes de integração in-process

A descrição no MCP não é um comentário, é parte do produto. Com uma descrição malfeita, o modelo pode não perceber que a ferramenta é necessária, ou chamá-la incorretamente. O JSON Schema rejeita valores desconhecidos antes da requisição, não depois.

Conclusão

Essa abordagem resolve dois problemas profundos na interseção entre LLMs e APIs de geolocalização: primeiro, que o modelo inventa endereços; segundo, que ele os inventa de outra forma mesmo tendo ferramentas. O primeiro se resolve dando ferramentas a ele; o segundo, com um contrato tipado rígido, validação e uma separação sensata entre erros de protocolo e de negócio.