"Nada consta" ou "fonte fora do ar"? O problema de dar dado público para um agente de IA

Estou montando um servidor MCP que checa empresa brasileira por CNPJ: cadastro na Receita, sanções federais (CEIS, CNEP, CEPIM, acordos de leniência), contratos com o governo federal e registro na CVM. A parte de chamar as APIs foi a fácil. O que deu trabalho foi outra coisa, e acho que vale para quem integra dado público com agente.

O problema

Se a API de sanções do Portal da Transparência dá timeout e o seu código devolve [], o agente lê “empresa sem sanções”. Para um fluxo de KYC ou due diligence, isso é o pior erro possível: um falso negativo silencioso, com cara de resposta boa.

E acontece fácil: try/except que devolve lista vazia, .get('dados', []), fallback “para não quebrar”. O LLM não tem como desconfiar.

O que fiz

1. Status por fonte, sempre. Toda resposta traz um bloco fontes, uma entrada por fonte consultada:

{"nome": "Portal da Transparência – CEIS", "status": "ok", "consultado_em": "2026-10-04T09:39:07-03:00", "de_cache": true, "idade_cache_s": 45573}

status é ok, nao_encontrado, erro, timeout ou limite_excedido. A regra: lista vazia só existe com status ok. Fonte com erro devolve null, nunca [].

2. Resultado parcial em vez de falha total. O relatório completo roda as 4 consultas em paralelo, cada uma com timeout próprio. Se uma estoura, ela volta null, entra em secoes_com_falha e o campo completo vira false. O agente recebe o que deu certo e sabe exatamente o que faltou.

3. Cache visível. Cadastro fica 7 dias em cache; sanções e contratos, 24h. Mas de_cache e idade_cache_s estão em toda fonte: quem consome decide se aquele dado de ontem serve.

4. Fato, não opinião. Nada de score de risco. O servidor devolve fatos com fonte e data; quem interpreta é o agente do cliente. Score parece valor agregado, mas é responsabilidade que eu não tenho como sustentar.

Pegadinhas das fontes (para quem for integrar)

• O filtro por CNPJ do Portal só casa o CNPJ exato. Consultar a matriz não traz sanção da filial e vice-versa. Consultar uma filial dispara também a consulta da matriz, e o registro de outro estabelecimento vem marcado. O caminho inverso não existe: o servidor não varre as filiais a partir da matriz. Se a sanção está numa filial, é preciso consultar o CNPJ dela.
• Campos com o texto “Sem informação” (em data, inclusive) e números negativos como -3 no lugar de nulo. Tudo isso vira null.
• A API de contratos não ordena. Para devolver “os mais recentes”, é preciso ler as páginas e ordenar localmente, com teto.
• CVM não tem API por CNPJ, mas o cadastro de companhias abertas é um CSV de 1,5 MB atualizado diariamente (latin1, separador ;). Baixar e indexar em memória é mais rápido e confiável que qualquer API. E a mesma empresa aparece mais de uma vez (registro cancelado antigo + ativo).
• Cobertura: sanções e contratos são só da esfera federal. “Nada consta” aqui não prova nada em estado ou município, e o aviso da resposta diz isso.

LGPD

Dado público não é dado liberado para qualquer uso. O servidor nunca devolve QSA (sócios), e-mail ou telefone. Para MEI e empresário individual, razão social e endereço costumam conter nome e residência da pessoa, então são omitidos (dados_omitidos_lgpd: true). Sanção aplicada a CPF é descartada.

Exemplo real

Resposta completa da Petrobras e as 5 ferramentas: https://github.com/DouglasGouvea/mcp-empresas-br-docs

Está publicado na MCPize (https://mcpize.com/mcp/mcp-empresas-br), com plano gratuito de 100 consultas/mês, no Smithery (https://smithery.ai/servers/gouvea-douglas/mcp-empresas-br) e no registro oficial de MCP. Feedback de quem trabalha com compliance ou KYC é o que mais me ajuda agora: o que falta para isso entrar num fluxo real?