Banco Central do Brasil (BCB) — SGS Time Series MCP Server

Buscar série no catálogo

bcb_buscar_serie

Read-onlyIdempotent

Busca séries do BCB por palavra-chave (ou pelo código) em DUAS camadas: o catálogo curado local de 135 séries verificadas contra a origem, que vem primeiro e com fonteNome dizendo se o nome é transcrito do portal do BCB ou herdado, e o índice do Portal de Dados Abertos do BCB, com milhares de séries identificadas por código. Ignora acentos e maiúsculas ('inflacao' encontra 'Inflação'); vários termos são combinados com E ('ipca servicos'). Quando usar: para descobrir o código de uma série antes de consultar valores. Quando NÃO usar: para navegar tudo por categoria use bcb_series_populares; para valores use bcb_serie_valores. Retorna: termo, totalEncontradas, series (cada item com codigo, nome, origem — 'curado' ou 'indice' — e, no índice, dataset com a página do portal), catalogo (origem, obtidoEm, seriesIndexadas, cobertura) e, quando aplicável, observacao, avisos, mensagem e sugestao. Cobertura: o índice NÃO é o SGS inteiro, portanto não encontrar aqui não prova que a série não exista — o campo catalogo.cobertura diz isso explicitamente em toda resposta. Comportamento de rede: o índice é servido de cache com validade de 24 h e a renovação é feita pela primeira busca após o vencimento (uma requisição ao portal, ~1 s); as demais buscas não tocam a rede. Se o portal estiver fora, a busca degrada para o catálogo curado (ou para o último índice obtido) e sinaliza em avisos, sempre com a data de obtenção visível.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`termo`	Yes	Termo de busca (mínimo 2 caracteres) ou o código da série. Vários termos são combinados com E, sem distinção de acento; a palavra de todo dia é traduzida para a do BCB (déficit→resultado primário, calote→inadimplência, desemprego→desocupação) e a resposta diz quando isso aconteceu (notasVocabulario).
`limite`	No	Máximo de séries a devolver (1-100, padrão: 20). `totalEncontradas` traz o total antes do corte.

Output Schema

TableJSON Schema

Name	Required	Description
`termo`	Yes	Termo pesquisado
`avisos`	No	Avisos de degradação (índice vencido ou indisponível)
`series`	Yes	Séries que correspondem ao termo — as do catálogo curado primeiro
`catalogo`	Yes	Proveniência do índice usado na busca
`mensagem`	No	Mensagem exibida quando nada é encontrado
`sugestao`	No	Sugestões de termos alternativos
`observacao`	No	Aviso de corte quando há mais resultados que `limite`
`provenance`	Yes	Um bloco por procedência que contribuiu com esta resposta (contrato v1.1; licenças nunca se fundem)
`attribution`	Yes	URLs canônicas das fontes desta resposta (lista de atribuição)
`notasVocabulario`	No	Quando um termo foi ampliado para a palavra que o BCB usa (déficit→resultado primário), diz qual
`totalEncontradas`	Yes	Quantidade de séries encontradas, antes do corte por `limite`

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 6, 2026

changedOutput schema / properties / provenance / items / description

Previous value: -"Bloco de proveniência (contrato v1.1): fonte, URL, competência, extração, diagnóstico de origem, citação e licença"New value: +"Bloco de proveniência (contrato v1.2): fonte, URL, competência, extração, diagnóstico de origem, citação e licença; e, só quando a resposta junta partes de origens ou momentos distintos, de onde veio cada parte"

addedOutput schema / properties / provenance / items / properties / field_sources

