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 66 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 Portuguese:

• "Como os senadores de São Paulo votaram nas últimas votações do plenário?" → senado_search_votacoes
• "Mostre a tramitação da PEC 45/2019." → senado_buscar_materias + senado_obter_materia
• "Quanto foi gasto com a cota parlamentar (CEAPS) em 2024, por tipo de despesa?" → 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

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.

Architecture

• Runtime: Cloudflare Workers (ESM)
• Transport: Streamable HTTP (MCP spec 2025-03-26) via createMcpHandler from agents/mcp
• Protocol: MCP over JSON-RPC — single /mcp endpoint handles POST, GET, DELETE
• SDK: @modelcontextprotocol/sdk 1.26.0+ (per-request McpServer instances)
• 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 timeout, retry with exponential backoff
• 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 18+
• 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

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.

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.

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.

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) and read from there instead of being scraped on every call. Two cadences write into it:

• a weekly off-Worker GitHub Action owns the full corpus of each entity (see below) — the source of truth;
• an in-Worker Cron Trigger (0 */2 * * *, src/scraper/pipeline.ts → refreshEcidadania) does only a targeted metric splice of the ~5 REST highlights per live entity (restcolecaomaismateria/ideia/audiencia — votos/comentários/apoios), recorded as ok-metrica so it never re-breaks the corpus baseline and never touches the long tail.

Both writers build payloads through the canonical buildXResumo builders + shared contentHash, so their rows are byte-identical. Each write:

• upserts ecidadania_current (one row per item — what the tools read),
• appends ecidadania_history only when an item's content_hash changes (time-series-ready),
• records each run in ecidadania_scrape_runs.

An anomaly guard (src/scraper/anomaly.ts, classifyRun) ensures a failed or anomalous corpus run (zero rows, or fewer than ECIDADANIA_CORPUS_MIN_PCT% of the last good run) never overwrites the last good state.

The list / analysis tools (listar_*, consultas_analise, sugerir_tema_enquete, consultas_votos) read from D1 via resolveList (src/scraper/store.ts): D1-first. Because every entity is now a full corpus, a stale corpus is served from D1 flagged (possivelDesatualizacao: true) rather than collapsing to the ~5-item live highlights (the original coverage bug); the live scrape is reserved for an empty D1 (cold start, before the first weekly run). Staleness uses ECIDADANIA_CORPUS_STALE_MAX_MIN (~10 days). Every list response carries an additive meta (fonte, lastScrapedAt, possivelDesatualizacao) so callers always see the data's real age and never get stale data silently.

The detail tools (obter_*) stay live (HTML scraped with CSS-class-targeted regex) for freshness, and write their richer payload through to ecidadania_detalhe fire-and-forget (deduped by content_hash), so detail history accrues without adding latency to the response.

#### Full-corpus ingestion (off-Worker, weekly)

All four e-Cidadania entities are full corpora owned by the weekly Action (.github/workflows/ingest-ecidadania.yml), each with its own scripts/ingest-ecidadania/index-*.ts orchestrator emitting batched out-*.sql the apply step bulk-loads:

• `consultas` — open consultations (detailed below).
• `eventos` — audiências/eventos from the principalaudiencia?p=N HTML listing; status comes straight from the listing block (no /processo bridge).
• `ideias` — ideias legislativas (~150k) from pesquisaideia?situacao=N&p=M, crawled per `situacao` bucket (the listing has no inline status) and emitted in ~10k-statement batches.
• `consultas_votos` — a separate historical acervo of votes-by-UF parsed from the ~33 MB Arquimedes CSV (Proposições-com-votos.csv), aggregated to one record per matéria with a votosPorUf breakdown. The CSV's "dados atualizados até" stamp becomes the provenance reference_period; it is excluded from the row hash (consultaVotoCore) so a weekly stamp bump on these frozen votes doesn't churn _history. STATUS ATUAL is uniformly "Descontinuado", hence archival, not a migration of the open consultations. Served by senado_ecidadania_consultas_votos with provenance pointing at the CSV (ECIDADANIA_ARQUIMEDES).

