Senado Brasil MCP Server

🇧🇷 Leia em Português

A public, hosted MCP server that gives AI assistants live, structured access to Brazilian Senate open data — no installation, no account, no API key. Point your MCP client at the hosted endpoint and start asking about senators, bills, votes, expenses, and more. It runs on Cloudflare Workers over Streamable HTTP.

It exposes 69 tools, 4 prompts, and 5 resources across two domains:

• Legislative — senators; bills and their tramitation; votes; committees; plenary sessions, results and presidential vetoes; party-bloc voting orientation; speeches and stenographic transcripts; blocs and leadership; federal legislation; and citizen participation via the e-Cidadania portal.
• Administrative — CEAPS parliamentary-quota expenses; housing allowance; civil servants and payroll; overtime; interns; procurement contracts and biddings; outsourced staff; petty-cash funds; and budget execution.

Data comes from three official sources — the legislative open-data API, the administrative open-data API, and the e-Cidadania portal. All tool responses are in Portuguese (pt-BR). See CHANGELOG.md for release history.

See it in action

Point a client at the endpoint and ask in plain language — English or Portuguese:

• "How did São Paulo's senators vote in the most recent floor votes?" → senado_search_votacoes
• "Show the legislative progress of PEC 45/2019 (a constitutional amendment proposal)." → senado_buscar_materias + senado_obter_materia
• "How much was spent on the CEAPS parliamentary allowance in 2024, broken down by expense type?" → senado_ceaps

The answers come live from the Senate's official open-data APIs — exact figures with provenance, not numbers guessed from training data.

Use it (hosted — no setup)

This is a remote, hosted, open-access server. To use it, point any MCP client at the Streamable HTTP endpoint — no install, no account, no API key, no configuration:

https://senado.sidneybissoli.com/mcp

OpenAI / ChatGPT app surface

For OpenAI Apps SDK submission and review, the Worker also exposes a curated MCP surface:

https://senado.sidneybissoli.com/mcp/openai-app-v2

This endpoint intentionally keeps the full public MCP server intact at /mcp, but limits tool discovery to 27 high-signal, intent-oriented tools for ChatGPT app use. /mcp/openai-app remains available as a legacy alias, but new ChatGPT app configurations should use /mcp/openai-app-v2 so clients fetch the current tool schema. The tools still call the same handlers and return the same provenance envelope; only the advertised surface is narrower. Any ChatGPT app listing should present this as an independent open-data research app, not as an official Senate, OpenAI or ChatGPT connector.

For ChatGPT Apps, those 27 tools also advertise a shared MCP Apps UI template at ui://senado-br-mcp/openai-app-dashboard-v2.html. The self-contained widget renders the returned structuredContent as a compact dashboard with metrics, main records, and source/provenance, without adding another model-visible data tool.

Public legal URLs for app review:

• Privacy policy: https://senado.sidneybissoli.com/privacy
• Terms of use: https://senado.sidneybissoli.com/terms

ChatGPT (Deep Research)

ChatGPT deep research (and company knowledge, and research workflows over the Responses API) only uses an MCP server that exposes exactly search and fetch — this server does, on top of the senado_* tools, on the full /mcp surface (not on the curated app profile). Point the connector at the hosted endpoint, no key required:

https://senado.sidneybissoli.com/mcp

search ranks the query against the senators in office and the active committees of the Senate and the National Congress and returns { id, title, url } (sen:<código> / com:<código>); fetch returns the document as readable Markdown — the senator's biography and mandates, or the committee's summary and board — with the canonical public page (the senator's profile on www25.senado.leg.br or the committee page on legis.senado.leg.br), which is what ChatGPT cites. Both carry the same provenance block as every other tool, in structuredContent and _meta (the text channel is the contract's JSON). In ChatGPT's developer mode (Settings → Security and login → Developer mode) any tool is callable — the senado_* tools remain the ones to use for data.

Install (any client)

For clients that launch MCP servers as a command — and for one-command setup — use the mcp-remote bridge. No build, no config, no key:

npx -y mcp-remote https://senado.sidneybissoli.com/mcp

