Senado BR — Brazilian Federal Senate Open Data
Senado BR is a hosted MCP server that gives AI assistants live, structured, provenance-backed access to Brazilian Federal Senate open data via 69 tools, 4 prompts, and 5 resources.
Explore senators: list current, former, or legislature-specific senators with UF/party/name filters; get biographies, mandates, historical roles, absences, votes, and speeches/transcripts.
Research legislation: search bills/matters and processes; inspect details, tramitação, texts, amendments, rapporteurs, deadlines, authorship rankings, and enacted federal laws.
Check votes and plenary activity: plenary and committee votes, nominal vote details, party leadership voting instructions, agendas, session results, vetoes, and veto vote results.
Inspect committees and Congress: committees, members, meetings, agendas, CPI requirements, blocs, leadership, and Mesa Diretora.
Analyze Senate spending: CEAPS quotas, housing/office allowances, payroll, overtime, personnel tables, contracts, biddings, outsourced staff, companies, price records, petty cash, and budget execution—including statistics and rankings.
Track citizen participation: e-Cidadania consultations, consensus/polarization analysis, legislative ideas, interactive events/comments, historical consultation votes by UF, and poll-theme suggestions.
Use reference and discovery tools: reference tables for matter types, parties, UFs, legislatures, legal norm types, process tables; plus Deep Research
search/fetchfor senators and committees.Rely on provenance: each response includes source, source URL, timestamp, citation, license, and retrieval diagnostics; results are in Portuguese and come live from official Senate APIs/portal.
Integrate easily: point an MCP client at the hosted Streamable HTTP endpoint or run locally via npm/stdio; prompts and resources provide guided workflows, glossary, and catalog context.
Exposes a curated MCP surface tailored to OpenAI's Apps SDK and Deep Research contract — including the required search and fetch tools, a 27-tool ChatGPT app profile at /mcp/openai-app-v2, and an MCP Apps UI dashboard template that renders structured results — so ChatGPT-based assistants can query Brazilian Senate open data (senators, bills, votes, expenses, committees) with provenance.
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
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.
Related MCP server: mcp-camara
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:
Senate tools | Covers | Where it runs | |
senado-br-mcp (this) | 69 | legislative, administrative (CEAPS, staff, contracts, budget) and e-Cidadania, with provenance on every answer | hosted, no install or key; or |
mcp-brasil 0.14.0 | 26 | legislative (senators, bills, floor votes, committees, agenda) — plus dozens of other government sources | local or self-hosted (Python) |
mcp-dados-br 0.6.0 | 3 | sitting senators, bill list, vote tally — plus IBGE, BCB, INMET, Chamber of Deputies | local (Python) |
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/mcpOpenAI / 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-v2This 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/privacyTerms 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/mcpsearch 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/mcpOne-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/mcpProtocol: 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-freeLiveness: 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 endpointTests: 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 install2. 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 --remoteThe 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/mcp6. Tests and typecheck
npm test # run all tests once
npm run test:watch # watch mode
npm run typecheck # tsc --noEmit7. 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) |
| POST, GET, DELETE, OPTIONS | MCP Streamable HTTP endpoint (managed by |
| GET | Health check — returns |
| GET | JSON: |
| GET | JSON counters: requests, tool calls, cache hits/misses, upstream calls/retries/errors, auth failures (always public) |
| GET | MCP server card for directory scanners (Smithery): |
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-cloudflareMCP 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 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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.sqlCaching
Layer architecture
Layer | Storage | Scope | TTL range | Purpose |
L0 | In-memory | Per-isolate | 30-300s | Ultra-fast, eliminates redundant requests within a Worker isolate |
L1 | Cloudflare Cache API ( | Per-colo (PoP) | 60-600s | Shared across requests at the same edge location |
L2 | KV (optional) | Global | Variable | Reserved for rare, low-write data |
Cache categories
Category | L0 TTL | L1 TTL | Used for |
STATIC | 300s | 600s | Legislation types, static reference |
SEMI_STATIC | 120s | 300s | Party list, UF list, committee details |
DYNAMIC | 30s | 60s | Agendas, recent votes, meeting lists |
ON_DEMAND | 30s | 120s | Specific bill/senator/vote lookups |
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 constructedCache 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/dadosabertosSenado Federal — Dados Abertos (Administrativo) —
adm.senado.gov.br/adm-dadosabertosSenado Federal — Execução Orçamentária e Financeira — Arquimedes/Financeiro feed at
senado.gov.brSenado 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):
Field | Meaning |
| Official source name (e.g. Senado Federal — Dados Abertos (Legislativo)) |
| Canonical endpoint/item URL consulted (e.g. |
| Vintage/competência of the data (e.g. |
| ISO-8601 of the upstream extraction — carried through the cache, so it reflects when the data was actually fetched, not the build or the cache-hit time; on merged responses, the oldest of the parts |
| Measured diagnostics of the trip to the source (attempts, outcome), or |
| Ready-to-use citation string (human-readable) |
| Source terms (Dados Abertos do Senado Federal) |
| Optional. Per-field sub-sources, each with its own extraction instant — only on responses that merge reads (v1.2, since 3.17.0; see below) |
| Optional. |
| Whether the figure may still change at the source: |
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_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), senado_listar_senadores with legislatura (since 3.24.0: the legislature list + emExercicio from /senador/lista/atual) 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:
Resource ( | Grain | Key variables | Source(s) |
| 1 public consultation (matéria) |
|
|
| 1 legislative idea (~113.7k) |
|
|
| 1 interactive event (audiência) |
|
|
| 1 comment (comment-level) |
| AJAX fragment |
| 1 matéria (historical acervo) |
| Arquimedes CSV |
ⁿ = 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)
Tool | Description |
| Tabelas de referência via |
Group A — Senators (5 tools)
Tool | Description |
| Lista senadores em exercício, fora de exercício ( |
| Detalhe biográfico de um senador: bio, mandatos, partido, contato |
| Como um senador votou em cada matéria (via v3 |
| Histórico funcional via |
| Senadores atualmente afastados (fora de exercício) |
Group B — Bills/Matters (2 tools, v3 backend)
Tool | Description |
| Busca matérias por tipo, número, ano, palavra-chave, autor ou tramitação (via v3 |
| Dados de uma matéria via |
Group C — Processes (5 tools)
Tool | Description |
| Busca processos legislativos (complementar à busca de matérias) |
| Detalhes completos de um processo legislativo específico |
| Aspecto de um processo via |
| Parlamentares autores de processos em tramitação, ordenados por produção |
| 12 tabelas de referência (siglas, assuntos, classes, tipos-*) via |
Group D — Votes (3 tools)
Tool | Description |
| Detalhes de uma votação com votos nominais. Aceita |
| Votações de uma matéria (via v3 |
| Busca/listagem flexível de votações do plenário por |
Group E — Committees (7 tools)
Tool | Description |
| Lista comissões (colegiados) ativas, filtráveis por tipo |
| Dados de uma comissão via |
| Reuniões de uma comissão num período de até 30 dias (lida dia a dia; o que é depois de hoje vem à parte, como agenda prevista) |
| Agenda de reuniões de todas as comissões numa data |
| Detalhe completo de uma reunião: partes, itens, convidados, resultados, links pauta/ata |
| Requerimentos protocolados numa CPI em atividade, paginados (upstream costuma vir vazio mesmo para CPIs ativas; retorno vazio traz |
| Estatísticas de carga por senador numa comissão: autoria ou relatoria |
Group F — Plenary (7 tools)
Tool | Description |
| Plenary schedule — by day, month or Congress (escopo dia/mes/cn) |
| Session results: items deliberated, opinions, outcomes (SF/CN/month) |
| Party leadership voting instructions per vote, with tallies |
| Presidential vetoes by year or tramitation status |
| Nominal veto vote results (by veto, vetoed bill or device) |
| Legislative session detail, agenda items, results or summary |
| Session types, attendance types, legislatures list |
Group G — e-Cidadania (9 tools)
Tool | Description |
| Consultas públicas (conjunto completo das abertas — matérias em tramitação) com votação sim/não; filtro |
| Detalhe de uma consulta: votos, autor, relator, comentários |
| Analisa o conjunto completo de consultas abertas via |
| Ideias legislativas de cidadãos; ranking das mais apoiadas via |
| Detalhe de uma ideia: texto, apoios, data em que foi proposta, linha do tempo (meta, Sugestão, decisão da CDH, encerramento) e proposições em que virou |
| Eventos interativos (audiências, sabatinas, lives); ranking dos mais comentados via |
| Detalhe de um evento: pauta, convidados, link de vídeo |
| Sugere temas para enquete mensal a partir de critérios configuráveis |
| Acervo histórico de votos das consultas com quebra por UF (CSV Arquimedes); ranking por |
Group I — Speeches (3 tools)
Tool | Description |
| Pronunciamentos de um senador via |
| Todos os discursos em plenário num intervalo de datas |
| Texto integral de um pronunciamento/discurso específico |
Group J — Blocs & Leadership (4 tools)
Tool | Description |
| Blocos parlamentares do Senado e seus partidos membros |
| Detalhes de um bloco parlamentar específico |
| Lideranças do Senado/Câmara/Congresso (líderes, vice-líderes) com o bloco/partido liderado, filtráveis |
| Membros da Mesa Diretora via |
Group K — Budget (1 tool)
Tool | Description |
| Emendas parlamentares ao orçamento via |
Group L — Federal Law (2 tools)
Tool | Description |
| Busca normas jurídicas federais por tipo, número, ano ou data (ao menos um obrigatório) |
| Detalhes de uma norma jurídica federal específica |
Group M — Committee Voting (1 tool)
Tool | Description |
| Votações em comissões via |
Group N — Taquigrafia (2 tools)
Tool | Description |
| Official transcripts of plenary sessions or committee meetings — summary mode with excerpts, full-text mode paginated in blocks, speaker filter |
| Video/audio units per session or meeting, with speaker and media links |
Group O — Senadores/Administrativo (2 tools)
Tool | Description |
| CEAPS parliamentary quota expenses by year — aggregated by senator, expense type, month or supplier, or itemized detail; |
| Dados administrativos dos senadores via |
Group P — Servidores / Gestão de Pessoas (4 tools)
Tool | Description |
| Civil servants by status (active/effective/commissioned/inactive), filterable by name, unit, position |
| Monthly payroll — summary by payroll type or per-person composition with computed gross; |
| Overtime payments by month with totals; |
| Tabelas de pessoal via |
Group Q — Contratações (6 tools)
Tool | Description |
| Contracts filtered in-Worker over the full base (accent-insensitive): supplier, CNPJ, year, number, object, labor |
| Items, payments, guarantees, amendments or activations of a contract/ata/empenho |
| Biddings by number or object text |
| Outsourced collaborators by name, company or unit |
| Companies contracting with the Senate (requires name/CNPJ filter) |
| Price-registration atas, commitment notes, young apprentices |
Group R — Suprimento de Fundos (1 tool)
Tool | Description |
| Petty-cash advances by year: recipients, concession acts, commitments, movements, card transactions; |
Group S — Orçamento do Senado (1 tool)
Tool | Description |
| Budget execution since 2013 (allocation, committed/settled/paid) and own revenues since 2012 (forecast vs collected) — aggregated by year, action, expense group, source or revenue origin; |
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.
Tool | Description |
| Organizational chart (organograma) resolved for a |
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.
Tool | Description |
| Ranks the query (natural language or keywords, pt/en, accent-insensitive) against senators in office and active committees; returns up to 10 |
| Returns the document for an id from |
Total: 69 tools
Prompts (4)
Reusable pt-BR workflow templates (MCP prompts capability), defined in src/prompts.ts:
Prompt | Args | What it guides |
|
| Resolve o senador e agrega/detalha despesas CEAPS. |
|
| Obtém situação atual + histórico de tramitação da matéria. |
|
| Lista os votos nominais do senador no período. |
| — | Consolida consultas (consenso/polarização), ideias e eventos populares. |
Resources (5)
Static context documents/tables (MCP resources capability), defined in src/resources.ts:
URI | Type | Content |
| markdown | Visão geral e qual ferramenta usar por objetivo. |
| markdown | As 69 ferramentas agrupadas por domínio. |
| markdown | Siglas e termos do Senado (PEC, CEAPS, CCJ, RCN…). |
| json | Tipos de proposição (sigla/nome/descrição). |
| json | As 27 unidades federativas. |
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
Variable | Required | Default | Description |
| No |
| Legislative API base URL |
| No |
| Administrative API base URL |
| No |
| CORS allowed origin |
| No (secret) | — | When set, requires |
| Yes (binding) | — | KV namespace for L2 cache |
| Yes (binding) | — | D1 database for the e-Cidadania pipeline (list persistence + history) |
| No |
| Staleness window (minutes, ~10d) for the off-Worker full corpora (all e-Cidadania entities) — served flagged, never collapsed to highlights |
| No |
| Catastrophic floor for the off-Worker corpus jobs: a complete crawl/parse below this % of the last good corpus is rejected |
| No (secret) | — | GitHub Actions secret (D1 edit scope) for the corpus ingestion / integrity-check jobs; not used by the Worker |
| No (Actions var) | — | GitHub Actions repo variable so wrangler skips |
| No (binding) | — | Analytics Engine dataset for per-tool call telemetry |
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/mcpLicense
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.)
Available Tools
69 toolsfetchDocumento para Deep ResearchARead-onlyIdempotentInspect
Returns the full document for an id obtained from search, as { id, title, text, url, metadata }: text is the readable content (Markdown) and url the canonical public page to cite.
Companion of search in the OpenAI Deep Research contract, over the Brazilian Federal Senate open data (senators in office and active committees of the Senate and the National Congress) catalog. Only ids returned by search are valid; an unknown id returns an error.
The senado_* tools remain the tools for data queries.
Behavior: read-only and idempotent — a live GET against the public source when the document needs it.
Inputs: id (required). Returns: provenance, attribution
searchBusca para Deep ResearchARead-onlyIdempotentInspect
Searches the Brazilian Federal Senate open data (senators in office and active committees of the Senate and the National Congress) catalog and returns up to 10 matching documents as { id, title, url }, ordered by relevance (an empty list means nothing matched).
This tool exists for the OpenAI Deep Research contract: ChatGPT deep research, company knowledge and research workflows over the Responses API require exactly the tools search and fetch. Pass one of the returned ids to fetch to read the document.
For direct questions and for data (values, series, rankings) prefer the senado_* tools, which return the actual data with provenance — this is a catalog index, not a data query.
Query: natural language or keywords, Portuguese or English; accents and case are ignored.
Behavior: read-only and idempotent — the catalog comes from the public source and is cached in memory.
Inputs: query (required). Returns: provenance, attribution
senado_agenda_comissoesAgenda das comissõesARead-onlyIdempotentInspect
Obtém a agenda de reuniões de todas as comissões numa data (data YYYYMMDD; padrão: hoje), com filtro opcional siglaComissao. Retorna { data, siglaComissao, count, reunioes }, cada reunião com codigo, comissao (sigla, nome), descricao, data, hora, local, tipo e situacao. Para o histórico de uma única comissão por período use senado_reunioes_comissao; para detalhes de uma reunião use senado_reuniao_comissao com o codigo.
Inputs: data, siglaComissao. Returns: provenance, attribution
senado_agenda_plenarioAgenda do plenárioARead-onlyIdempotentInspect
Obtém a agenda de sessões de plenário (Senado ou Congresso Nacional), por dia ou mês, com a pauta de matérias a votar. Retorna { data, escopo, count, sessoes }, onde cada sessão traz codigo, data, hora, tipo, situacao e pauta (matéria, ementa, autor, parecer). Use escopo dia/mes/cn; sem data assume hoje. Para o resultado já apreciado use senado_resultado_plenario; detalhes de uma sessão via senado_encontro_plenario.
Inputs: data, escopo, dataFim. Returns: provenance, attribution
senado_autores_atuaisAutores em exercícioARead-onlyIdempotentInspect
Lista parlamentares autores de processos em tramitação, ordenados por produção (maior número de matérias primeiro). Atenção à semântica: 'atual' significa 'com processo AINDA EM TRAMITAÇÃO', não 'mandato vigente' — a lista mistura senadores, deputados e ex-parlamentares, e a mesma pessoa pode aparecer 2× com códigos distintos (ex.: como 'Senador' e como 'Deputado', pelo tratamento); não use como lista de senadores em exercício (para isso, senado_listar_senadores). Retorna { count, total, autores }, cada autor com codigo, nome, tratamento, uf e quantidadeMaterias. Filtros opcionais uf e nome (busca parcial sem acento); limite padrão 50 (máx. 1000). Use o codigo em senado_obter_senador ou senado_search_processos (codigoParlamentarAutor).
Inputs: uf, nome, limite. Returns: provenance, attribution
senado_buscar_legislacaoBuscar legislação federalARead-onlyIdempotentInspect
Busca normas jurídicas federais já promulgadas (leis, decretos, leis complementares, emendas constitucionais etc.) combinando os filtros tipo, numero, ano e data em modo AND; informe ao menos um: uma chamada sem nenhum filtro retorna erro determinístico, não uma lista vazia. Somente leitura, sem efeitos colaterais; consulta ao vivo à base oficial de dados abertos, cujos resultados podem variar entre chamadas. Retorna { count, normas } sem paginação: count é o total de normas que casam (0, sem erro, quando nenhuma casa) e cada item traz codigo, tipo, descricaoTipo, numero, ano, data (ISO AAAA-MM-DD), norma, ementa e apelido, com null nos campos ausentes. Passe o codigo a senado_obter_legislacao para obter a indexação temática e a URL do texto integral. Para proposições ainda em tramitação (PEC, PL, PLP, MPV) use senado_buscar_materias; esta ferramenta cobre apenas normas já promulgadas.
Inputs: ano, data, tipo, numero. Returns: provenance, attribution
senado_buscar_materiasBuscar matérias legislativasARead-onlyIdempotentInspect
Busca matérias legislativas por tipo (PEC, PL, PLP, MPV), número, ano, palavras-chave, autor, período de apresentação ou situação de tramitação; informe ao menos um critério. Para pedidos como 'matérias recentes sobre X', use palavraChave, ano ou dataInicioApresentacao/dataFimApresentacao, ordenarPor: 'dataApresentacao', ordem: 'desc' e limite baixo (ex: 10); não é necessário chamar detalhes para listar resultados. Retorna { count, total, materias[] }, cada item com codigo (codigoMateria), sigla, numero, ano, ementa, autor, situacao, dataApresentacao, url e tramitando. Use codigo em senado_obter_materia apenas quando o usuário pedir detalhe/tramitação/textos. limite padrão 100 (máx. 500); ao truncar inclui aviso. Ex.: { palavraChave: 'inteligência artificial', ano: 2025, limite: 10 } ou { sigla: 'PEC', numero: 45, ano: 2019 } (datas em YYYYMMDD ou ISO).
Inputs: ano, ordem, sigla, limite, +7 more. Returns: provenance, attribution
senado_ceapsGastos CEAPS (cota parlamentar)ARead-onlyIdempotentInspect
Despesas da Cota para Exercício da Atividade Parlamentar (CEAPS) dos senadores em um ano. A fonte também publica lançamentos NEGATIVOS, sem rótulo próprio (a maioria em passagens aéreas, com jeito de crédito ou estorno): eles entram nas somas e totais como desconto e, nas estatísticas, aparecem como mínimo e no bottom — não leia um valor negativo como erro nem como 'a menor despesa'. Para perguntas de maior/menor/média/mediana/distribuição/ranking ('quem gastou mais CEAPS', 'gasto mediano', 'distribuição das despesas') use estatisticas=true: computa min/máx/média/mediana/desvio/percentis sobre TODAS as despesas filtradas e devolve top/bottom (padrão 10) com identificadores — os modos agregados só somam por grupo e não revelam a distribuição nem o extremo individual. Sem agruparPor → distribuicao das despesas individuais + top/bottom; com agruparPor (senador/tipo/mes/fornecedor) → grupos[] ranqueados por soma decrescente (grupos[0] = maior gastador), cada um com sua mini-distribuição. Sem estatisticas: nos modos agregados (por-senador/por-tipo/por-mes/por-fornecedor, padrão por-senador) traz agregado[] ordenado por total desc com chave, total e despesas (contagem); em modo='detalhe' traz despesas[] (mês, data, senador, tipoDespesa, fornecedor, cnpjCpf, valor). Filtre por mes, codSenador, nomeSenador, tipoDespesa ou fornecedor (busca parcial); limite cap 100 com aviso ao truncar. Obtenha codSenador via senado_listar_senadores.
Inputs: ano (required), mes, modo, topN, +7 more. Returns: provenance, attribution
senado_contratacao_detalheDetalhar contrataçãoARead-onlyIdempotentInspect
Detalha uma seção específica de uma contratação já identificada pelo id. tipo indica a natureza do registro: contratos (contrato firmado; padrão), atas_registro_preco (compromisso de preços para compras futuras) ou notas_empenho (reserva orçamentária do gasto). secao escolhe o aspecto: itens, pagamentos, garantias (qualquer tipo), aditivos (só contratos) ou acionamentos (só atas_registro_preco). Retorna { id, tipo, secao, count, total, itens } com os registros brutos da seção (campos conforme a API administrativa), limitados a limite (padrão 100, máx 500) — count < total indica truncagem; seção sem registros retorna count 0 e itens vazio (o id é conferido na lista-pai antes, então count 0 significa mesmo seção vazia, não contratação inexistente); id que não existe e combinações secao×tipo inválidas (ex.: aditivos fora de contratos) retornam erro. Atenção: a fonte NÃO publica o valor do contrato em nenhuma seção; apenas aditivos traz valor, referente ao termo aditivo (às vezes nulo) — não procure valor monetário em itens/pagamentos/garantias. Obtenha o id via senado_contratos ou senado_contratacoes_lista — para localizar a contratação (não detalhá-la) use aquelas ferramentas.
Inputs: id (required), secao (required), tipo, limite. Returns: provenance, attribution
senado_contratacoes_listaListar contrataçõesARead-onlyIdempotentInspect
Lista, conforme tipo, atas de registro de preço, notas de empenho ou menores aprendizes do Senado, com filtro textual opcional aplicado no Worker sobre todos os campos. Retorna { tipo, count, total, registros }; para atas_registro_preco/notas_empenho cada registro segue o formato de contrato (id, numero, objeto, empresa, subEspecie, vigencia...), enquanto menores_aprendizes vêm como registros brutos da API (campos não normalizados). Ordenação por ordem sobre a sequência de id do upstream: desc (padrão) = mais recentes primeiro, asc = mais antigos primeiro; offset pula registros para paginar a cauda. Limitado a limite (padrão 50, máx 500), com aviso ao truncar; tipo sem registros retorna lista vazia. Para aprofundar uma ata/empenho, use o id em senado_contratacao_detalhe.
Inputs: tipo (required), ordem, filtro, limite, +1 more. Returns: provenance, attribution
senado_contratosContratos do SenadoARead-onlyIdempotentInspect
Busca contratos administrativos do Senado por fornecedor, CNPJ, ano, número, objeto ou mão de obra (base completa baixada e filtrada no Worker; busca parcial sem acento em objeto/fornecedor/número). Retorna { count, total, contratos }, onde cada item traz id, numero, objeto, empresa {nome, cnpj}, subEspecie, dataAssinatura, vigencia e unidadeGestora. Atenção: a fonte NÃO publica o valor do contrato (nenhum campo monetário aqui nem nas seções de detalhe; apenas a seção aditivos de senado_contratacao_detalhe traz valor, referente ao termo aditivo) — não gaste chamadas procurando valor. A lista mistura subespécies (CT = contratos, AC = acordos de cooperação, TD = termos de doação etc.); distinga pelo campo subEspecie retornado. Limitado a limite itens (padrão 50, máx 500), com aviso quando há truncamento. Use o id retornado em senado_contratacao_detalhe para itens, pagamentos, garantias ou aditivos.
Inputs: ano, cnpj, limite, numero, +3 more. Returns: provenance, attribution
senado_discursos_plenarioDiscursos no plenárioARead-onlyIdempotentInspect
Lista todos os discursos realizados em plenário num período de datas (dataInicio/dataFim obrigatórias, formato YYYYMMDD). Retorna { periodo, count, discursos }, cada item com codigo, data, casa, tipoUsoPalavra, resumo, indexacao, url, nomeParlamentar, codigoParlamentar, partido e uf. Para discursos de um parlamentar específico use senado_discursos_senador; obtenha o texto integral com senado_discurso_texto.
Inputs: dataFim (required), dataInicio (required). Returns: provenance, attribution
senado_discursos_senadorDiscursos de um senadorARead-onlyIdempotentInspect
Lista pronunciamentos de um senador, filtráveis por período e casa. tipo (padrão discursos) alterna entre discursos (falas próprias) e apartes (intervenções em falas de outros) — muda a fonte upstream e o conteúdo, mantendo a mesma estrutura. Retorna { codigoSenador, tipo, count, discursos, periodosNaoLidos?, aviso? } sem paginação (count 0 e lista vazia quando não há pronunciamentos no período), cada item com codigo, data, casa, tipoUsoPalavra, resumo, indexacao, url e nomeParlamentar — sem o texto integral. ATENÇÃO: para tipo=discursos, omitir dataInicio/dataFim faz a fonte retornar SOMENTE os últimos 30 dias (frequentemente vazio) — para o histórico, informe o período explícito (ex.: desde o início do mandato; períodos de mais de 1 ano são lidos ano a ano por dentro, e um ano que a fonte não entregar aparece em periodosNaoLidos); apartes traz o histórico completo sem período e, com período, só os apartes dentro dele. Obtenha o codigoSenador via senado_listar_senadores e o texto completo em senado_discurso_texto (campo codigo). Para discursos de todos os senadores num período use senado_discursos_plenario, não esta.
Inputs: codigoSenador (required), casa, tipo, dataFim, +1 more. Returns: provenance, attribution
senado_discurso_textoTexto de um discursoARead-onlyIdempotentInspect
Obtém o texto integral de um único pronunciamento pelo codigoPronunciamento. Retorna { codigoPronunciamento, texto }, onde texto é a transcrição completa (string, podendo ter dezenas de KB — não é truncada nem paginada); codigo inexistente ou discurso sem texto retorna erro. Obtenha o codigoPronunciamento antes via senado_discursos_senador ou senado_discursos_plenario (campo codigo). Para apenas listar/filtrar discursos (resumo, data, autor) use aquelas ferramentas; esta traz o texto de um discurso já identificado.
Inputs: codigoPronunciamento (required). Returns: provenance, attribution
senado_distribuicao_materiasRanking de autoria/relatoria por comissãoARead-onlyIdempotentInspect
Ranqueia parlamentares pela quantidade de matérias numa comissão (siglaComissao), medindo carga de trabalho legislativo. tipo escolhe o eixo: autoria (matérias de autoria; padrão) ou relatoria (matérias relatadas). Retorna { siglaComissao, tipo, count, parlamentares } ordenado por quantidade desc, sem paginação (count 0 quando a comissão não tem registros), cada item com codigo, nome, partido, uf e quantidade. codigoParlamentar restringe a um parlamentar e só tem efeito em tipo=autoria (ignorado em relatoria). Descubra a sigla via senado_listar_comissoes; use o codigo do parlamentar em senado_obter_senador. Para a lista das matérias em si (não a contagem) use senado_buscar_materias.
Inputs: siglaComissao (required), tipo, codigoParlamentar. Returns: provenance, attribution
senado_ecidadania_consultas_analiseAnálise de consultas públicasARead-onlyIdempotentInspect
Analisa o conjunto completo de consultas públicas abertas (matérias em tramitação) do e-Cidadania por grau de concordância cidadã, conforme modo: consenso → consultas com alta concentração de votos numa direção, ordenadas da maior para a menor concentração; usa percentualMinimo (padrão 85%). polarizada → consultas com votação equilibrada (~50/50), ordenadas da menor para a maior diferença sim/não; usa margemPolarizacao (padrão 15 pontos). Analisa por padrão consultas aberta (opinião pública atual). Quando a matéria sai de tramitação a consulta passa a encerrada, então status: "encerrada"/"todas" cobrem o conjunto que foi encerrado desde a ingestão (cresce com o tempo); fechadas antes da 1ª carga não são capturadas. Todos os modos aceitam minimoVotos (padrão 1000) e limite (padrão 10). Retorna { modo, criterio, count, consultas }. É esta a ferramenta para 'consultas mais votadas', ranking ou panorama ATUAL da votação das consultas em tramitação — não confundir com senado_ecidadania_consultas_votos, que é o acervo HISTÓRICO (matérias já arquivadas) com quebra por UF. Para o detalhe de uma consulta use senado_ecidadania_obter_consulta.
Inputs: modo, limite, status, minimoVotos, +2 more. Returns: provenance, attribution
senado_ecidadania_consultas_votosVotos em consultas por UFARead-onlyIdempotentInspect
Acervo histórico de votos das consultas públicas do e-Cidadania, com quebra por UF (fonte: CSV Arquimedes; ~15 mil matérias, atualizado semanalmente). Use apenas quando o pedido for pelo acervo/arquivo histórico ou por votos por estado (UF); para 'consultas mais votadas', ranking ou opinião ATUAL das consultas em tramitação use senado_ecidadania_consultas_analise. Diferente de senado_ecidadania_listar_consultas (consultas em tramitação): aqui o conjunto é o arquivo de matérias já consultadas — status vem como Descontinuado no arquivo de origem, por isso é tratado como acervo, não como opinião atual. Retorna { count, referencePeriod, consultas }, cada item com id, materia, ementa, autoria, votosSim/votosNao/totalVotos, votosPorUf ({ UF: { sim, nao } }) e url. Use ordenarPor (total/sim/nao, padrão total) e ordem para ranking; uf para recortar e ranquear por aquele estado (só matérias com votos na UF, e cada item ganha recorteUf); materia para filtrar por código (numérico) ou trecho do nome/ementa; limite (padrão 20).
Inputs: uf, ordem, limite, materia, +1 more. Returns: provenance, attribution
senado_ecidadania_listar_consultasListar consultas públicasARead-onlyIdempotentInspect
Lista consultas públicas do e-Cidadania (conjunto completo das abertas — toda matéria em tramitação, ~7,7 mil), em que cidadãos votam sim/não. Retorna { count, consultas }, cada consulta com id, materia, ementa, votosSim/votosNao/totalVotos, percentualSim/percentualNao, status e url. Toda consulta entra como aberta; quando a matéria sai de tramitação ela passa a encerrada (o conjunto encerrada/todas cresce com o tempo). Consultas encerradas antes da 1ª ingestão não são capturadas. Aceita limite (padrão 20). Para o detalhe de uma consulta chame senado_ecidadania_obter_consulta com o id; para recortes analíticos (consenso/polarização) use senado_ecidadania_consultas_analise.
Inputs: limite, pagina, status. Returns: provenance, attribution
senado_ecidadania_listar_eventosListar eventos interativosARead-onlyIdempotentInspect
Lista eventos interativos do e-Cidadania (audiências públicas, sabatinas, lives) — conjunto completo (corpus persistido em D1, atualizado semanalmente; ~milhares de eventos, incluindo encerrados). Retorna { count, eventos }, cada evento com id, titulo, data, hora, comissao (sigla), comentarios, status (agendado/encerrado/cancelado) e url; aceita filtro por status, por comissao (sigla) e limite (padrão 20). Para um ranking dos mais comentados, ordene por comentários (ordenarPor: "comentarios", ordem: "desc"). Para o detalhe completo de um evento use senado_ecidadania_obter_evento.
Inputs: ordem, limite, status, comissao, +1 more. Returns: provenance, attribution
senado_ecidadania_listar_ideiasListar ideias legislativasARead-onlyIdempotentInspect
Lista ideias legislativas propostas por cidadãos no e-Cidadania — conjunto completo (corpus persistido em D1; ideias em andamento atualizadas diariamente; ~118 mil ideias, incluindo encerradas e convertidas em proposição). Retorna { count, ideias, avisoDatas }, cada ideia com id, titulo, apoios, status (a categoria da listagem do portal em que a ideia aparece: aberta = "Aberta", "Na comissão" ou "Aguardando envio à CDH"; encerrada = "Encerrada – sem apoio suficiente" ou "Não acatada" pela CDH; convertida = "Transformada em proposição"; removida = retirada do portal, que não a publica mais — o corpus guarda o último estado conhecido), url e os campos lidos do detalhe quando o backfill já passou por ela (dataPublicacao, autorUf, descricao, plConvertido; null até lá; autorUf traz a sigla da UF ou "Exterior", como o portal publica, e null quando o portal não publica a localidade; plConvertido, apesar do nome, é a Sugestão gerada na CDH, "SUG N/AAAA", não o projeto de lei). proposicoes (desde a 3.21.0, ausente até o backfill ler a ideia; [] = lida sem proposição) lista os projetos em que a ideia foi transformada, pela CDH ou adotada por parlamentar: tipo, número, ano, quem transformou, data e link. Datas: dataPublicacao é a DATA LIMITE para receber os 20.000 apoios — a única data que o corpus guarda; o nome do campo é histórico — e por isso cai no futuro em ideia aberta; dataCriacaoEstimada (= data limite − 120 dias, a regra dos 4 meses do portal) é calculada pelo servidor e é estimativa, não dado da fonte; a data REAL da proposição sai em senado_ecidadania_obter_ideia (dataProposta); avisoDatas repete isso na resposta. Aceita filtro por status e limite (padrão 20). Para um ranking das mais apoiadas, ordene por apoios (ordenarPor: "apoios", ordem: "desc"). Para o detalhe completo de uma ideia (texto, autor, linha do tempo, Sugestão, decisão da CDH, proposições em que virou) chame senado_ecidadania_obter_ideia com o id.
Inputs: ordem, limite, pagina, status, +1 more. Returns: provenance, attribution
senado_ecidadania_obter_consultaDetalhar consulta públicaARead-onlyIdempotentInspect
Obtém o detalhe de uma consulta pública específica do e-Cidadania. Retorna um objeto com id, materia, ementa, votosSim/votosNao/totalVotos, percentualSim/percentualNao, status, autor, relator, url. O portal não publica o período da consulta: dataAbertura/dataEncerramento (e comissao/linkMateria) vêm sempre null — a consulta abre quando a matéria entra em tramitação e encerra quando sai, refletido em status. O campo comentarios vem null: a página de consulta não possui recurso de comentários. O campo relator vem null: a página da consulta publica só autoria e ementa, não a relatoria — o relator da matéria sai de senado_obter_materia com o mesmo número (codigoMateria = id). Obtenha o id antes via senado_ecidadania_listar_consultas ou senado_ecidadania_consultas_analise.
Inputs: id (required). Returns: provenance, attribution
senado_ecidadania_obter_eventoDetalhar evento interativoARead-onlyIdempotentInspect
Obtém o detalhe completo de um evento interativo do e-Cidadania (audiência, sabatina, live). Retorna um objeto com id, titulo, descricao, data, hora, comissao e comissaoNomeCompleto, local, status (agendado/encerrado/cancelado), comentarios, url, mais pauta (até 15 itens), convidados e videoUrl (embed do YouTube quando houver, senão null) — campos não preenchidos vêm null e id inexistente retorna erro. Obtenha o id antes via senado_ecidadania_listar_eventos. Para apenas listar/rankear eventos (sem descrição/pauta/convidados) use senado_ecidadania_listar_eventos, não esta.
Inputs: id (required). Returns: provenance, attribution
senado_ecidadania_obter_ideiaDetalhar ideia legislativaARead-onlyIdempotentInspect
Obtém o detalhe de uma ideia legislativa do e-Cidadania, lido ao vivo da página da ideia. Retorna id, titulo, descricao, apoios, status, origemStatus, autor ("NOME (UF)", o nome abreviado como o portal publica), url, plConvertido (a Sugestão gerada, "SUG n/ano"), dataEncerramento (fim do período de apoio, quando encerrado) e os campos da linha do tempo do portal: dataProposta (data em que a ideia foi proposta, publicada pela fonte), prazoApoios (data limite para os 20.000 apoios), dataMeta/meta (quando alcançou a meta), sugestao (número, ano, data e link da Sugestão), decisaoCdh (a CDH transformou ou não a Sugestão), encerramento (apoios recebidos e fim do período), oficina (ideia de Oficina Legislativa), proposicoes (cada proposição em que a ideia virou — pela CDH ou adotada por senador/deputado —, com sigla, número, ano, parlamentar e link), linhaDoTempo (os acontecimentos como publicados, mais recente primeiro) e avisos (acontecimento que o servidor não reconheceu, copiado sem interpretação). Situação: status é a categoria do portal guardada no corpus (aberta/encerrada/convertida/removida, as mesmas de senado_ecidadania_listar_ideias); se a ideia ainda não está no corpus, o servidor a classifica pela linha do tempo e origemStatus diz isso. Datas: use dataProposta; dataPublicacao é a data limite (nome histórico, igual a prazoApoios) e dataCriacaoEstimada é estimativa mantida por compatibilidade. comentarios, problema e solucao vêm null: a página não os publica. Obtenha o id antes via senado_ecidadania_listar_ideias.
Inputs: id (required). Returns: provenance, attribution
senado_ecidadania_sugerir_tema_enqueteSugerir tema de enqueteARead-onlyIdempotentInspect
Sugere temas para uma enquete pública mensal (seleção de pauta): analisa o conjunto completo de consultas (abertas) e as ideias do e-Cidadania e elege as de maior engajamento cidadão, filtrando por polarização/consenso e participação mínima. Retorna { criteriosAplicados, totalAnalisados, count, totalQualificados, sugestoes } (até 10), cada sugestão com tipo (consulta/ideia), id, titulo, motivo, metricas (participação/polarização) e url, ordenadas por participação. count é o número de sugestões retornadas (≤10) e totalQualificados é quantas passaram nos critérios. Critérios opcionais em criterios: evitarPolarizacao/evitarConsenso (padrão true), minimoParticipacao (padrão 500), apenasEmTramitacao (padrão true → considera só consultas abertas, com base no status real). Para investigar uma sugestão, use senado_ecidadania_obter_consulta ou senado_ecidadania_obter_ideia conforme o tipo.
Inputs: criterios. Returns: provenance, attribution
senado_empresas_contratadasEmpresas contratadasARead-onlyIdempotentInspect
Busca empresas que contratam com o Senado por nome (mín. 3 caracteres) ou CNPJ/CPF (busca parcial). Retorna { count, total, empresas }, cada item com id, nome, cnpj, contratos (até 30 números) e totalContratos. Exige nome ou cnpj (a base completa é grande); limitado a limite (padrão 20, máx 100). Use o id/número de contrato em senado_contratos ou senado_contratacao_detalhe para o detalhamento.
Inputs: cnpj, nome, limite. Returns: provenance, attribution
senado_encontro_plenarioSessões do plenárioARead-onlyIdempotentInspect
Detalhes de um encontro legislativo (sessão de plenário). Retorna { codigo, secao, encontro }, onde encontro é o objeto bruto da API (ou array, quando o upstream traz vários) cujos campos variam conforme a secao escolhida: detalhes (padrão) traz dados gerais da sessão (tipo, data, situação, presença); pauta traz as matérias previstas; resultado traz os itens apreciados e seus resultados; resumo traz uma síntese. encontro pode vir vazio se a seção não tiver dados, e a chamada retorna erro se o codigo não existir. Obtenha o codigo via senado_agenda_plenario ou senado_resultado_plenario.
Inputs: codigo (required), secao. Returns: provenance, attribution
senado_estrutura_organizacionalEstrutura organizacionalARead-onlyIdempotentInspect
Estrutura organizacional (organograma) do Senado Federal até o nível de serviço. Dada uma unidade (sigla como 'DGER' ou nome como 'Diretoria-Geral'), retorna { unidade, caminho[], totalSubordinadas, subordinadas[] }: caminho são os órgãos superiores (da cúpula até o superior imediato) e subordinadas são TODAS as unidades da subárvore (secretarias, coordenações, serviços e núcleos), cada uma com sigla, nome e nivel (profundidade relativa). Use para responder 'o que está sob a DGER', 'quais secretarias/serviços pertencem a X' ou para entender a hierarquia administrativa. Para CONTAR ou LISTAR servidores sob uma unidade, use senado_servidores com subordinadasA. Fonte: portal institucional (a API de dados abertos não publica a árvore completa).
Inputs: unidade (required), limite. Returns: provenance, attribution
senado_execucao_orcamentariaExecução orçamentária do SenadoARead-onlyIdempotentInspect
Execução orçamentária do Senado: despesas (dotação, empenhado, liquidado, pago; desde 2013) ou receitas próprias (previstas e arrecadadas; desde 2012). Para maior/menor/média/mediana/distribuição/ranking ('quanto o Senado pagou/arrecadou com X', 'maior grupo de despesa') use estatisticas=true: SEM agruparPor = distribuição das linhas (min/máx/média/mediana/percentis) + top/bottom; COM agruparPor = grupos ranqueados por soma decrescente (grupos[0]=maior). A coluna de valor analisada é escolhida automaticamente conforme o tipo; o resultado já traz o rótulo legível dela em campoAnalisado. Retorna { tipo, modo, ano, totalLinhas, ... }: nos modos agregados, agregado[] com { chave, ...valores } ordenado por valor; em detalhe, despesas[]/receitas[] limitado por limite (padrão 100, com aviso ao truncar). Use tipo=despesas com modo por-ano/por-acao/por-grupo/por-fonte e tipo=receitas com por-origem; filtre por ano para reduzir o volume antes de pedir detalhe. O que cada número é: nas despesas, dotação/empenhado/liquidado/pago são ACUMULADOS no exercício até a data de posição do arquivo (o data_vintage da proveniência diz qual) — o exercício corrente é parcial e cresce; nas receitas, arrecadada é o valor do mês e prevista vem lançada inteira no mês 1. São os valores que o Senado publica na data de posição; lançamentos podem ser corrigidos depois. Única ferramenta de orçamento interno do Senado; não confundir com senado_orcamento_parlamentar (emendas/ofícios parlamentares ao orçamento da União).
Inputs: ano, modo, tipo, topN, +4 more. Returns: provenance, attribution
senado_horas_extrasHoras extras de servidoresARead-onlyIdempotentInspect
Horas extras pagas a servidores do Senado em ano/mes de referência (a partir de 2013). Para perguntas de maior/menor/média/mediana/distribuição/ranking ('quem recebeu mais horas extras', 'valor mediano de hora extra', 'distribuição dos pagamentos') use estatisticas=true: computa min/máx/média/mediana/desvio/percentis sobre TODAS as linhas filtradas (valorTotal) e devolve top/bottom (padrão 10) com identificadores. Sem agruparPor → distribuicao das linhas individuais + top/bottom; com agruparPor (nome/competencia) → grupos[] ranqueados por soma decrescente (grupos[0] = quem mais recebeu; por nome soma as linhas do mesmo servidor no mês), cada um com sua mini-distribuição. Sem estatisticas: retorna { ano, mes, count, total, valorTotal, horasExtras[] }, onde valorTotal soma o gasto do mês e cada item traz nome, valorTotal, horasExtras, competencia e pagamento. Filtro opcional por nome (busca parcial) e limite (padrão 100, máx 500; ignorado quando estatisticas=true). Para a remuneração completa do servidor use senado_remuneracoes_servidores.
Inputs: ano (required), mes (required), nome, topN, +3 more. Returns: provenance, attribution
senado_licitacoesLicitações do SenadoARead-onlyIdempotentInspect
Busca licitações do Senado por número exato (ex: 19/2018) ou texto do objeto. Retorna { count, total, licitacoes } com os registros brutos da API administrativa, limitados a limite (padrão 50, máx 500). Exige ao menos numero ou objeto (sem filtro retorna erro). Para o contrato resultante de uma licitação, use senado_contratos.
Inputs: limite, numero, objeto. Returns: provenance, attribution
senado_liderancasLideranças partidáriasARead-onlyIdempotentInspect
Lista as lideranças do Senado, da Câmara e do Congresso Nacional (líderes, vice-líderes etc.). Retorna { count, liderancas }, cada item com tipo, descricao, unidadeLideranca, casa, dataDesignacao, dataTermino, numeroOrdemViceLider, bloco (codigo/nome/sigla — preenchido quando a liderança é de bloco; o codigo serve em senado_obter_bloco), partido (codigo/sigla/nome — a unidade liderada, quando liderança de partido) e parlamentar (codigo, nome, partido de filiação, uf). A fonte NÃO publica a UF do parlamentar (vem sempre null) — obtenha-a via senado_obter_senador pelo codigo. Filtre por casa (SF/CN/CD), codigoParlamentar, vigente (S/N) ou siglaTipoLideranca; sem filtros retorna todas as casas. Para a composição de blocos use senado_listar_blocos.
Inputs: casa, vigente, codigoParlamentar, siglaTipoLideranca. Returns: provenance, attribution
senado_listar_blocosListar blocos parlamentaresARead-onlyIdempotentInspect
Lista todos os blocos parlamentares do Senado e seus partidos membros. Retorna { count, blocos }, onde cada bloco traz codigo, nome, nomeApelido, dataCriacao, dataExtincao e a lista partidos (cada um com sigla, nome, dataAdesao, dataDesligamento). A lista inclui a composição HISTÓRICA de cada bloco: partido com dataDesligamento preenchida já saiu (a composição atual são os com dataDesligamento null) e o mesmo partido pode repetir com períodos de adesão distintos — sem esse filtro um partido parece estar em 2 blocos ao mesmo tempo. Use para descobrir o codigo de um bloco e depois detalhá-lo via senado_obter_bloco; para lideranças use senado_liderancas.
Inputs: no named parameters. Returns: provenance, attribution
senado_listar_comissoesListar comissõesARead-onlyIdempotentInspect
Lista comissões (colegiados) ativas do Senado, com filtros por tipo (permanente, temporaria, cpi, mista) e ativa. Retorna { count, comissoes }, cada item com codigo, sigla, nome, tipo, casa e ativa. O endpoint só traz comissões ativas, logo ativa=false resulta em lista vazia. Use para descobrir a sigla exigida por senado_obter_comissao e senado_reunioes_comissao.
Inputs: tipo, ativa. Returns: provenance, attribution
senado_listar_senadoresListar senadoresARead-onlyIdempotentInspect
Use para pedidos como 'liste os senadores em exercício', 'senadores atuais', 'lista atual de senadores' ou filtros por UF/partido. Lista senadores em exercício, fora de exercício ou de uma legislatura específica, com filtros opcionais por nome, uf e partido. Retorna { count, senadores }, cada item com codigo, nome, nomeCompleto, partido, uf, foto e emExercicio, mais proveniência oficial da lista lida. emExercicio é a situação de HOJE: sem legislatura, true (padrão) lista os em exercício (titulares e suplentes que assumiram a vaga) e false lista os fora de exercício (titulares licenciados e suplentes fora da vaga — a mesma lista de senado_senadores_afastados); com legislatura, omitido traz a legislatura inteira e true/false filtra pela situação de hoje. nome faz correspondência parcial ignorando acentos/maiúsculas (use quando você só tem o nome e precisa do codigo); uf/partido filtram localmente. Use o codigo em senado_obter_senador ou senado_votacoes_senador.
Inputs: uf, nome, partido, emExercicio, +1 more. Returns: provenance, attribution
senado_mesaMesa DiretoraARead-onlyIdempotentInspect
Lista os membros da Mesa Diretora (presidente, vice-presidentes, secretários). O parâmetro casa (padrão senado) escolhe entre senado (Mesa do Senado Federal) e congresso (Mesa do Congresso Nacional). Retorna { casa, mesa, count, membros }, cada membro com cargo, codigo, nome, partido e uf. Para lideranças partidárias use senado_liderancas.
Inputs: casa. Returns: provenance, attribution
senado_notas_taquigraficasNotas taquigráficasARead-onlyIdempotentInspect
Transcrição oficial (notas taquigráficas) de uma sessão plenária ou reunião de comissão, em blocos sequenciais. Retorna { id, tipo, sessao, data, totalBlocos, aviso?, blocos }; id inexistente ou sem transcrição no acervo retorna totalBlocos 0 com aviso explicando. Cobertura: sessões plenárias do SF (deliberativas, não deliberativas, especiais) são transcritas em poucos dias; sessões CONJUNTAS do Congresso, canceladas/não realizadas e algumas solenes NÃO têm notas (a mídia pode existir em senado_videos_taquigrafia). modo governa o payload: resumo (padrão) traz por bloco sequencia, dataInicio/Fim, trecho (200 chars), caracteres e linkAudio, limitado a limite (padrão 20; pagine com sequenciaInicio, aviso sinaliza corte); texto traz o conteúdo integral de até 20 blocos por chamada (janela sequenciaInicio→sequenciaFim) e inclui intervalo. sequenciaFim só atua em modo=texto. Obtenha o id via senado_agenda_plenario/senado_resultado_plenario (sessão) ou senado_reuniao_comissao (reunião); orador filtra blocos pelo nome citado. Para a mídia (vídeo/áudio) use senado_videos_taquigrafia, não esta.
Inputs: id (required), modo, tipo, limite, +3 more. Returns: provenance, attribution
senado_obter_blocoDetalhar bloco parlamentarARead-onlyIdempotentInspect
Obtém detalhes de um bloco parlamentar específico pelo seu código. Retorna um objeto com codigo, nome, nomeApelido, dataCriacao, dataExtincao e partidos (array com sigla, nome, dataAdesao, dataDesligamento); dataExtincao é null para blocos vigentes. partidos é a composição HISTÓRICA: quem tem dataDesligamento preenchida já saiu do bloco (composição atual = dataDesligamento null). Obtenha o parâmetro codigo primeiro via senado_listar_blocos; código inexistente retorna erro ("Bloco parlamentar não encontrado").
Inputs: codigo (required). Returns: provenance, attribution
senado_obter_comissaoDetalhar comissãoARead-onlyIdempotentInspect
Obtém dados de uma comissão pela sigla, conforme secao (padrão resumo): resumo → { codigo, sigla, nome, tipo, finalidade, presidente, vicePresidente, totalMembros, titulares, suplentes } (presidente/vice com nome/codigo/bancada). finalidade só vem preenchida para colegiados temporários (CPIs, comissões temporárias e de medida provisória); para comissões permanentes (CCJ, CAE etc.) a fonte não a publica e o campo vem nulo com um aviso — as competências estão no Regimento Interno. membros → { sigla, secao, count, membros }, cada membro com codigo, nome, tipoVaga (titular/suplente), ativo e dataInicio. A sigla é resolvida internamente para código numérico; descubra-a via senado_listar_comissoes.
Inputs: sigla (required), secao. Returns: provenance, attribution
senado_obter_legislacaoDetalhar norma legalARead-onlyIdempotentInspect
Obtém o detalhe de uma norma federal já promulgada pelo seu codigo interno. Somente leitura, sem efeitos colaterais; consulta ao vivo à base oficial de dados abertos. Retorna um objeto com codigo, tipo, descricaoTipo, numero, ano, data (ISO AAAA-MM-DD), norma, apelido, ementa, indexacao (termos temáticos) e url do texto integral — campos ausentes na norma vêm null, e codigo inexistente retorna erro "Norma não encontrada", não um objeto vazio. Obtenha o codigo antes via senado_buscar_legislacao (é o identificador interno da norma, não o número da lei). Para localizar normas por tipo/número/ano use senado_buscar_legislacao; esta serve só para o detalhe de uma norma já identificada.
Inputs: codigo (required). Returns: provenance, attribution
senado_obter_materiaDetalhar matéria legislativaARead-onlyIdempotentInspect
Obtém dados de uma matéria pelo codigoMateria, conforme secao (padrão detalhe): detalhe → objeto com identificacao, apelido, ementa, autor, situacao, localAtual, dataApresentacao, indexacao, classificacoes[], tramitando, relator (nome/partido/uf/comissão), deliberacao e normaGerada. tramitacao → histórico de tramitação cronológico em tramitacoes[] (data, local, descricao), com count/total (mantém os mais recentes ao truncar). textos → documentos da matéria em textos[] (tipo, formato, identificacao, data, autoria, url), do mais recente ao mais antigo. limite aplica-se a tramitacao/textos (padrão 100 e 50; ao truncar inclui aviso). Obtenha o codigoMateria via senado_buscar_materias.
Inputs: codigoMateria (required), secao, limite. Returns: provenance, attribution
senado_obter_processoDetalhar processoARead-onlyIdempotentInspect
Obtém detalhes completos de um processo legislativo específico pelo seu id. Retorna um objeto com id, codigoMateria, identificacao, sigla, numero, ano, objetivo, ementa, tipoConteudo, dataApresentacao, autoria, indexacao, urlDocumento, tramitando (boolean) e o estado atual do processo: situacaoAtual (+siglaSituacaoAtual/dataSituacaoAtual), deliberacao (data, tipo, destino) e normaGerada (quando o processo virou norma). Obtenha o idProcesso antes via senado_search_processos ou senado_buscar_materias; para emendas, relatorias ou prazos use senado_processo_detalhe (parâmetro secao).
Inputs: idProcesso (required). Returns: provenance, attribution
senado_obter_senadorDetalhar senadorARead-onlyIdempotentInspect
Obtém o detalhe biográfico de um senador específico. Retorna um objeto com codigo, nome, nomeCompleto, nomeCivil, sexo, dataNascimento, naturalidade/ufNaturalidade, partido, uf, foto, email, emExercicio e a lista mandatos (legislatura, uf, participacao, dataInicio, dataFim). emExercicio é derivado dos exercícios do mandato (aberto = em exercício) e vem null — nunca afirmado — quando os mandatos não puderam ser lidos. Código inexistente retorna erro ("Senador com código N não encontrado"), nunca um registro vazio. Requer codigoSenador — obtenha-o via senado_listar_senadores (filtro nome). Para filiações, profissões, licenças, comissões ou cargos use senado_senador_historico (parâmetro tipo).
Inputs: codigoSenador (required). Returns: provenance, attribution
senado_obter_votacaoDetalhar votaçãoARead-onlyIdempotentInspect
Obtém detalhes de uma votação de plenário, incluindo votos nominais. codigoVotacao aceita OS DOIS códigos que a fonte publica para a mesma votação: o codigoVotacao de 4 dígitos (ex.: 7101 — o que senado_search_votacoes e senado_votacoes_senador devolvem nesse campo) ou o codigoSessao de 6 dígitos da sessão plenária (ex.: 581816). Com o código da votação retorna aquela votação; com o da sessão retorna { codigoSessao, count, votacoes } com todas as votações da sessão. Cada votação traz placar, resultado legível + resultadoCodigo bruto, secreta e votos[] (codigoSenador, nomeSenador, partido, uf, voto). Resolver o código de 4 dígitos exige varrer uma janela temporal: por padrão a janela recente da fonte (~12 meses); para votação mais antiga informe ano. Código que não existe em nenhum dos dois espaços retorna erro — nunca lista vazia. Atenção: códigos de senado_votacao_comissao e o codigoVotacao de senado_orientacao_bancada pertencem a OUTROS espaços de numeração e não são válidos aqui.
Inputs: codigoVotacao (required), ano. Returns: provenance, attribution
senado_orcamento_parlamentarOrçamento parlamentar (emendas)ARead-onlyIdempotentInspect
Emendas parlamentares ao orçamento da União, conforme tipo (padrão emendas). tipo: emendas (proposição) → { tipo, count, emendas }, cada item (lote de emendas de um autor) com autor, codigoAutor, quantidadeEmendas, anoExecucao, materia (peça orçamentária, p.ex. LOA 29/2023), tipoPl, dataOperacao e ativo. tipo: oficios (execução — indicação de destino de emendas já aprovadas) → { tipo, ano, count, total, aviso?, oficios }, cada ofício com id, autor, protocolo, dataInclusao e quantidadeEmendas; filtre pelo ano do orçamento da emenda (recomendado — a base cobre vários anos), pagine com limite/pagina, e use incluirEmendas: true para o detalhe de cada emenda (favorecido, CNPJ, órgão, nota de empenho). Nota: no modo oficios, o ofício é o documento de execução que indica o destino do recurso de uma emenda já aprovada (posterior à proposição); a data do ofício difere do ano do orçamento. Para a execução do orçamento interno do próprio Senado (despesas/receitas) use senado_execucao_orcamentaria.
Inputs: ano, tipo, limite, pagina, +1 more. Returns: provenance, attribution
senado_orientacao_bancadaOrientação de bancadaARead-onlyIdempotentInspect
Orientação de bancada nas votações de plenário: como cada liderança partidária orientou o voto, com placar — essencial para análise de disciplina partidária. Retorna { count, votacoes }, com cada votação trazendo codigoVotacaoSve, descricao, materia, dataInicio, dataTermino, sessao, totais (totalSim, totalNao, totalAbstencao, obstrucoes), quorumInicial/quorumFinal e orientacoes (partido, voto). Informe data (um dia) ou o período dataInicio/dataFim. O codigoVotacaoSve é o identificador interno do sistema de votação eletrônica e pertence a um espaço de numeração próprio: NÃO serve como entrada de senado_obter_votacao (use a data com senado_search_votacoes para chegar ao código da votação). Para o resultado das sessões use senado_resultado_plenario.
Inputs: data, dataFim, dataInicio. Returns: provenance, attribution
senado_pessoal_tabelasTabelas de gestão de pessoasARead-onlyIdempotentInspect
Tabelas de pessoal do Senado conforme o parâmetro tabela. Quantitativos agregados: pessoal (força de trabalho por classe/escolaridade), cargos-funcoes (cargos em comissão e funções de confiança), previsao-aposentadoria, senadores. Listas nominais: estagiarios (ativos), pensionistas, lotacoes (setores), cargos (nomes de cargos). Retorna { tabela, count, total, aviso?, registros[] } — registros agregados (nos quantitativos) ou nominais (nas listas), conforme a tabela, limitados por limite (padrão 100, máx 2000); count 0 e lista vazia quando a tabela não tem registros. O filtro textual opcional casa contra qualquer campo do registro. Para o cadastro nominal de servidores efetivos/comissionados use senado_servidores.
Inputs: tabela (required), filtro, limite. Returns: provenance, attribution
senado_processo_detalheDetalhes do processoARead-onlyIdempotentInspect
Detalha um aspecto de processos legislativos conforme o parâmetro secao: emendas → emendas apresentadas (id, identificacao, numero, tipo, autoria, data, colegiado, descricao, decisoes (objetos com casa/data/tipo/comissao/nomeComissao), url; aceita filtro codigoParlamentarAutor); relatorias → relatorias designadas (idProcesso, processo, relator, partido, uf, tipoRelator, comissao, dataDesignacao, dataDestituicao, motivoEncerramento; aceita codigoParlamentar/codigoColegiado/dataReferencia); prazos → prazos regimentais/constitucionais (registros brutos da API; aceita dataReferencia). Todos aceitam idProcesso e/ou codigoMateria e período dataInicio/dataFim (YYYYMMDD ou ISO) — informe pelo menos um filtro. Retorna { secao, count, total, aviso?, itens }, limitado a limite (padrão 100, máx. 500). Obtenha o idProcesso via senado_search_processos; tipos de prazo via senado_tabelas_processo. Ex.: { secao: 'emendas', codigoMateria: 137999 } ou { secao: 'relatorias', codigoParlamentar: 4994, dataReferencia: '2025-06-01' }.
Inputs: secao (required), limite, dataFim, dataInicio, +6 more. Returns: provenance, attribution
senado_remuneracoes_servidoresRemuneração de servidoresARead-onlyIdempotentInspect
Remunerações dos servidores do Senado em ano/mes de referência (a partir de 2013). Para perguntas de maior/menor/média/mediana/ranking ('quem ganhou mais em junho/2026', 'remuneração média') use estatisticas=true: computa min/máx/média/mediana/desvio/percentis sobre a folha INTEIRA e devolve top/bottom (padrão 10) identificados por nome (com idInternoFolha só para desambiguar homônimos, não para citar) — o modo resumo/detalhe só vê uma fatia e não acha o extremo real. Cada percentil vem com um rotulo legível e a coluna analisada tem rótulo legível em campoAnalisado. campo escolhe a verba analisada (padrão: remuneração bruta); consolidarPorServidor (padrão true) soma as linhas Normal+Suplementar da mesma pessoa antes das estatísticas; agruparPor='tipoFolha' devolve estatísticas por grupo (implica não-consolidado). Sem estatisticas: modo=resumo (padrão) retorna { ano, mes, totalRegistros, resumo[] } agregado por tipoFolha; modo=detalhe retorna { count, total, remuneracoes[] } com a composição individual, limitada por limite (padrão 50, máx 500). Filtros nome/tipoFolha aplicam antes de tudo. Para o cadastro de servidores use senado_servidores.
Inputs: ano (required), mes (required), modo, nome, +7 more. Returns: provenance, attribution
senado_requerimentos_cpiRequerimentos de CPIARead-onlyIdempotentInspect
Lista requerimentos de uma CPI (Comissão Parlamentar de Inquérito) em atividade, pela siglaCpi, com paginação por pagina (índice baseado em 0, definido pelo upstream). Retorna { siglaCpi, pagina, count, requerimentos }, onde requerimentos é a lista de registros brutos da página (campos conforme a API: tipicamente número, data, ementa, autor e situação do requerimento). count é o tamanho da página; uma página além do total retorna count 0 — use isso para saber que as páginas acabaram. Descubra as siglas via senado_listar_comissoes com tipo=cpi. Limitação conhecida: o endpoint upstream costuma responder vazio mesmo para CPIs em atividade, e não há fonte alternativa limpa na API; nesses casos o retorno traz count 0 e um campo aviso explicando — não interprete lista vazia como certeza de que a CPI não possui requerimentos.
Inputs: siglaCpi (required), pagina. Returns: provenance, attribution
senado_resultado_plenarioResultados do plenárioARead-onlyIdempotentInspect
Resultado das sessões plenárias numa data: itens de pauta apreciados, pareceres e resultados. Retorna { data, escopo, count, sessoes } (todas as sessões da data, sem paginação), com cada sessão trazendo codigoSessao, numeroSessao, data, hora, tipo, casa e itens (codigoMateria, identificacao, ementa, resultado, parecer — resultado/parecer podem vir null em itens ainda não deliberados). Sem sessão na data, count é 0 e sessoes vem vazio. escopo: sf (Senado), cn (Congresso) ou mes (resumo do mês). Para a pauta prévia use senado_agenda_plenario; orientação de bancada via senado_orientacao_bancada.
Inputs: data (required), escopo. Returns: provenance, attribution
senado_resultado_vetoResultado de vetoARead-onlyIdempotentInspect
Obtém o resultado da apreciação de um veto presidencial. Retorna { codigo, tipo, resultado }, onde resultado é o objeto bruto da API (sem wrappers), com campos variáveis — tipicamente identificação do veto, situação por dispositivo (ex.: "Rejeitado"/"Mantido") e link do PDF do resultado nominal (PdfsResultadoVotacao). A API não fornece placar numérico (sim/não) aqui — o detalhamento nominal está no PDF; vem objeto vazio quando o veto ainda não foi votado e retorna erro se o codigo não existir. tipo define o que codigo representa: veto (código do veto, padrão), materia (código do projeto vetado) ou dispositivo (dispositivo de veto parcial) — as três chaves apontam para o mesmo veto. Obtenha o código via senado_vetos. Para listar vetos (não o resultado de um) use senado_vetos.
Inputs: codigo (required), tipo. Returns: provenance, attribution
senado_reuniao_comissaoDetalhar reunião de comissãoARead-onlyIdempotentInspect
Detalha uma reunião de comissão. Aceita DOIS caminhos: o codigoReuniao direto, ou sigla da comissão mais data (YYYYMMDD) — neste segundo caso a ferramenta resolve o código sozinha, e devolve as candidatas quando o dia tem mais de uma reunião. Retorna um objeto com codigo, titulo, comissao, data, hora, local, situacao, realizada, secreta, tipoPresenca (presencial/semipresencial), presidente, links urlPauta/urlResultado/urlAta e partes (cada parte com evento e itens apreciados: identificacao, ementa, autoria, relatoria, resultado, codigoMateria). A API NÃO publica lista de presença da reunião (só presidente e eventuais convidados): reconstrua a presença pelos votos nominais (senado_votacao_comissao), por quem falou na transcrição (senado_notas_taquigraficas com tipo=reuniao) ou pela ata oficial (urlAta, quando publicada). Sem código à mão, prefira sigla + data; o codigoReuniao também sai de senado_agenda_comissoes ou senado_reunioes_comissao.
Inputs: data, sigla, codigoReuniao. Returns: provenance, attribution
senado_reunioes_comissaoReuniões de comissãoARead-onlyIdempotentInspect
Lista reuniões de uma comissão (pela sigla) num intervalo dataInicio/dataFim (YYYYMMDD) de até 30 dias; sem datas, usa os últimos 14 dias. A fonte só entrega 30 dias por pedido (e cortava o resto calada), então janelas maiores são recusadas: divida períodos longos em chamadas de até 30 dias. A agenda é lida um dia por vez; um dia que a fonte não entregar aparece em diasNaoLidos, com aviso. Retorna { sigla, periodo, count, reunioes, agendaPrevista?, diasNaoLidos?, aviso? }, cada reunião com codigo, descricao, data, hora, local, tipo e situacao. reunioes traz só as de até hoje; quando o período chega ao futuro, as marcadas para depois de hoje vêm à parte em agendaPrevista (count, reunioes, aviso) — são previsão e podem mudar. Descubra a sigla via senado_listar_comissoes; use o codigo retornado em senado_reuniao_comissao para os detalhes da pauta.
Inputs: sigla (required), dataFim, dataInicio. Returns: provenance, attribution
senado_search_processosPesquisar processosARead-onlyIdempotentInspect
Busca processos legislativos no endpoint v3 /processo (parâmetros complementares ao senado_buscar_materias). Retorna { count, total, aviso?, processos }, cada item com id, codigoMateria, identificacao, ementa, tipoDocumento, dataApresentacao, autoria (compactada: primeiros autores + total), totalAutores, tramitando (boolean) e normaGerada. É obrigatório ao menos um filtro (sigla, número, ano, autor ou período). Limitado a limite (padrão 20, máx. 200), com aviso ao truncar. Use o id retornado em senado_obter_processo para detalhes. Ex.: { sigla: 'PL', ano: 2025, dataInicioApresentacao: '2025-03-01' } (datas em YYYYMMDD ou ISO).
Inputs: ano, autor, sigla, limite, +5 more. Returns: provenance, attribution
senado_search_votacoesPesquisar votaçõesARead-onlyIdempotentInspect
Busca e lista votações do plenário combinando critérios opcionais. Janela temporal: informe dias (últimos N dias, 1-365) para atividade recente, OU dataInicio/dataFim (YYYYMMDD) para um período arbitrário — para um ano inteiro use dataInicio: "AAAA0101" e dataFim: "AAAA1231". Demais filtros: idProcesso, codigoMateria, sigla/numero/ano da matéria, codigoParlamentar e siglaVotoParlamentar. Retorna { count, votacoes } ordenadas da mais recente para a mais antiga; cada item traz codigoSessao, data, materia, codigoMateria, resultado e placar (totalSim/totalNao/totalAbstencao), sem votos nominais. Use senado_obter_votacao com o codigoSessao para os votos de cada senador.
Inputs: ano, dias, sigla, numero, +6 more. Returns: provenance, attribution
senado_senadores_adminSenadores (dados administrativos)ARead-onlyIdempotentInspect
Dados administrativos dos senadores conforme o parâmetro tipo: auxilio-moradia → { tipo, count, senadores } (nome, uf, partido, auxilioMoradia, imovelFuncional; legislatura atual). escritorios-apoio → { tipo, count, escritorios } (senador, uf, partido, setor, endereco, telefone). aposentados → { tipo, count, aposentados } ex-senadores aposentados pelos planos de previdência do Congresso (IPC e PSSC), com nome, tipo do plano, dataInicial, remuneracao. Filtros opcionais uf e nome (busca parcial) aplicam-se a auxilio-moradia e escritorios-apoio; nome também filtra aposentados. Cada tipo retorna count 0 e lista vazia quando não há registros. Para gastos de cota parlamentar use senado_ceaps. Ex.: { tipo: 'auxilio-moradia', uf: 'SP' } ou { tipo: 'aposentados' }.
Inputs: tipo (required), uf, nome. Returns: provenance, attribution
senado_senadores_afastadosSenadores afastadosARead-onlyIdempotentInspect
Lista os senadores atualmente afastados (fora de exercício). Retorna { count, senadores }, cada item com codigo, nome, nomeCompleto, partido, uf, foto e emExercicio (sempre false). Não requer parâmetros. Atenção: é a lista BRUTA do upstream, sem recorte de legislatura — pode conter registros históricos (ex.: senadores falecidos) e inconsistências pontuais com o detalhe do parlamentar; também não traz o vínculo titular↔suplente (para saber quem assumiu a vaga, consulte os mandatos em senado_obter_senador). Use codigo em senado_obter_senador para o detalhe; para os senadores em exercício (e busca por nome) use senado_listar_senadores.
Inputs: no named parameters. Returns: provenance, attribution
senado_senador_historicoHistórico do senadorARead-onlyIdempotentInspect
Histórico funcional de um senador conforme o parâmetro tipo. Valores: licencas (itens com dataInicio/dataFim/descricao), comissoes (sigla/nome/casa/participacao/datas), cargos (comissao/cargo/datas), historico-academico (cursos, registros brutos da API), filiacoes (partido/nomePartido/dataFiliacao/dataDesfiliacao) e profissoes (nome). Retorna { codigoSenador, tipo, count, itens }, com a forma de cada item dependente do tipo; tipos sem registros para o senador retornam count 0 e itens vazio. Requer codigoSenador (obtenha via senado_listar_senadores). Para dados biográficos e mandatos use senado_obter_senador. Ex.: { codigoSenador: 4994, tipo: 'filiacoes' } → histórico de partidos do senador.
Inputs: tipo (required), codigoSenador (required). Returns: provenance, attribution
senado_servidoresServidores do SenadoARead-onlyIdempotentInspect
Lista servidores do Senado por situacao (ativos, efetivos, comissionados ou inativos), com filtros opcionais por nome, lotacao e cargo. Retorna { situacao, count, total, servidores[] }, cada item com nome, vinculo, situacao, cargo, funcao, lotacao, anoAdmissao etc. Aplica limite (padrão 50, máx 500) e inclui aviso quando há truncamento — refine os filtros. Também conta e lista TODOS os servidores de TODA a estrutura subordinada a uma diretoria/secretaria (não só a lotação direta), cruzando a lotação de cada servidor com o organograma até o nível de serviço: informe a unidade (sigla ou nome, ex.: 'DGER') em subordinadasA — use isso para 'quantas pessoas estão sob a Diretoria-Geral', pois filtrar lotacao pela sigla-mãe retorna 0 (os servidores ficam em serviços/núcleos subordinados). Nesse modo o retorno traz a unidade resolvida, o total (um piso), os servidores, as unidades não reconhecidas no organograma (naoClassificados, com nota explicativa) e os afastados/em trânsito (afastadosOuEmTransito); ao responder, verbalize esses conceitos em português corrente — não cite nomes de parâmetros ou campos. Para o organograma em si use senado_estrutura_organizacional; para remuneração use senado_remuneracoes_servidores.
Inputs: nome, cargo, limite, lotacao, +2 more. Returns: provenance, attribution
senado_suprimento_fundosSuprimento de fundosARead-onlyIdempotentInspect
Suprimento de fundos do Senado (adiantamentos a supridos): relação anual de supridos, atos de concessão, empenhos, movimentações ou transações de cartão corporativo, conforme tipo. Retorna { ano, tipo, count, total, registros } (snake_case da API administrativa), filtrável por filtro textual e limitado por limite (padrão 100, máx 500); ao truncar, inclui aviso. Para maior/menor/média/mediana/distribuição/ranking ('quem mais recebeu', 'fornecedor com maior gasto', 'valor mediano') use estatisticas=true (só nos tipos transacoes, empenhos, atos-concessao — os demais não têm coluna de valor): SEM agruparPor = distribuição das linhas (min/máx/média/mediana/percentis) + top/bottom; COM agruparPor = grupos ranqueados por soma decrescente (grupos[0]=maior). A coluna de valor analisada é escolhida automaticamente conforme o tipo; o resultado já traz o rótulo legível dela em campoAnalisado. Registros sem valor são excluídos das estatísticas. Em atos de concessão, cada beneficiário é identificado pelo NOME (cruzado com o cadastro de supridos) e pode-se usar agruparPor='suprido' para ranquear por beneficiário. Informe o ano (a fonte publica de 2013 em diante); use os mesmos códigos administrativos vistos em senado_contratacoes_lista ou senado_execucao_orcamentaria para cruzar gastos.
Inputs: ano (required), tipo, topN, campo, +4 more. Returns: provenance, attribution
senado_tabelas_plenarioTabelas de referência do plenárioARead-onlyIdempotentInspect
Consulta tabelas de referência do plenário para resolver códigos/domínios, conforme tabela: tipos-sessao (espécies de sessão plenária), tipos-comparecimento (situações de presença) ou legislaturas (períodos legislativos com datas). Retorna { tabela, count, total, linhas } — count é o nº após o corte por limite e total o disponível; count < total indica truncagem (aumente limite); count 0 quando o filtro não casa. Cada linha traz o código/sigla e a descrição do domínio (campos conforme a API). Use para interpretar campos como tipo de senado_agenda_plenario/senado_resultado_plenario. Para tabelas do processo legislativo (assuntos, classes, situações) use senado_tabelas_processo. Ex.: { tabela: 'legislaturas' } ou { tabela: 'tipos-sessao', filtro: 'deliberativa' }.
Inputs: tabela (required), filtro, limite. Returns: provenance, attribution
senado_tabelas_processoTabelas de referência de processosARead-onlyIdempotentInspect
Consulta tabelas de referência do processo legislativo para resolver códigos/siglas, conforme tabela. Domínios de entidade: siglas (siglas de proposição), assuntos, classes, destinos, entes. Domínios de tipo (código→descrição): tipos-situacao, tipos-decisao, tipos-autor, tipos-atualizacao, tipos-documento, tipos-conteudo-documento, tipos-prazo. Retorna { tabela, count, total, linhas } — count é o nº após o corte por limite e total o disponível; count < total indica truncagem (aumente limite); count 0 quando o filtro não casa. Cada linha traz código/sigla e descrição (campos conforme a API). Use antes de filtrar em senado_search_processos/senado_processo_detalhe. Para as tabelas do plenário (tipos de sessão, legislaturas) use senado_tabelas_plenario. Ex.: { tabela: 'tipos-prazo' } ou { tabela: 'siglas', filtro: 'PEC' }.
Inputs: tabela (required), filtro, limite. Returns: provenance, attribution
senado_tabelas_referenciaTabelas de referênciaARead-onlyIdempotentInspect
Consulta tabelas de referência do Senado pelo parâmetro tabela. Valores: tipos-materia → { count, tipos } (sigla/nome/descricao dos tipos de proposição, p.ex. PEC, PL, MPV) — catálogo curado mantido neste servidor (12 tipos mais comuns, não é a lista viva do upstream processo/siglas, que tem ~184 siglas); use para achar a sigla correta antes de senado_buscar_materias/senado_search_processos; partidos → { count, totalSenadores, partidos } (partidos com bancada atual, ordenados por nº de senadores); ufs → { count, totalSenadores, ufs } (as 27 UFs com a contagem de senadores em exercício); legislatura-atual → { numero, periodo, dataInicio, dataFim } da legislatura vigente; tipos-norma → { count, tipos } (sigla/descricao dos tipos de norma para senado_buscar_legislacao); tipos-uso-palavra → { count, tipos } (codigo/descricao para interpretar tipoUsoPalavra em senado_discursos_senador). Toda resposta inclui o campo tabela. Para a relação nominal de parlamentares use senado_listar_senadores.
Inputs: tabela (required). Returns: provenance, attribution
senado_terceirizadosTerceirizadosARead-onlyIdempotentInspect
Lista colaboradores terceirizados do Senado, filtráveis (busca parcial, sem acento) por nome, empresa contratada ou lotação. Retorna { count, total, terceirizados }, cada item com nome, cpf, situacao, empresa, lotacao e numeroContrato. A lista completa é baixada e filtrada no Worker; resultados limitados a limite (padrão 50, máx 500), com aviso ao truncar. Para a empresa contratante e seus contratos, use senado_empresas_contratadas.
Inputs: nome, limite, empresa, lotacao. Returns: provenance, attribution
senado_vetosVetos presidenciaisARead-onlyIdempotentInspect
Lista vetos presidenciais em apreciação pelo Congresso Nacional, por ano ou por status de tramitação. Retorna { count, total, aviso?, vetos }, com cada veto trazendo codigo, identificacao, ementa, emTramitacao, materiaVetada, tipo (total/parcial), assunto e dataLimiteVotacao (prazo de sobrestamento de pauta). limite controla o corte (padrão 100; aviso indica truncagem). Informe ano OU status (tramitando/antes-rcn/encerrados). Para o resultado da votação de um veto use senado_resultado_veto.
Inputs: ano, limite, status. Returns: provenance, attribution
senado_videos_taquigrafiaVídeos da taquigrafiaARead-onlyIdempotentInspect
Lista os vídeos e áudios (unidades descritivas) de uma sessão plenária ou reunião de comissão. Retorna { id, tipo, count, total, aviso?, videos } (sessão sem mídia no acervo → count/total 0 com aviso; ao passar de limite inclui aviso). A cobertura de mídia é mais ampla que a das notas: sessões conjuntas do Congresso costumam ter vídeos mesmo sem transcrição, cada item com codigo, data, descricao, orador, duracaoSegundos e os links urlVideo, urlAudio, urlThumbnail. Obtenha o id via senado_agenda_plenario/senado_resultado_plenario (sessão) ou senado_reuniao_comissao (reunião). Para a transcrição textual correspondente use senado_notas_taquigraficas, não esta.
Inputs: id (required), tipo, limite, orador. Returns: provenance, attribution
senado_votacao_comissaoVotações em comissãoARead-onlyIdempotentInspect
Lista votações em comissões. O parâmetro por (padrão comissao) define o eixo da consulta: por: comissao → exige siglaComissao; lista as votações daquela comissão. por: senador → exige codigoSenador; lista os votos do senador em comissões (filtro opcional comissao). por: materia → exige sigla, numero e ano (ex.: PL 2630/2020); lista as votações da proposição em comissões (filtro opcional comissao). Em todos os casos aceita período opcional dataInicio/dataFim (YYYYMMDD, filtrado pela data da reunião) e retorna { por, ...contexto, count, votacoes }, cada votação com codigo, data, comissao, reuniao, materia, descricao, totais publicados pela fonte (totalSim/totalNao/totalAbstencao; contados dos votos, com placarComputado: true, só quando a fonte não os traz) e votos (senador, partido, voto). Sem paginação. Períodos amplos podem estourar o tempo-limite da consulta (erro de timeout): prefira janelas de até 3 meses e divida períodos maiores em chamadas sucessivas. Obtenha siglas via senado_listar_comissoes, codigoSenador via senado_listar_senadores; para votações no plenário use senado_votos_materia. Atenção: o codigo de cada votação de comissão pertence a um espaço de numeração próprio e NÃO é válido em senado_obter_votacao (que é exclusivo de plenário) — podem coincidir numericamente, mas apontam para votações diferentes.
Inputs: ano, por, sigla, numero, +5 more. Returns: provenance, attribution
senado_votacoes_senadorVotações de um senadorARead-onlyIdempotentInspect
Lista as votações nominais de um senador, mostrando como votou em cada matéria. Retorna { periodo, count, votos }, cada voto com codigoSessao, codigoVotacao, data, materia, descricao, voto e resultado, ordenados da mais recente para a mais antiga. Sem período usa o ano corrente; informe ano ou o par dataInicio/dataFim (YYYYMMDD). Requer codigoSenador (obtenha via senado_listar_senadores); para detalhes de uma votação específica (votos de todos os senadores) use senado_obter_votacao — os dois códigos são aceitos, e codigoSessao resolve direto.
Inputs: codigoSenador (required), ano, dataFim, dataInicio. Returns: provenance, attribution
senado_votos_materiaVotos de uma matériaARead-onlyIdempotentInspect
Obtém as votações de uma matéria pelo codigoMateria. Retorna { codigoMateria, count, votacoes }, cada item com data, descricao, resultado e placar (totalSim/totalNao/totalAbstencao); com incluirVotos: true (padrão false) acrescenta votos[] (nome, partido, uf e voto de cada senador). Obtenha o codigoMateria via senado_buscar_materias ou senado_obter_materia.
Inputs: codigoMateria (required), incluirVotos. Returns: provenance, attribution
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 69 tools
The descriptions are unusually explicit and cross-reference alternatives, which helps a lot, but several tool families overlap meaningfully: buscar_materias vs search_processos, obter_materia vs obter_processo, and the multiple voting tools (votos_materia, search_votacoes, obter_votacao, votacoes_senador, votacao_comissao) require careful reading to choose correctly. There is also redundancy such as senadores_afastados overlapping with listar_senadores(emExercicio=false). Boundaries are mostly documented, but the overlap is broader than just one or two pairs.
Nearly all tools use a readable snake_case pattern with the senado_ prefix, often followed by a domain and an action (senado_obter_materia, senado_listar_senadores, senado_ecidadania_listar_eventos). Deviations exist: some names are noun-only (senado_mesa, senado_vetos, senado_licitacoes), two use English 'search', and the generic search/fetch tools lack the prefix, but the overall pattern remains predictable.
With 69 tools, the surface is far beyond what an agent can reliably scan and select from in normal use. Even though the domain is broad and many tools cover distinct subdomains, this is the extreme end of tool-count mismatch and will impose a heavy selection burden.
Coverage is very broad across legislative matters, processes, voting, committees, plenary, e-Cidadania, legislation, budget, personnel, contracts, and administrative data. Minor gaps remain, such as individual detail endpoints for some administrative entities (e.g. servidores, terceirizados, empresas), but the overall read-only lifecycle is well covered.
Maintenance
Related MCP Connectors
Brazilian election and legislative data (MCP Político, MCP Legislativo) for Claude and ChatGPT.
Banco Central do Brasil (Brazil's central bank) MCP. Keyless public APIs: SGS time series + Olinda…
# MCP DadosBR Servidor MCP focado em dados públicos do Brasil. Oferece duas ferramentas simples e…
GovTrack MCP — federal US Congress data (free, no auth)
Related MCP Servers
- AlicenseBqualityNot gradedmaintenanceEnables interaction with the Brazilian Chamber of Deputies Open Data API, providing access to information about legislators, legislative proposals, voting records, events, committees, and parliamentary activities through 57 typed and validated tools.63-
- AlicenseAqualityDmaintenanceAn MCP server that provides access to the Brazilian Chamber of Deputies open data API. It enables users to search for deputies, track their expenses, and query legislative information such as bills and API endpoints.61MIT
- AlicenseBqualityFmaintenanceMCP server for Brazilian Federal Senate open data (legislators, bills, votes, committees)33MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to query Brazilian Senate data including senators, bills, voting records, committees, and plenary sessions through natural language.26 npm7MIT