The consultas job is the reference implementation:

consultas covers the full set of OPEN consultations — every matter currently in tramitação (~7.7k), not just the ~5 highlights. Confirmed on the first run: the pesquisamateria listing is in-tramitação-only, so closed/historical consultations are not captured by this source (a pre-ingestion historical backfill is out of scope). Three settled design decisions:

1. Decoupled ingestion. The open set is acquired by an off-Worker TypeScript job (scripts/ingest-ecidadania/, run by a weekly GitHub Action — .github/workflows/ingest-ecidadania.yml) that paginates the HTML listing (pesquisamateria?p=1..N, the only full-coverage source for open consultations) for ids + vote counts and bulk-loads D1; the Worker only reads. The brittle, long crawl is kept out of the request/Cron path.
2. Status from `/processo`, not HTML. A consultation runs from presentation until the end of tramitação, so status is a function of the matter: aberta ⟺ the `codigoMateria` is in the `/processo` `tramitando=S` set, derived from robust JSON (never scraped). Every consultation enters as aberta (the listing only yields in-tramitação matters); on each complete run the job re-derives status for all stored rows by /processo membership (not by listing-absence, which can be transient), so a consultation whose matter leaves tramitação flips to encerrada. The encerrada/todas sets therefore grow over time; consultations that closed before the first ingestion aren't captured (out of scope). The list/analysis tools default to status: aberta.
3. Two reconciled cadences (one shared writer contract). The job reuses contentHash + the ConsultaResumo builder + classifyRun from src/scraper/, so its rows are byte-identical to the Cron's. The weekly job owns the long tail; the 2h Cron keeps the ~5 hot/open highlights fresh via a targeted metric splice (recorded as ok-metrica, bypassing the corpus classifyRun baseline). Corpus freshness (possivelDesatualizacao) is computed from the last status='ok' run and uses a larger window (ECIDADANIA_CORPUS_STALE_MAX_MIN), and a stale consultas corpus is served from D1 flagged rather than collapsing back to the live highlights.

Write guards on the load: an incomplete crawl (any page failed) or an incomplete /processo status universe writes only an erro run row; even a complete crawl is rejected by a catastrophic floor (ECIDADANIA_CORPUS_MIN_PCT, default 80% of the last good corpus) to guard against a degraded page — overridable with --force / INGEST_FORCE=1 for a legitimate large shrink. Run weekly via the Action, or manually:

CLOUDFLARE_API_TOKEN=… npm run ingest:ecidadania                 # writes scripts/ingest-ecidadania/out.sql
npx wrangler d1 execute senado-ecidadania --remote --file=scripts/ingest-ecidadania/out.sql

Caching

Layer architecture

Cache categories

POST caching approach

MCP uses POST for all tools/call requests. Caching POST responses is not natively supported by the Cache API, which requires GET requests. The solution:

1. Hash parameters — Tool name + sorted parameters are hashed with SHA-256
2. Synthetic GET key — A synthetic URL https://senado-br-mcp.internal/__cache/{tool}/{hash} is constructed
3. Cache API match/put — The synthetic GET URL is used with caches.default.match() and caches.default.put(), allowing standard Cache API operations on POST-originated data

