Ferramentas do MCP

O MCP (Model Context Protocol) é o protocolo aberto com que um agente de IA chama ferramentas externas. O servidor MCP em https://mcp.brasilsintetico.com/mcp expõe as mesmas operações da API, com as mesmas regras, créditos e limites. Ele fala HTTP streamable, sem estado, e responde em JSON.

Fluxo típico

O servidor entrega este roteiro ao agente na conexão:

list_releases para ver as releases e as UFs oferecidas;
estimate_simulation com um cenário, para validá-lo e ver o preço antes de gastar;
submit_simulation para rodar: reserva os créditos e devolve o job;
get_job até o estado ser concluido (ou falhou: os créditos voltam);
get_findings para os achados em linhas: saturação, alcance, o efeito de cada canal e o veredito. Quando o cenário trouxe um contrato de resposta, get_answers dá as respostas. O resultado bruto nunca é servido: um job devolve achados, respostas e veredito, não dados;
compare_jobs para pôr lado a lado duas simulações concluídas da mesma release: o cenário de cada uma e os números principais de cada tabela dos achados, com a diferença.

Para começar de um modelo, list_campaign_templates lista a biblioteca, e get_campaign_template, com as UFs ou as cidades, devolve o cenário de um modelo para esse lugar, pronto para estimate_simulation. Um modelo traz premissas, não resultado.

Para conhecer uma cidade, sem simular: quote_city_diagnosis mostra os setores e o preço, que é zero; open_city_diagnosis abre o diagnóstico por setor no projeto; e get_city_diagnosis lê o resumo e cada variável, setor por setor. get_city_profile e get_city_tracts dão o contexto do município sem abrir nada.

Ferramentas

Ferramenta	Escopo	Natureza	O que faz
`list_releases`	`results:read`	só leitura	As releases oferecidas, com a população de cada UF.
`list_campaign_templates`	`results:read`	só leitura	A biblioteca de campanhas: os modelos por setor, com as premissas, e o resumo de cada caso público: o que foi medido, quantas UFs passam, as reprovações declaradas, a fonte e a página com o erro de cada UF (`detalhe`). O erro por UF vem pela API (`GET /v1/biblioteca`) e na página da biblioteca.
`get_campaign_template`	`results:read`	só leitura	Um modelo: o plano sem lugar, as premissas e as perguntas sugeridas. Com `ufs` ou `municipios`, também o cenário para esse lugar, com as perguntas, pronto para `estimate_simulation`.
`estimate_simulation`	`simulate`	só leitura	Valida um cenário e devolve o preço em milionésimos de real, sem reservar.
`submit_simulation`	`simulate`	gasta créditos	Roda um cenário: reserva o preço e devolve o job.
`list_jobs`	`results:read`	só leitura	Os jobs mais recentes do projeto, cada um com o `nome`.
`get_job`	`results:read`	só leitura	Um job e o registro dele: o `nome`, o estado, o preço e o hash do resultado.
`cancel_job`	`simulate`	desfaz	Cancela um job sem máquina; a reserva volta.
`erase_job_data`	`simulate`	desfaz	Apaga o pedido, as entradas e o resultado de um job que terminou. Não dá para desfazer.
`get_findings`	`results:read`	só leitura	Uma tabela dos achados em linhas: `tabela`, `municipios` e `limite` (até 1.000). Por padrão, só os municípios do público do cenário. A resposta traz o nome de cada município (`municipios`) e o que cada coluna quer dizer (`descricao`).
`get_answers`	`results:read`	só leitura	As respostas ao contrato de resposta de um job concluído, com a frase de cada uma, que nomeia cada município pelo nome, o nome dos municípios das perguntas (`municipios`) e o de cada setor em que uma resposta se baseia (`nomes`).
`compare_jobs`	`results:read`	só leitura	Duas simulações concluídas da mesma release lado a lado: o cenário de cada uma e os números principais dos achados, linha a linha, com a diferença e o nome de cada município (Comparar dois jobs).
`get_city_profile`	`results:read`	só leitura	O município visto do chão, pelo código IBGE de 7 dígitos: a área urbanizada em 2022 (densa, pouco densa, loteamentos vazios e vazios urbanos) e o crescimento dela desde 2019 (IBGE), a cobertura do solo em 2025 e a área urbana desde 1985 (MapBiomas). É contexto: não muda uma simulação.
`get_city_tracts`	`results:read`	só leitura	O município por setor censitário: um resumo (setores, edificações, área com declividade de 30% ou mais, o limite da Lei 6.766/1979 para parcelar o solo) e até `limite` setores com a cobertura do solo, as edificações e a declividade média. As edificações ficam ocultas onde moram de 1 a 4 domicílios.
`get_city_rainfall`	`results:read`	só leitura	A chuva do município desde janeiro de 1981, pelo código IBGE de 7 dígitos: a normal de 1991–2020 de cada mês e do ano, o mês mais chuvoso e o total de cada ano com a anomalia contra a normal (o ano corrente, ainda incompleto, fica sem anomalia). Com `meses`, a série mensal. É uma estimativa sobre a área do município, não a leitura de um pluviômetro, e não serve para chuva intensa de curta duração.
`quote_city_diagnosis`	`results:read`	só leitura	O diagnóstico por setor de uma cidade para o projeto: os setores, o preço (zero: o diagnóstico é gratuito) e `aberto`, se o projeto já abriu a cidade.
`open_city_diagnosis`	`simulate`	registra, sem custo	Abre o diagnóstico de uma cidade no projeto. Abrir de novo devolve o mesmo recibo.
`get_city_diagnosis`	`results:read`	só leitura	O diagnóstico de uma cidade aberta. Sem `variavel`, o resumo: as variáveis observadas (Censo 2022), as modeladas pela população sintética, cada uma com o seu erro, e quantos setores ficam com número abaixo do corte de erro. Com `variavel`, os valores por setor; o número modelado acima do corte fica oculto, com o motivo. Também `escolas`, `saude` e o saneamento (`abastecimento_agua`, `esgotamento`, `destino_lixo`, `banheiro`).
`estimate_growth`	`results:read`	só leitura	O que um loteamento novo pede de uma cidade aberta: moradores, crianças, escolas, saúde, saneamento e declividade, com a faixa de cada número (O cenário de crescimento) e o nome de cada setor que a resposta lista (`nomes`).
`estimate_calibration`	`simulate`	só leitura	Confere um pedido de calibração e a série, e devolve o preço, sem reservar.
`submit_calibration`	`simulate`	gasta créditos	Roda uma calibração: reserva o preço e devolve o job.
`get_calibration`	`results:read`	só leitura	O veredito de uma calibração concluída, o que ficou livre ou fixo e o valor escolhido de cada parâmetro, com `na_borda`.