• One-click (LobeHub): open the server page and click Install.
• Native remote URL (Claude Desktop/Code and other Streamable-HTTP clients): see Connecting MCP Clients.

Everything below Architecture (Prerequisites, Setup, Deploy) is only for optionally self-hosting your own instance — it is not required to use this public server.

Run locally (npx · stdio)

Prefer not to route queries through a third-party host (e.g. a newsroom policy)? The same server also runs as a local stdio process that talks directly to the official government APIs — same 69 tools, same provenance envelope, no Cloudflare in the loop. This is the npm/stdio channel, published as senado-br-mcp.

Point a command-based client (Claude Desktop/Code, etc.) at the package — npm fetches and runs it, no clone or build:

{
  "mcpServers": {
    "senado-br": {
      "command": "npx",
      "args": ["-y", "senado-br-mcp"]
    }
  }
}

To run it directly or hack on it, use the source checkout instead:

git clone https://github.com/SidneyBissoli/senado-br-mcp-cloudflare
cd senado-br-mcp-cloudflare
npm install
npm run build
node dist/cli.js   # serves MCP over stdio (Ctrl+C to stop)

Parity with the hosted server: the legislative and administrative tools are identical (same upstream APIs, same throttle/cache/provenance) — locally the L1 Cloudflare cache is a no-op, but the L0 in-memory cache still works, so results are the same. The only difference is the e-Cidadania list/corpus tools: without D1 they fall back to a live scrape of the ~5 REST highlights, flagged via meta.fonte / possivelDesatualizacao; the detail tools (obter_*) are identical. Logs go to stderr — stdout carries only the JSON-RPC protocol stream.

Agent Skill (optional)