This caching happens at the tool level (inside each tool's callback), not at the MCP transport level.

Provenance

Every tool attaches a provenance envelope so a result is traceable back to its official source — provenance is treated as a first-class part of the answer, not an optional extra (the audience is journalists and political-science researchers, for whom an un-sourced figure is unusable). The envelope lives in structuredContent.provenance (parseable by clients, validated by the tool's output schema) and is mirrored as a one-line source footer in the text content for clients that only render text — the data JSON itself is not duplicated with the envelope, to keep the per-response token cost low (a fixed ≈170 chars).

Coverage spans all four upstream sources, each with its own source/attribution/license (in src/utils/provenance.ts):

• Senado Federal — Dados Abertos (Legislativo) — legis.senado.leg.br/dadosabertos
• Senado Federal — Dados Abertos (Administrativo) — adm.senado.gov.br/adm-dadosabertos
• Senado Federal — Execução Orçamentária e Financeira — Arquimedes/Financeiro feed at senado.gov.br
• Senado Federal — Portal e-Cidadania — www12.senado.leg.br/ecidadania

Fields (per response — one tool, one source):

retrieved_at fidelity is provided by the cache layer (cachedFetchWithMeta), which persists the fetch timestamp alongside the value, so it reflects the real upstream extraction even on a cache hit. Two exceptions report an honest live timestamp instead: the e-Cidadania list tools (read from D1) use the corpus's lastScrapedAt — the true age of the stored data — while e-Cidadania detail tools, scraped live, use the fetch time and a level-3 canonical item URL.

Coverage is universal: all 66 tools carry the envelope (verify with grep -c 'resultWithProvenance(' src/tools/*.ts). The ⊕ marks in the inventory below denote the original pilot tools (votes, bills, processes); the envelope now extends to every tool, so the marks are historical.

Tool Inventory

Group H — Reference/Metadata (1 tool)

Group A — Senators (5 tools)

Group B — Bills/Matters (2 tools, v3 backend)

Group C — Processes (5 tools)

Group D — Votes (3 tools)

Group E — Committees (7 tools)

Group F — Plenary (7 tools)

Group G — e-Cidadania (9 tools)

Group I — Speeches (3 tools)

Group J — Blocs & Leadership (4 tools)

Group K — Budget (1 tool)

Group L — Federal Law (2 tools)

Group M — Committee Voting (1 tool)

Group N — Taquigrafia (2 tools)

Group O — Senadores/Administrativo (2 tools)

Group P — Servidores / Gestão de Pessoas (4 tools)

Group Q — Contratações (6 tools)

Group R — Suprimento de Fundos (1 tool)

Group S — Orçamento do Senado (1 tool)

Total: 66 tools

Prompts (4)

Reusable pt-BR workflow templates (MCP prompts capability), defined in src/prompts.ts:

Resources (5)

Static context documents/tables (MCP resources capability), defined in src/resources.ts:

Project Structure

src/
├── index.ts              # Worker entrypoint (fetch handler + scheduled/Cron handler)
├── server.ts             # McpServer factory (creates per-request instance)
├── auth.ts               # Optional Bearer token auth (constant-time compare)
├── metrics.ts            # In-memory counters served at /metrics
├── types.ts              # Env, cache categories, safeguard constants
├── cache/
│   ├── l0-memory.ts      # In-memory Map cache with TTL + LRU eviction
│   ├── l1-cache-api.ts   # Cloudflare Cache API wrapper (synthetic GET keys)
│   └── manager.ts        # Cache orchestrator (L0 → L1 → upstream)
├── throttle/
│   ├── token-bucket.ts   # Token bucket rate limiter (global + per-client)
│   └── upstream.ts       # Upstream fetch with concurrency limit, retry, timeout
├── scraper/
│   ├── ecidadania.ts     # Isolated e-Cidadania scraper (REST lists + regex HTML detail; buildConsultaResumo)
│   ├── pipeline.ts       # 2h Cron: targeted highlight metric splice (consultas/eventos/ideias); corpora owned by the weekly jobs
│   ├── anomaly.ts        # Run classification (anomalous run never overwrites current)
│   └── store.ts          # D1 reads (resolveList + per-entity staleness, lastGoodRunAt) + detail write-through
├── instrument.ts         # Per-tool call telemetry (in-memory + Analytics Engine)
├── utils/
│   ├── logger.ts         # Structured JSON logging
│   └── validation.ts     # toolResult, toolError, errorFrom, buildParams, ensureArray helpers
└── tools/
    ├── referencia.ts        # Group H — 1 reference/metadata tool
    ├── senadores.ts         # Group A — 5 senator tools
    ├── materias.ts          # Group B — 2 bill/matter tools (v3 backend)
    ├── processos.ts         # Group C — 5 process tools
    ├── votacoes.ts          # Group D — 3 vote tools
    ├── comissoes.ts         # Group E — 7 committee tools
    ├── plenario.ts          # Group F — 7 plenary tools
    ├── ecidadania.ts        # Group G — 8 e-Cidadania tools (read from D1; see scraper/)
    ├── discursos.ts         # Group I — 3 speech tools
    ├── composicao.ts        # Group J — 4 bloc/leadership tools
    ├── orcamento.ts         # Group K — 1 budget tool
    ├── legislacao.ts        # Group L — 2 federal law tools
    ├── votacao-comissao.ts  # Group M — 1 committee voting tool
    ├── taquigrafia.ts       # Group N — 2 stenographic record tools
    ├── senadores-admin.ts   # Group O — 2 admin senator tools (CEAPS, housing)
    ├── servidores.ts        # Group P — 4 personnel tools
    ├── contratacoes.ts      # Group Q — 6 procurement tools
    ├── supridos.ts          # Group R — 1 petty-cash tool
    └── orcamento-senado.ts  # Group S — 1 budget execution tool
scripts/
└── ingest-ecidadania/    # Off-Worker weekly full-corpus consultas ingestion (run via `npm run ingest:ecidadania`)
    ├── index.ts          # Orchestrator: crawl → status (/processo) → normalize → guards → out.sql
    ├── listing.ts        # Pure listing parser (parseConsultaListingPage, findLastPage)
    ├── status.ts         # tramitando=S set from /processo → aberta/encerrada (deriveStatus)
    ├── restatus.ts       # Linger fix: re-status stored rows by /processo membership (close zombies)
    ├── http.ts           # Polite fetch (retry/backoff) for the unattended crawl
    ├── d1.ts             # D1 pre-reads (existing meta, payloads, last good rows) via wrangler
    └── sql.ts            # out.sql generation (mirrors SQL.upsert/SQL.history; reuses SyncRecord)
.github/workflows/        # publish-mcp.yml (registry) + ingest-ecidadania.yml (weekly D1 corpus load)
migrations/               # D1 schema (0001 tables, 0002 indexes) for the e-Cidadania pipeline
tests/                    # Vitest unit tests mirroring src/ (parsers, cache, throttle, auth, scraper,
                          # pipeline/anomaly/store, listing/sql/highlights, plus e-Cidadania contract tests)

Environment Variables

Connecting MCP Clients

This is a remote server (Streamable HTTP, no install, open access) — point any MCP client at https://senado.sidneybissoli.com/mcp. Besides 66 tools, it exposes prompts (ready-made pt-BR workflows: senado_gastos_senador, senado_tramitacao_materia, senado_votos_senador, senado_panorama_ecidadania) and resources (senado://guia, senado://catalogo, senado://glossario, senado://tabelas/tipos-materia, senado://tabelas/ufs).

One-click (LobeHub)

Install from the LobeHub marketplace — open the server page and click Install (it pre-fills the remote endpoint, no config needed).

Claude Desktop / Claude Code

Add to your MCP configuration:

{
  "mcpServers": {
    "senado-br": {
      "url": "https://senado.sidneybissoli.com/mcp"
    }
  }
}

For command-based clients (or any client without native remote support), use the mcp-remote bridge:

{
  "mcpServers": {
    "senado-br": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://senado.sidneybissoli.com/mcp"]
    }
  }
}

MCP Inspector

npx @modelcontextprotocol/inspector https://senado.sidneybissoli.com/mcp

License

MIT

Credits

Icon: "Amanhecer no Congresso Nacional" — photograph of the Brazilian National Congress, used under a Creative Commons license. (If you are the author, open an issue so we can add full attribution / the license link.)