Senado Brasil MCP Server
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.
Compared with the alternatives
Other Brazilian MCP servers also touch the Senate — mcp-brasil and mcp-dados-br are multi-source aggregators in which the Senate is one source among many. The difference is coverage and how you run it. Measured in each one's source code on 2026-10-11:
Pick an aggregator when the question crosses the Senate with the Chamber of Deputies, the electoral court (TSE) or the Transparency Portal. Pick this server for expenses (CEAPS), staff, contracts, budget, speeches, committee votes, vetoes or e-Cidadania — areas the others don't cover. Full per-area table, side-by-side examples and how to re-measure (in Portuguese): docs/comparativo-alternativas.md.
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
createMcpHandlerfromagents/mcp - Protocol: MCP over JSON-RPC —
/mcphandles the full public server;/mcp/openai-app-v2exposes a curated 27-tool profile plus a shared MCP Apps widget for OpenAI app review/submission (/mcp/openai-appremains as a legacy alias) - SDK:
@modelcontextprotocol/server2.x (per-request McpServer instances; the v1@modelcontextprotocol/sdkis not installed —agentsstill lists it as a peer, satisfied vialegacy-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 measuredretrievaldiagnostics (trips, attempts, anomalies) - Auth: Optional Bearer token (set the
API_KEYsecret; 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
/healthand/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
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.
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; 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:
- a daily off-Worker GitHub Action owns the full corpus of the three live entities (
consultas,eventos,ideias; see below) — the source of truth. Daily (not weekly) because the first-seen seriesMIN(scraped_at)is the only measurable entry-rhythm signal and every skipped day permanently shortens it (ROADMAP Etapa 2, decisão D3); - a weekly ingest Action (
.github/workflows/verify-consultas-votos.yml— historical filename) for theconsultas_votosacervo: the Senado republishes the Arquimedes CSV periodically (confirmed 2026-07-20), so the weekly run re-ingests the current vintage under the same anomaly guards as the other corpora (see below); - 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 asok-metricaso it never re-breaks the corpus baseline and never touches the long tail. In v2 the eventos splice preserves the corpus's canonical comment count (the daily crawl is the source of truth forcomentarios, so the splice can't ping-pong it against the degraded REST count).
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_historyonly when an item'scontent_hashchanges (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)
The three live e-Cidadania corpora are owned by the daily 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). In v2 each crawled matter is also enriched from its detail page (visualizacaomateria) forautoria/relator; those are immutable, so only rows not yet enriched are fetched.eventos— audiências/eventos from theprincipalaudiencia?p=NHTML listing; status comes straight from the listing block (no/processobridge). In v2 every event is enriched from its detail page (canonicaldata/hora+comissaoNomeCompleto/local/descricao/pauta/convidados/videoUrl) and its AJAX comment fragment (canonical count + oneecidadania_comentariosrow per comment, diffed against the stored hashes and emitted asout-eventos-comentarios-*.sql).ideias— ideias legislativas (~113.7k) frompesquisaideia?situacao=N&p=M, crawled persituacaobucket (the listing has no inline status) and emitted in ~10k-statement batches. In v2 the listing crawl preserves the immutable detail fields, and a separate resumable backfill (index-ideias-detalhe.ts, run viaingest:ecidadania:ideias-detalhe) fills them a chunk per run — because ~113.7k detail fetches don't fit one Action, it persists a cursor inecidadania_detalhe_cursorand wraps around at the end.
The fourth entity, consultas_votos, is 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 data_vintage; it is excluded from the row hash (consultaVotoCore) so a re-ingest with unchanged 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). It is excluded from the daily job and owned by its own weekly ingest Action (.github/workflows/verify-consultas-votos.yml — the filename keeps the historical verify- prefix): the acervo was originally treated as a frozen single vintage (ROADMAP Etapa 2, decisão D1) and the weekly run only verified it, but on 2026-07-20 the Senado republished the CSV as a fresh vintage (+43 matérias, 648 updated), so the scheduled run now re-ingests the current vintage under the standard anomaly guards (empty/truncated CSV and the catastrophic floor still fail without writing; force dispatch overrides the floor). The script's verify mode (INGEST_CONSULTAS_VOTOS_VERIFY=1 / --verify) remains available as an on-demand integrity check.
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:
- Decoupled ingestion. The open set is acquired by an off-Worker TypeScript job (
scripts/ingest-ecidadania/, run by a daily 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. - Status from
/processo, not HTML. A consultation runs from presentation until the end of tramitação, sostatusis a function of the matter: aberta ⟺ thecodigoMateriais in the/processotramitando=Sset, derived from robust JSON (never scraped). Every consultation enters asaberta(the listing only yields in-tramitação matters); on each complete run the job re-derives status for all stored rows by/processomembership (not by listing-absence, which can be transient), so a consultation whose matter leaves tramitação flips toencerrada. Theencerrada/todassets therefore grow over time; consultations that closed before the first ingestion aren't captured (out of scope). The list/analysis tools default tostatus: aberta. - Two reconciled cadences (one shared writer contract). The job reuses
contentHash+ theConsultaResumobuilder +classifyRunfromsrc/scraper/, so its rows are byte-identical to the Cron's. The daily job owns the long tail; the 2h Cron keeps the ~5 hot/open highlights fresh via a targeted metric splice (recorded asok-metrica, bypassing the corpusclassifyRunbaseline). Corpus freshness (possivelDesatualizacao) is computed from the laststatus='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 daily 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:
- Hash parameters — Tool name + sorted parameters are hashed with SHA-256
- Synthetic GET key — A synthetic URL
https://senado-br-mcp.internal/__cache/{tool}/{hash}is constructed - Cache API match/put — The synthetic GET URL is used with
caches.default.match()andcaches.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 implements the portfolio-wide provenance contract (@sbissoli/mcp-provenance): the server builds and validates a full canonical model per response, and emits its concise projection — a fixed-order block with explicit null for unknown fields; responses that merge several upstream reads also list each part with its own extraction instant (field_sources), and the block's retrieved_at is then the oldest of them. The block lives in structuredContent.provenance (parseable by clients; note the advertised per-tool output schema is permissive, so contract validation happens server-side at build time, in the package) and is mirrored as a compact 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.
Coverage spans all four upstream sources, each with its own source/citation/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 of the concise block (contract v1.3 since 3.18.5; per response — one tool, one source; keys in this fixed order; the first seven are always present, with null when the source does not expose the value; the optional ones are absent, never empty, when they do not apply):
No Senate source publishes notices alongside the data, so notices (also part of v1.3) does not appear. The text footer gains a line only for exceptions — here, the computed-values line on the estatisticas modes.
The canonical model behind the block also carries dataset.id (item/series identifier, e.g. codigoMateria=137808) and api_version; those are validated on every build and inform attribution (below), but are not part of the concise projection.
In addition to the provenance envelope, structuredContent carries a top-level attribution list — the distinct source URLs behind the response. This mirrors the naming proposed in modelcontextprotocol#711 (where attribution is a list of source references at the response level), so the server stays forward-compatible if that RFC lands; the richer provenance object remains this server's own extension.
Out-of-band mirror in _meta. The same provenance and attribution are also mirrored on the result's _meta under namespaced keys (com.sidneybissoli.senado/provenance and com.sidneybissoli.senado/attribution). The MCP spec keeps _meta for metadata about a result that should not steer the model, which is where the still-incubating trust/attribution work from #711 (split into an experimental extensions track, not yet in core) points; mirroring there gives audit and UI consumers the provenance without reading the model-facing data channel, at no model-token cost, while structuredContent keeps it visible so the model can cite the source. The mirror survives the ChatGPT-app profile minimizer (which only strips structuredContent.meta).
Field-level granularity. Most tools are single-source, so one envelope suffices. The few that merge reads in one response fill field_sources — a list of { fields, source_url, dataset_id, data_vintage, retrieved_at, served_from_cache } attributing specific output fields to their real origin, and the block's retrieved_at is the oldest of them. served_from_cache is true/false for reads through the server cache and null where the notion does not apply (the bundled org-chart snapshot, the e-Cidadania corpus in D1). The merging tools (since 3.18.2): senado_obter_materia secao=detalhe (/processo/{id} + ementa from /processo + relator from /processo/relatoria), senado_obter_senador and the Deep Research fetch of a senator (biography + mandatos/emExercicio from /senador/{codigo}/mandatos), senado_reunioes_comissao over a window that crosses the year (one read per year), senado_servidores with subordinadasA (payroll + org-chart snapshot), senado_suprimento_fundos statistics on atos-concessao (acts + beneficiary names from the supridos registry), senado_ecidadania_obter_evento (live detail + comentarios from the corpus) and senado_ecidadania_sugerir_tema_enquete (consultas and ideias corpora). Only a read that becomes a field of the answer is a sub-source: a read that only resolves or checks an identifier (a committee acronym → its code, the parent check in senado_contratacao_detalhe) is left out, otherwise a cached lookup table would make the whole answer claim to be as old as it. attribution always lists every distinct underlying source_url.
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, or the live scrape instant when the corpus is empty or stale and the list falls back to the portal (since 3.18.3; before, the stale corpus's instant leaked into the live answer) — while e-Cidadania detail tools, scraped live, use the fetch time and a level-3 canonical item URL. The only path that falls back to the build-time default is the in-code static reference catalog (senado_tabelas_referencia tipos-materia), which has no upstream extraction instant.
Coverage is universal: all 69 tools carry the envelope — the 67 senado_* tools via resultWithProvenance( (verify with grep -c 'resultWithProvenance(' src/tools/*.ts) and the two Deep Research tools via provenanceExtras (same block, in structuredContent/_meta, since their text channel is the contract's JSON). 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.
Citable dataset (e-Cidadania participation)
Beyond the live server, this project publishes a frozen, versioned, citable dataset of the e-Cidadania participation layer (public consultations, legislative ideas, interactive events + their comments, historical votes by state) — the layer the R package congressbr never covered. Each value carries a per-field provenance envelope ({ value, sourceEndpoint, sourceField, retrievedAt, license, schemaVersion }); the data license (Dados Abertos do Senado Federal) is kept separate from the code license (MIT).
- How to cite —
CITATION.cff(dataset; cite the version-DOI of the snapshot you used, the concept-DOI for the dataset across versions). - What's in each release —
CHANGELOG-dataset.md(cumulative, append-only; binds each release to itsschemaVersion). - Variable dictionary & field provenance —
docs/dataset-dictionary.md(generated fromsrc/dataset/schema.ts, the single source of truth). - Data license —
LICENSE-DATA.md. - Cutting a release (freeze → checksums → GitHub Release → Zenodo DOI) —
docs/release-runbook.md; machinery insrc/dataset/,scripts/build-dataset/, and.github/workflows/release-dataset.yml.
Inventory — schema v2 (schemaVersion 2.0.0)
Each release ships one NDJSON resource per entity (one HarmonizedRecord per line: identity + a provenance envelope per field), plus a datapackage.json manifest and a copy of the dictionary. Five resources:
ⁿ = new/reopened in v2 · ᶜ = source corrected to the canonical one in v2. What v2 (2.0.0) changed — the ingestion moved from listing-only to listing + detail (+ AJAX comments for events):
- Eventos corrected & enriched.
data/horanow come from the detail page (canonical — the estudo A3 found the listing 57% divergent onhora), plus six new detail fields (comissaoNomeCompleto,local,descricao,pauta,convidados,videoUrl).comentariosis now the canonical AJAX count (the listing count was0-spurious in 82% of events, capturing only ~6.7% of engagement). - New comment-level resource
eventos_comentarios— one row per audiência comment, the participation signal nobody else publishes versioned. - Detail-only fields reopened for
ideias(dataPublicacao,autorUf,descricao,plConvertido) andconsultas(autoria,relator) — previously alwaysnullby design. - Privacy posture by data origin. Citizen content (audiência comments, idea authors) keeps UF only — never the name, discarded at the parser; public agents (consulta authorship/rapporteur, event guests) keep the name (public by function). See
docs/schema-v2-inventario.mdfor the field-by-field rationale (approved target).
The frozen NDJSON is not committed (built from the sovereign D1 corpus on demand); a tagged dataset-v* release attaches the tarball + SHA256SUMS + release.json and archives them on Zenodo.
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)
Group T — Estrutura Organizacional (1 tool)
Reads a bundled snapshot of the Senate's organizational tree (crawled from the institutional portal down to serviço level by npm run ingest:estrutura), since the open-data API only publishes units down to Secretaria and never links a leaf unit to its parent. Units the portal lists only by name, without a page of their own (the CONLEG/CONORF núcleos), are captured as synthetic nodes from the page's indented listing. Congress-wide bodies where the servant registry records lotações (CMO, CPCMS, CMMC) come from a curated complement (src/estrutura/complemento-cn.ts, public source: congressonacional.leg.br) under a separate Congresso Nacional root (CN) — never under the Senate tree, so subordinadasA: "DGER" excludes them while subordinadasA: "CN" counts them. Servants recorded under the situational pseudo-units "Servidores Afastados/em Trânsito - SF" are reported separately as afastadosOuEmTransito by senado_servidores.
Group U — Deep Research (2 tools)
The OpenAI Deep Research contract: the only two tools without the senado_ prefix, because the names are fixed by the contract. Registered through the same shim as the others (read-only annotations, the shared output envelope — open data plus required provenance + attribution —, per-tool telemetry) and served on /mcp only — the curated ChatGPT app profile does not include them. The index (senators in office + active committees, ~300 documents) is built on first use from the same two list endpoints the senado_listar_* tools read, and kept for 24 h.
Total: 69 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 off-Worker 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
└── estrutura.ts # Group T — 1 org-structure tool (reads src/data/ snapshot via src/estrutura/)
scripts/
└── ingest-ecidadania/ # Off-Worker 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
├── verify.ts # consultas_votos on-demand integrity-check verdict (verifyAcervoIntegrity)
└── sql.ts # out.sql generation (mirrors SQL.upsert/SQL.history; reuses SyncRecord)
.github/workflows/ # ingest-ecidadania.yml (daily D1 corpus load), verify-consultas-votos.yml
# (weekly frozen-acervo integrity check), publish-mcp.yml (registry),
# usage-report.yml (monthly Analytics report), deprecate-registry.yml
# (all pinned to current Node 24 action majors — see each YAML for exact versions)
migrations/ # D1 schema (0001 tables, 0002 indexes, 0003 comment level + detail cursor) 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 69 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.)