This repo bundles a Claude Agent Skill at .claude/skills/senado-br/ that teaches Claude when to reach for this server and how to use its 69 tools well — a themed tool map, common question→tool playbooks, the provenance contract, and gotchas (dates, the codigoMateria bridge, e-Cidadania's open-set listing, pagination). It points back to the server's own senado://catalogo / senado://guia resources rather than duplicating them.

Claude Code auto-discovers it when you work in this repo. To use it elsewhere, copy .claude/skills/senado-br/ into your ~/.claude/skills/, or zip the folder and upload it in claude.ai (Settings → Features). The skill assumes the senado-br MCP server is connected (hosted or via npx).

Architecture

• Runtime: Cloudflare Workers (ESM)
• Transport: Streamable HTTP (MCP spec 2025-03-26) via createMcpHandler from agents/mcp
• Protocol: MCP over JSON-RPC — /mcp handles the full public server; /mcp/openai-app-v2 exposes a curated 27-tool profile plus a shared MCP Apps widget for OpenAI app review/submission (/mcp/openai-app remains as a legacy alias)
• SDK: @modelcontextprotocol/server 2.x (per-request McpServer instances; the v1 @modelcontextprotocol/sdk is not installed — agents still lists it as a peer, satisfied via legacy-peer-deps)
• Validation: Zod schemas for all tool inputs
• Caching: 2-layer (L0 memory + L1 Cache API) with SHA-256 keying
• e-Cidadania store: D1 database refreshed by a Cron Trigger (every 2h) — list tools read from D1 with a live-scrape fallback and a staleness flag; detail tools stay live with write-through (see e-Cidadania)
• Rate limiting: Token bucket — global (8 req/s) + per-client (2 req/s)
• Upstream throttle: Max 6 concurrent requests, 10s budget per trip, retry on 429/5xx/network with exponential backoff and Retry-After (portfolio shared fetch @sbissoli/mcp-upstream); every response's provenance carries the measured retrieval diagnostics (trips, attempts, anomalies)
• Auth: Optional Bearer token (set the API_KEY secret; open access when unset). Constant-time comparison.
• Observability: Structured JSON logging + in-memory counters at /metrics; per-tool call telemetry (selection, error rate, cache-vs-live) in Cloudflare Analytics Engine, PII-free
• Liveness: Runs on Cloudflare's own global network behind a custom domain — no third-party host that can go dark. Public /health and /status (version + last-deploy id/timestamp) make uptime and the current build verifiable; the status badge above pings the live endpoint
• Tests: Vitest unit tests for parsers, helpers, cache, throttle, and auth

Self-hosting (optional)

Not needed to use the server — it is already hosted at https://senado.sidneybissoli.com/mcp (open access). Follow this section only if you want to run your own private instance.

Prerequisites

• Node.js 22+ (engines.node)
• Wrangler CLI v4+
• Cloudflare account

Setup

1. Install dependencies

npm install

2. Create KV namespace

# Create the KV namespace
wrangler kv namespace create CACHE_KV

# Note the ID from the output, e.g.:
# { binding = "CACHE_KV", id = "abc123..." }

3. Configure wrangler.toml

Replace the placeholder KV namespace ID:

[[kv_namespaces]]
binding = "CACHE_KV"
id = "YOUR_KV_NAMESPACE_ID_HERE"

Optionally set ALLOWED_ORIGIN to restrict CORS:

[vars]
ALLOWED_ORIGIN = "https://your-app.example.com"

The e-Cidadania pipeline needs a D1 database and a Cron Trigger (both already declared in wrangler.toml — replace the database ID):

[[d1_databases]]
binding = "ECIDADANIA_DB"
database_name = "senado-ecidadania"
database_id = "YOUR_D1_DATABASE_ID_HERE"

[triggers]
crons = ["0 */2 * * *"]

Create the database (paste the returned ID above) and apply the schema:

npx wrangler d1 create senado-ecidadania
npx wrangler d1 migrations apply senado-ecidadania --remote

The list tools fall back to live scraping when D1 is empty, so the server works before the first Cron run.

4. (Optional) Enable authentication

wrangler secret put API_KEY
# Clients must then send: Authorization: Bearer <key>
# When API_KEY is not set, the server is open access.

5. Local development

npm run dev
# Dev server runs locally on port 8787 (local only).
# The public MCP endpoint is https://senado.sidneybissoli.com/mcp

6. Tests and typecheck

npm test             # run all tests once
npm run test:watch   # watch mode
npm run typecheck    # tsc --noEmit

7. Deploy

npm run deploy
# Serves at https://senado.sidneybissoli.com (custom domain) and
# https://senado-br-mcp.sidneybissoli.workers.dev (workers.dev fallback)

Endpoints

Path	Methods	Description
/	GET	Landing page (pt-BR) — identifies the client behind the outgoing User-Agent: what the service is, load posture, contact (always public)
/mcp	POST, GET, DELETE, OPTIONS	MCP Streamable HTTP endpoint (managed by createMcpHandler)
/health	GET	Health check — returns ok (always public)
/status	GET	JSON: status, version, and last-deploy metadata (deploy.id/tag/timestamp) — liveness + current build, no MCP handshake needed (always public)
/metrics	GET	JSON counters: requests, tool calls, cache hits/misses, upstream calls/retries/errors, auth failures (always public)
/.well-known/mcp/server-card.json	GET	MCP server card for directory scanners (Smithery): serverInfo, authentication, tools/resources/prompts — generated from the live full profile by @sbissoli/mcp-surface/card (always public)

Surface fingerprint, checkable from the registry

Every release publishes, in its MCP Registry entry, the sha256 of the surface /mcp serves (initialize, tools, resources, prompts of the full profile) and which methods answer there without a credential. A surface change without a version bump fails the build; the fingerprint in the registry lets a client check the same thing on its own side. Canonical form and procedure: SPEC.md of @sbissoli/mcp-surface. To check it yourself (Node 18+, no dependencies):

curl -sO https://raw.githubusercontent.com/SidneyBissoli/mcp-br-commons/main/packages/mcp-surface/exemplos/verify.mjs
node verify.mjs io.github.SidneyBissoli/senado-br-mcp-cloudflare

MCP Request Examples

All requests go to POST /mcp with JSON-RPC 2.0 format.

List available tools

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Call a tool — List senators from SP

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "senado_listar_senadores",
    "arguments": {
      "uf": "SP",
      "emExercicio": true
    }
  }
}

