How I built a semantic layer over Brazil’s official economic data, and why the hardest part wasn’t the API

Felipe Gambetta de Souza — Sat, 12 Sep 2026 19:19:50 +0000

Brazil has a huge amount of high-quality official economic data.

The problem is that using it programmatically is much harder than it should be.

The Brazilian Central Bank has one API and data model. IBGE has another. Tesouro has another. SICONFI, Comex Stat, Novo Caged, ANP, EPE and CVM all expose data differently.

At first, I thought the solution was straightforward:

Put all of these sources behind one API.

While building it, I realized that API normalization was not actually the hardest problem.

The hardest problem was preserving economic meaning.

A correct number can still be the wrong answer

Suppose someone asks:

What is the current Selic rate?

There are several legitimate official series related to Selic.

For example:

the Selic target defined by Copom;
the effective Selic rate;
accumulated monthly Selic;
annualized variants.

All of them are real official data.

But returning the wrong one still produces an incorrect answer.

This became one of the core design principles behind Open Economics.

Instead of treating search and availability as the same problem, I separated them.

1. Semantic resolution

First, determine what economic concept the user is actually asking for.

For example:

current Selic target rate

can resolve to:

selic-target

2. Data availability

Then determine which official datasets actually represent that concept and whether Open Economics can query them correctly.

For the Selic target, that leads to:

bcb-sgs:432

which is the official BCB series:

Taxa de juros - Meta Selic definida pelo Copom

If the right concept is not currently supported, the system should say so.

It should not silently return a similar-looking series just because it happens to contain the same keywords.

Provenance became part of the data model

Once multiple sources sit behind the same API, abstraction creates another problem.

You can easily lose answers to basic questions:

Who published this number?
Which official dataset did it come from?
What unit does it use?
What date or period does it represent?
Was anything transformed?
Where can I inspect the original source?

So Open Economics keeps provenance attached to the result.

A response can preserve things such as:

official institution;
dataset identity;
source URL;
metadata URL;
unit;
frequency;
observation date;
transformations;
retrieval metadata.

The goal is not to build another database of copied economic numbers.

The goal is to provide a consistent interface over official sources without hiding where the data came from.

Then I tried making the same layer usable by AI agents

I also wanted agents to query the data directly.

So I built a remote MCP server.

It currently exposes 19 tools covering semantic discovery, dataset inspection, metadata and data retrieval.

During testing, I found an interoperability bug that I did not expect.

The MCP tools worked.

The client could discover them.

The calls succeeded.

But an agent using Cline still couldn't answer something as simple as the current Selic rate.

Why?

The complete result was being returned in:

structuredContent

while the normal textual MCP content contained little more than:

Retrieved official BCB observations for bcb-sgs:432.

So technically the MCP call had succeeded.

But that particular client wasn't exposing the structured result to the model.

The agent knew that data had been retrieved, but couldn't actually see the values.

Supporting the protocol wasn't enough

The fix wasn't to remove structured output.

structuredContent is still the canonical machine-readable result.

Instead, I added a bounded textual representation containing enough information for a model to actually use the result:

values;
dates;
units;
dataset identity;
official institution;
provenance;
official source URL.

Small results can be represented completely.

Larger results include a limited number of rows and explain that the complete machine-readable result remains available in structuredContent.

After deploying the change, I repeated the Cline test with an important constraint:

Use only Open Economics. No web search, curl, terminal, direct BCB API calls, or external sources.

The agent successfully:

resolved the query semantically;
identified bcb-sgs:432;
inspected the official metadata;
retrieved the observations;
read the actual value and date;
answered using only Open Economics.

That was a useful reminder that protocol compliance and real-world interoperability are not always the same thing.

What Open Economics looks like today

Open Economics is now a free and open-source layer for Brazilian official economic data.

There is:

REST API

For example, the latest Selic target observation:

curl "https://open-economics-data.knbf982hkn.chatgpt.site/api/v1/indicators/br-selic-target/latest"

Interactive interface

You can try queries without writing code:

https://open-economics-data.knbf982hkn.chatgpt.site/en/ask?utm_source=devto&utm_medium=community&utm_campaign=launch

MCP

Agents can connect directly to:

https://open-economics-data.knbf982hkn.chatgpt.site/api/mcp

The remote MCP server currently exposes 19 tools.

No API key is required.

No signup is required.

Everything is read-only.

Current sources

The project currently integrates data from Brazilian official sources including BCB, IBGE, Tesouro, SICONFI, MDIC / Comex Stat, MTE / Novo Caged, ANP, EPE and CVM.

It is not intended to pretend every possible Brazilian economic dataset is already normalized.

One of the design goals is precisely to make missing coverage explicit instead of silently substituting something else.

Open source

The code is here:

https://github.com/felipegambettadesouza6-jpg/open-economics

There is also a public Postman workspace:

https://www.postman.com/open-economics/open-economics

And the MCP server is published through the official MCP Registry.

What I want to test next

At this point, I am less interested in hearing that the project "looks cool" and more interested in finding the cases where the abstraction breaks.

Especially:

revisions;
tricky date semantics;
inconsistent units;
multidimensional datasets;
similarly named economic series;
methodology changes;
provenance;
queries requiring multiple official sources.

If you work with Brazilian economic data, APIs, data engineering or AI agents:

What official-data query is still unnecessarily painful for you today?

Give me a concrete example.

I want to run it against Open Economics and find where the system still fails.

DEV Community: Felipe Gambetta de Souza