Added value: +{
+  "description": "Presente só quando a resposta junta partes de origens ou momentos distintos: para cada grupo de campos, a URL, a extração e se veio do cache. Ausente nas respostas de uma origem só",
+  "items": {
+    "additionalProperties": false,
+    "description": "Proveniência de um grupo de campos da resposta: de onde veio e quando foi extraído",
+    "properties": {
+      "data_vintage": {
+        "description": "Vintage/competência da sub-fonte",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "dataset_id": {
+        "description": "Identificador do conjunto da sub-fonte",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "fields": {
+        "description": "Campos do payload atribuídos a esta sub-fonte",
+        "items": {
+          "type": "string"
+        },
+        "minItems": 1,
+        "type": "array"
+      },
+      "retrieved_at": {
+        "description": "ISO-8601 da extração desta sub-fonte na origem",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "served_from_cache": {
+        "description": "true se esta sub-fonte veio do cache do servidor (retrieved_at é o da extração original); false se foi buscada nesta chamada; null se o servidor não distingue",
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "source_url": {
+        "description": "URL canônica da sub-fonte que originou estes campos",
+        "type": "string"
+      }
+    },
+    "required": [
+      "fields",
+      "source_url",
+      "dataset_id",
+      "data_vintage",
+      "retrieved_at"
+    ],
+    "type": "object"
+  },
+  "minItems": 1,
+  "type": "array"
+}

changedOutput schema / properties / provenance / items / properties / retrieved_at / description

Previous value: -"Instante REAL da extração na origem (ISO-8601, fuso do servidor). Resposta servida de cache mantém o instante do fetch original, que é a data de extração relevante"New value: +"Instante REAL da extração na origem (ISO-8601, fuso do servidor). Resposta servida de cache mantém o instante do fetch original, que é a data de extração relevante. Quando a resposta junta partes extraídas em momentos distintos, é o MAIS ANTIGO deles (field_sources diz cada um)"

Changed9 schema fields changedSep 27, 2026

changedOutput schema / properties / provenance / description

Previous value: -"Um bloco por procedência que contribuiu com esta resposta (contrato v1.0; licenças nunca se fundem)"New value: +"Um bloco por procedência que contribuiu com esta resposta (contrato v1.1; licenças nunca se fundem)"

changedOutput schema / properties / provenance / items / description

Previous value: -"Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença"New value: +"Bloco de proveniência (contrato v1.1): fonte, URL, competência, extração, diagnóstico de origem, citação e licença"

changedOutput schema / properties / provenance / items / properties / citation / description

Previous value: -"Citação pronta para uso"New value: +"Citação/atribuição pronta para uso"

changedOutput schema / properties / provenance / items / properties / data_vintage / description

Previous value: -"Competência do dado segundo a fonte; null quando a fonte não expõe"New value: +"Competência/vintage do dado segundo a fonte; null quando a fonte não expõe"

changedOutput schema / properties / provenance / items / properties / license / description

Previous value: -"Regime legal do dado"New value: +"Regime legal do dado (id SPDX quando há, senão o nome da licença)"

addedOutput schema / properties / provenance / items / properties / retrieval

Added value: +{
+  "description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade; null quando o servidor não mede",
+  "oneOf": [
+    {
+      "additionalProperties": false,
+      "description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade",
+      "properties": {
+        "anomalies": {
+          "description": "Anomalias superadas até o sucesso, somadas por classe, em ordem fixa; [] se nenhuma",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "count": {
+                "description": "Ocorrências desta classe na chamada",
+                "minimum": 1,
+                "type": "integer"
+              },
+              "kind": {
+                "description": "Classe da anomalia (vocabulário fechado do contrato)",
+                "enum": [
+                  "timeout",
+                  "network",
+                  "http_4xx",
+                  "http_5xx",
+                  "rate_limited",
+                  "malformed_body"
+                ],
+                "type": "string"
+              }
+            },
+            "required": [
+              "kind",
+              "count"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "attempts": {
+          "description": "Tentativas somadas, incluindo as repetidas (>= requests)",
+          "minimum": 1,
+          "type": "integer"
+        },
+        "requests": {
+          "description": "Idas distintas à origem que compõem esta resposta (fatias, páginas)",
+          "minimum": 1,
+          "type": "integer"
+        },
+        "unstable": {
+          "description": "true se houve repetição (attempts > requests) ou alguma anomalia",
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "requests",
+        "attempts",
+        "anomalies",
+        "unstable"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

changedOutput schema / properties / provenance / items / properties / retrieved_at / description

Previous value: -"Instante REAL da extração na origem (ISO-8601, horário de Brasília). Resposta servida de cache mantém o instante do fetch ORIGINAL, que é a data de extração relevante."New value: +"Instante REAL da extração na origem (ISO-8601, fuso do servidor). Resposta servida de cache mantém o instante do fetch original, que é a data de extração relevante"

changedOutput schema / properties / provenance / items / properties / source_url / description

Previous value: -"URL canônica que reproduz a consulta"New value: +"URL canônica que reproduz a consulta na fonte"

changedOutput schema / properties / provenance / items / required

Previous value: -[
-  "source",
-  "source_url",
-  "data_vintage",
-  "retrieved_at",
-  "citation",
-  "license"
-]New value: +[
+  "source",
+  "source_url",
+  "data_vintage",
+  "retrieved_at",
+  "retrieval",
+  "citation",
+  "license"
+]

Changed2 schema fields changedSep 16, 2026

changedInput schema / properties / termo / description

Previous value: -"Termo de busca (mínimo 2 caracteres) ou o código da série. Vários termos são combinados com E."New value: +"Termo de busca (mínimo 2 caracteres) ou o código da série. Vários termos são combinados com E, sem distinção de acento; a palavra de todo dia é traduzida para a do BCB (déficit→resultado primário, calote→inadimplência, desemprego→desocupação) e a resposta diz quando isso aconteceu (notasVocabulario)."

addedOutput schema / properties / notasVocabulario

Added value: +{
+  "description": "Quando um termo foi ampliado para a palavra que o BCB usa (déficit→resultado primário), diz qual",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

First observedSep 6, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial behavior beyond them: 24h cache with refresh-on-first-search-after-expiry, that subsequent searches avoid the network, and graceful degradation to the curated catalog with a warning when the portal is down. It also discloses the crucial coverage caveat that the index is not the whole SGS.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and when-to-use guidance, and nearly every clause carries information. However it is a dense single block that also restates return fields already covered by the output schema, making it longer than strictly necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a search tool with rich annotations and an output schema, it is fully complete: it explains layers, network behavior, degradation, and coverage limits. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the parameter descriptions already document the accent/case insensitivity, AND-combination, and vocabulary translation. The description repeats the accent/case and AND behavior but adds little parameter-specific meaning beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Busca séries do BCB por palavra-chave (ou pelo código)') and describes the two-layer mechanism (curated catalog + portal index). It explicitly differentiates siblings by naming bcb_series_populares and bcb_serie_valores as different purposes. An agent can tell this apart from the other series tools without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit 'Quando usar' (to discover a series code before consulting values) and 'Quando NÃO usar' with named alternatives and their conditions (bcb_series_populares for category browsing, bcb_serie_valores for values). This is textbook routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Banco Central do Brasil (BCB) — SGS Time Series MCP Server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.