Call a tool — Search bills by keyword

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "senado_buscar_materias",
    "arguments": {
      "palavraChave": "inteligência artificial",
      "tramitando": true
    }
  }
}

Call a tool — Get recent plenary votes

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "senado_search_votacoes",
    "arguments": {
      "dias": 7
    }
  }
}

Call a tool — Most popular citizen ideas

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "senado_ecidadania_listar_ideias",
    "arguments": {
      "ordenarPor": "apoios",
      "ordem": "desc",
      "status": "aberta"
    }
  }
}

Upstream API Endpoints

The server consumes two classes of upstream endpoints from the Senado API:

Legacy endpoints (.json suffix, PascalCase responses)

Used by Groups A, E, F, H, I, J, K, L, M, N. The .json suffix is appended automatically by upstream.ts. None of these is marked deprecated upstream.

Upstream path	Used by
/senador/lista/atual	senado_listar_senadores
/senador/lista/legislatura/{legislatura}	senado_listar_senadores (param legislatura)
/senador/{codigo} (+ /mandatos)	senado_obter_senador (biografia + mandatos via chamada extra)
/senador/{codigo}/licencas, /comissoes, /cargos, /historicoAcademico, /filiacoes, /profissao	senado_senador_historico (tipo enum)
/senador/afastados	senado_senadores_afastados
/senador/{codigo}/apartes	senado_discursos_senador (tipo=apartes)
/comissao/lista/colegiados	senado_listar_comissoes (+ sigla-to-code resolution)
/comissao/{codigo}	senado_obter_comissao (secao=resumo; numeric code, not sigla)
/composicao/comissao/{codigo} (+ ?ativas=S)	senado_obter_comissao (secao=membros)
/comissao/agenda/{data}	senado_agenda_comissoes
/comissao/agenda/{dataInicio}/{dataFim}	senado_reunioes_comissao
/comissao/reuniao/{codigoReuniao}	senado_reuniao_comissao
/comissao/cpi/{sigla}/requerimentos	senado_requerimentos_cpi (upstream often empty even for active CPIs — empty result carries an aviso)
/materia/distribuicao/autoria, /distribuicao/relatoria/{sigla}	senado_distribuicao_materias
/plenario/agenda/dia/{data}, /agenda/mes/{data}, /agenda/cn/...	senado_agenda_plenario
/plenario/resultado/{data}, /resultado/cn/{data}, /resultado/mes/{data}	senado_resultado_plenario
/plenario/resultado/veto/{codigo} (+ /materia/, /dispositivo/)	senado_resultado_veto
/plenario/votacao/orientacaoBancada/{data} (+ período)	senado_orientacao_bancada
/plenario/encontro/{codigo} (+ /pauta, /resultado, /resumo)	senado_encontro_plenario
/plenario/tiposSessao, /lista/tiposComparecimento, /lista/legislaturas	senado_tabelas_plenario
/materia/vetos/{ano}, /vetos/aposrcn, /vetos/antesrcn, /vetos/encerrados	senado_vetos
/taquigrafia/notas/{sessao|reuniao}/{id}	senado_notas_taquigraficas
/taquigrafia/videos/{sessao|reuniao}/{id}	senado_videos_taquigrafia
/senador/{codigo}/discursos	senado_discursos_senador
/plenario/lista/discursos/{dataInicio}/{dataFim}	senado_discursos_plenario
/discurso/texto-integral/{codigo}	senado_discurso_texto (plain text, fetched directly)
/senador/lista/tiposUsoPalavra	senado_tabelas_referencia (tabela=tipos-uso-palavra)
/composicao/lista/blocos	senado_listar_blocos
/composicao/bloco/{codigo}	senado_obter_bloco
/composicao/lideranca	senado_liderancas
/composicao/mesaSF	senado_mesa (casa=senado)
/composicao/mesaCN	senado_mesa (casa=congresso)
/orcamento/lista	senado_orcamento_parlamentar (tipo=emendas)
/orcamento/oficios	senado_orcamento_parlamentar (tipo=oficios)
/legislacao/lista	senado_buscar_legislacao
/legislacao/{codigo}	senado_obter_legislacao
/legislacao/tiposNorma	senado_tabelas_referencia (tabela=tipos-norma)
/votacaoComissao/comissao/{sigla}	senado_votacao_comissao (por=comissao)
/votacaoComissao/parlamentar/{codigo}	senado_votacao_comissao (por=senador)
/votacaoComissao/materia/{sigla}/{numero}/{ano}	senado_votacao_comissao (por=materia)
/autor/lista/atual	senado_autores_atuais