Cada ferramenta declara a natureza dela nas anotações do MCP (readOnlyHint, destructiveHint). Assim, um cliente pode pedir sua confirmação antes de gastar ou desfazer.

Argumentos

estimate_simulation e submit_simulation recebem scenario: o cenário de campanha, tipado pelo mesmo JSON Schema da API. Um agente vê os campos antes de enviar.
submit_simulation aceita idempotency_key. Sem ela, a chave é o próprio cenário: enviar o mesmo cenário de novo devolve o mesmo job, sem cobrar duas vezes.
get_job, cancel_job, erase_job_data, get_findings, get_answers e get_calibration recebem job_id.
get_findings aceita tabela (por padrão, saturacao), municipios e limite (por padrão 200, até 1.000).
compare_jobs recebe a e b, os ids dos dois jobs, e aceita municipios e limite, como get_findings.
get_campaign_template recebe modelo, o id que list_campaign_templates dá, e aceita ufs (siglas) e municipios (códigos IBGE de 7 dígitos). Com só municipios, as UFs são as deles.
As ferramentas da cidade recebem municipio, o código IBGE de 7 dígitos: get_city_profile, get_city_tracts, get_city_rainfall, quote_city_diagnosis, open_city_diagnosis, get_city_diagnosis e estimate_growth. Algumas aceitam mais:
- get_city_tracts aceita limite, de 0 a 5.000 setores (por padrão, 50);
- get_city_rainfall aceita meses: com true, a resposta traz também a série mensal;
- get_city_diagnosis aceita variavel. Sem ela, vem o resumo. Com ela, vêm os valores por setor: as variáveis do resumo, escolas, saude e o saneamento (abastecimento_agua, esgotamento, destino_lixo, banheiro).
estimate_growth recebe também unidades, as unidades habitacionais do loteamento (de 1 a 20.000), e o lugar, por exatamente um de dois:
- setores: os códigos de 15 dígitos dos setores em que o loteamento fica;
- poligono: o contorno como [[longitude, latitude], ...]. O centro dele precisa cair num setor da cidade.
estimate_calibration e submit_calibration recebem pedido, como o pedido de calibração da API, e a série por um de dois caminhos:
- serie: as linhas, um objeto por linha (periodo, municipio, os recortes declarados e contagem);
- serie_sha256: no lugar das linhas, o hash de uma série que o projeto montou a partir de uma base de clientes.
- O pedido é tipado pelo mesmo JSON Schema de GET /v1/schemas/pedido-calibracao, com o cenário escrito no lugar. Ele não leva serie.sha256: a plataforma calcula o hash pelas linhas.
submit_calibration aceita idempotency_key. Sem ela, a chave é o pedido com a série: enviar os dois de novo devolve o mesmo job, sem cobrar duas vezes.

Respostas e recusas

As respostas usam os mesmos campos da API (estado, preco_micros, registro). Um setor censitário listado por get_city_diagnosis, get_city_tracts, estimate_growth ou get_answers vem com o nome em nomes (Os nomes dos setores): chame o setor por ele, e mostre junto dos nomes o crédito deles: em fontes, no diagnóstico; em creditos_dos_nomes, nas outras três, cujos números têm outras fontes. Uma recusa vem com isError: true e o texto código: mensagem (Erros no MCP). Um agente lê o motivo e o campo culpado e corrige o cenário, em vez de tentar adivinhar.