Skip to content
Brasil Data Commons Docs

Use with AI assistants (MCP)

Brasil Data Commons runs a public Model Context Protocol (MCP) server. Connect it to an AI assistant and the assistant can look up indicators and fetch official Brazilian statistics itself, citing the source of every number, instead of answering from memory.

Endpointhttps://brazildatacommons.com.br/mcp
TransportStreamable HTTP (stateless)
AuthenticationNone — the data is public
Toolssearch_indicators, get_observations, search_entities, resolve_places (all read-only)

Connect your client

Section titled “Connect your client”
Terminal window
claude mcp add --transport http --scope user dcbr https://brazildatacommons.com.br/mcp

Or share it with a project through .mcp.json (the type field is required):

{
  "mcpServers": {
    "dcbr": { "type": "http", "url": "https://brazildatacommons.com.br/mcp" }
  }
}

Any other client that speaks Streamable HTTP works the same way: point it at the endpoint, no headers or credentials needed.

The tools

Section titled “The tools”

Assistants normally chain them on their own; knowing the flow helps you phrase questions and read the answers.

  1. search_indicators — finds the statistical variables that match a topic (e.g. taxa de analfabetismo, PIB per capita, óbitos por homicídio), optionally restricted to the places you care about, and resolves place names to their IDs. It ranks variables exactly like this site’s search page; when nothing local matches, it returns variables from peer Data Commons (e.g. the UN’s), marked as such. Variables from Brasil Data Commons have IDs such as br/Count_Person; copy them as returned and read their meaning from the name.
  2. get_observations — fetches the values of one variable for a place: the latest value (default), every date, or a date range. With a child place type it returns the value for every place inside a parent — e.g. every municipality (AdministrativeArea2) in a state (AdministrativeArea1). Each series carries its source, so the assistant can say where a number comes from; when several sources publish the same variable you can ask for a specific one.

Two helpers cover what the main pair leaves implicit:

  • resolve_places — turns place names into IDs without guessing. When several places share a name (Bom Jesus is a município in five states; São Paulo is a state and a city) it lists them all with their state and population, so the assistant can pick from context or ask you.
  • search_entities — the site’s search as a tool: places, variables, topics and sources for a query, optionally limited to one group.

So: search first, then fetch. If you already know a variable ID (from this site’s pages or the API), you can name it directly.

Tips for good answers

Section titled “Tips for good answers”
  • Be explicit about the kind of place. “São Paulo” and “Rio de Janeiro” are both a state and a city, and many municipalities share a name. Say município de São Paulo or estado de São Paulo, or add the state (Bom Jesus - PI, Recife, Pernambuco), to get the one you mean.
  • Ask for a period, e.g. de 2010 a 2022 or série completa; otherwise the latest value is returned.
  • Percentages. Where a source publishes a percentage, the observation is marked with unit Percent; the variable itself describes what is measured (e.g. a count as a fraction of a population). Ask the assistant to state what a percentage is of.
  • Questions can be in Portuguese or English.

Example prompts:

  • Compare a taxa de mortalidade infantil dos estados do Nordeste no último ano disponível.
  • Qual foi o PIB do município de Campinas de 2015 a 2021? Cite a fonte.
  • Which Brazilian states had the highest homicide rate in the latest year?

Limits

Section titled “Limits”

  • Time. One tool call is cut off after about 85 seconds; national queries over all ~5,570 municipalities are the slowest. If a call times out, narrow it (one state instead of the whole country, a shorter date range).

  • Concurrency. Calls are queued when many arrive at once, and the endpoint may rate-limit clients that send bursts of requests. An assistant making a handful of calls per question is well within normal use.

  • Large results. A full history for every municipality of a state can be tens of thousands of numbers (every município of Brazil for one date is about half a million characters). The server returns the full answer; most clients cap how much tool output they accept, and beyond that the result is truncated or saved to a file:

    ClientDefault capHow to raise it
    Claude Codeget_observations up to 200k characters; larger results go to a file Claude readsMAX_MCP_OUTPUT_TOKENS=50000 claude
    Codex~10k tokensoutput_token_limit per tool (see the Codex tab)
    claude.ai~150k characters—
    Gemini CLI~40k characters—
    opencode~50 KB—
    pi~20 KB—

    The better fix is usually a narrower question: the latest value instead of the whole series, or one state instead of all municipalities.

Troubleshooting

Section titled “Troubleshooting”
  • The client can’t connect. Check the URL has no typo and uses https://. MCP clients talk to it with POST; opening the URL in a browser (a GET) shows an error such as 405 Method Not Allowed — that is expected.
  • The assistant answers without calling the tools. Ask explicitly: use o Brasil Data Commons para responder.
  • Wrong place. See the tip above on states vs. municipalities; you can also ask the assistant which place ID it used.
  • Every call needs approval. All tools are read-only and say so; most clients let you allow them permanently for this server.