v3 endpoints (flat JSON arrays/objects, camelCase)

Used by Groups B, C, D. Dates must be in ISO format (YYYY-MM-DD) — tools accept YYYYMMDD and convert. The codigoMateria query param bridges legacy matéria codes to v3 processes.

Upstream path	Used by
/votacao	senado_obter_votacao, senado_search_votacoes, senado_votos_materia, senado_votacoes_senador
/processo	senado_search_processos, senado_buscar_materias
/processo/{id}	senado_obter_processo, senado_obter_materia (secao=detalhe/tramitacao)
/processo/documento	senado_obter_materia (secao=textos)
/processo/emenda	senado_processo_detalhe (secao=emendas)
/processo/relatoria	senado_processo_detalhe (secao=relatorias), senado_obter_materia (rapporteur)
/processo/prazo	senado_processo_detalhe (secao=prazos)
/processo/{siglas,assuntos,classes,destinos,entes,tipos-*}	senado_tabelas_processo (12 reference tables)

Administrative API (adm.senado.gov.br/adm-dadosabertos, flat snake_case JSON)

Used by Groups O, P, Q, R via admFetch (no .json suffix; HTTP 404 treated as empty collection). Base URL configurable via SENADO_ADM_BASE_URL.

Upstream path	Used by
/api/v1/senadores/despesas_ceaps/{ano}	senado_ceaps (~10 MB/year, cached + aggregated in-Worker)
/api/v1/senadores/{auxilio-moradia,escritorios,aposentados}	senado_senadores_admin (tipo enum)
/api/v1/servidores/servidores/{ativos,efetivos,comissionados,inativos}	senado_servidores
/api/v1/servidores/remuneracoes/{ano}/{mes}	senado_remuneracoes_servidores (~5.5 MB/month)
/api/v1/servidores/horas-extras/{ano}/{mes}	senado_horas_extras
/api/v1/servidores/quantitativos/*, /previsao-aposentadoria, /api/v1/senadores/quantitativos/senadores	senado_pessoal_tabelas (quantitativos)
/api/v1/servidores/{estagiarios,pensionistas,lotacoes,cargos}	senado_pessoal_tabelas (listas nominais)
/api/v1/contratacoes/contratos (+ /{id}/aditivos)	senado_contratos, senado_contratacao_detalhe
/api/v1/contratacoes/{tipo}/{id}/{itens,pagamentos,garantias}	senado_contratacao_detalhe
/api/v1/contratacoes/licitacoes	senado_licitacoes
/api/v1/contratacoes/terceirizados	senado_terceirizados
/api/v1/contratacoes/empresas	senado_empresas_contratadas (~13 MB, requires filter)
/api/v1/contratacoes/{atas_registro_preco,notas_empenho,menores_aprendizes}	senado_contratacoes_lista
/api/v1/supridos/{ano} (+ atosConcessao, empenhos, movimentacoes, transacoes)	senado_suprimento_fundos
senado.gov.br/bi-arqs/Arquimedes/Financeiro/{Despesa,Receitas}SenadoDadosAbertos.json	senado_execucao_orcamentaria (daily JSON feeds, Brazilian decimal strings normalized)

e-Cidadania (D1-backed, Cron-refreshed)

The e-Cidadania list data is persisted in a D1 database (ecidadania_current/_history/_scrape_runs, discriminated by entidade; plus ecidadania_comentarios for the audiência comment level and ecidadania_detalhe_cursor for the resumable detail backfill — added in schema v2) and read from there instead of being scraped on every call. Three cadences write into it: