senado-br-mcp (Cloudflare Workers)

A public, hosted MCP server for Brazilian Senate open data, running on Cloudflare Workers (Streamable HTTP). It is already deployed and open access — just point your MCP client at the hosted endpoint; no installation, no account, no API key required.

Provides 65 tools (plus 4 prompts and 5 resources) organized into 19 groups covering the legislative domain (senators, bills, votes, committees, plenary sessions and results, presidential vetoes, party-bloc voting orientation, legislative processes, reference data, citizen participation via e-Cidadania, speeches and stenographic transcripts, blocs and leadership, federal legislation, committee voting) and the administrative domain (CEAPS parliamentary quota expenses, housing allowance, civil servants and payroll, overtime, interns, procurement contracts, biddings, outsourced staff, petty-cash funds, budget execution and own revenues). Connects to three sources: the legislative open data API, the administrative open data API and the e-Cidadania portal.

v2.1.0: all tools that consumed endpoints marked deprecated upstream (the legacy /materia/* family and /senador/{codigo}/votacoes) were migrated to the v3 /processo and /votacao APIs, keeping tool names and output keys stable.

v2.2.0: adds the administrative domain (groups O, P, Q, R — 16 tools) consuming adm.senado.gov.br. Large datasets (CEAPS ≈ 10 MB/year, payroll ≈ 5.5 MB/month) are fetched once, cached, and filtered/aggregated inside the Worker — tools never return raw dumps.

v2.3.0: every tool now declares MCP annotations (readOnlyHint, openWorldHint) and a structured-output schema; canonical endpoint moved to the custom domain https://senado.sidneybissoli.com/mcp (the *.workers.dev URL still works as a fallback).

v3.0.0: consolidated 90 → 65 tools by merging near-duplicate tools into enum/secao/tipo parameters (e.g. reference tables → senado_tabelas_referencia; per-process sub-resources → senado_processo_detalhe; senado_mesa with a casa param; senado_search_votacoes absorbing the recent-votes/list tools). Breaking change: several tool names were removed or renamed.

v3.1.0: adds the MCP prompts capability (4 reusable pt-BR workflow templates — CEAPS expenses, bill tracking, senator votes, e-Cidadania overview) and the resources capability (5 static context docs: usage guide, tool catalog, glossary, and the tipos-matéria / UFs reference tables). Ships a LICENSE file (MIT).

Use it (hosted — no setup)

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

https://senado.sidneybissoli.com/mcp

Install (any client)

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

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

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

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

Architecture

• Runtime: Cloudflare Workers (ESM)
• Transport: Streamable HTTP (MCP spec 2025-03-26) via createMcpHandler from agents/mcp
• Protocol: MCP over JSON-RPC — single /mcp endpoint handles POST, GET, DELETE
• SDK: @modelcontextprotocol/sdk 1.26.0+ (per-request McpServer instances)
• Validation: Zod schemas for all tool inputs
• Caching: 2-layer (L0 memory + L1 Cache API) with SHA-256 keying
• Rate limiting: Token bucket — global (8 req/s) + per-client (2 req/s)
• Upstream throttle: Max 6 concurrent requests, 10s timeout, retry with exponential backoff
• Auth: Optional Bearer token (set the API_KEY secret; open access when unset). Constant-time comparison.
• Observability: Structured JSON logging + in-memory counters exposed at /metrics
• Tests: Vitest unit tests for parsers, helpers, cache, throttle, and auth

Self-hosting (optional)

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

Prerequisites

• Node.js 18+
• Wrangler CLI v4+
• Cloudflare account

Setup

1. Install dependencies

npm install

2. Create KV namespace

# Create the KV namespace
wrangler kv namespace create CACHE_KV

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

3. Configure wrangler.toml

Replace the placeholder KV namespace ID:

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

Optionally set ALLOWED_ORIGIN to restrict CORS:

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

4. (Optional) Enable authentication

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

5. Local development

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

6. Tests and typecheck

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

7. Deploy

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

Endpoints

Path	Methods	Description
/mcp	POST, GET, DELETE, OPTIONS	MCP Streamable HTTP endpoint (managed by createMcpHandler)
/health	GET	Health check — returns ok (always public)
/metrics	GET	JSON counters: requests, tool calls, cache hits/misses, upstream calls/retries/errors, auth failures (always public)

MCP Request Examples

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

List available tools

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

Call a tool — List senators from SP

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

Call a tool — Search bills by keyword

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

Call a tool — Get recent plenary votes

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

Call a tool — Most popular citizen ideas

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

Upstream API Endpoints

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

Legacy endpoints (.json suffix, PascalCase responses)

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

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

v3 endpoints (flat JSON arrays/objects, camelCase)

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

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

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

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

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

e-Cidadania (HTML scraping + internal REST)

List tools use internal REST APIs (restcolecaomaismateria, restcolecaomaisideia, restcolecaomaisaudiencia) that return clean JSON. Detail tools scrape HTML with CSS-class-targeted regex.

Caching

Layer architecture

Layer	Storage	Scope	TTL range	Purpose
L0	In-memory Map	Per-isolate	30-300s	Ultra-fast, eliminates redundant requests within a Worker isolate
L1	Cloudflare Cache API (caches.default)	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:

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

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

Tool Inventory

Group H — Reference/Metadata (1 tool)

Tool	Description
senado_tabelas_referencia	Tabelas de referência via tabela enum: tipos-materia, partidos, ufs, legislatura-atual, tipos-norma, tipos-uso-palavra

Group A — Senators (5 tools)

Tool	Description
senado_listar_senadores	Lista senadores em exercício/por legislatura, com filtros nome (busca parcial sem acento), uf e partido
senado_obter_senador	Detalhe biográfico de um senador: bio, mandatos, partido, contato
senado_votacoes_senador	Como um senador votou em cada matéria (via v3 /votacao)
senado_senador_historico	Histórico funcional via tipo enum: licencas, comissoes, cargos, historico-academico, filiacoes, profissoes
senado_senadores_afastados	Senadores atualmente afastados (fora de exercício)

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

Tool	Description
senado_buscar_materias	Busca matérias por tipo, número, ano, palavra-chave, autor ou tramitação (via v3 /processo)
senado_obter_materia	Dados de uma matéria via secao enum: detalhe (situação/relator), tramitacao (histórico) ou textos (documentos)

Group C — Processes (5 tools)

Tool	Description
senado_search_processos	Busca processos legislativos (complementar à busca de matérias)
senado_obter_processo	Detalhes completos de um processo legislativo específico
senado_processo_detalhe	Aspecto de um processo via secao enum: emendas, relatorias ou prazos
senado_autores_atuais	Parlamentares autores de processos em tramitação, ordenados por produção
senado_tabelas_processo	12 tabelas de referência (siglas, assuntos, classes, tipos-*) via tabela enum

Group D — Votes (3 tools)

Tool	Description
senado_obter_votacao	Detalhes de uma votação com votos nominais. Aceita codigoVotacao (codigoSessao da sessão plenária).
senado_votos_materia	Votações de uma matéria (via v3 /votacao?codigoMateria), com votos nominais opcionais
senado_search_votacoes	Busca/listagem flexível de votações do plenário por dias, período, processo, matéria ou senador

Group E — Committees (7 tools)

Tool	Description
senado_listar_comissoes	Lista comissões (colegiados) ativas, filtráveis por tipo
senado_obter_comissao	Dados de uma comissão via secao enum: resumo (mesa/totais) ou membros (composição). Resolve sigla para código internamente.
senado_reunioes_comissao	Reuniões de uma comissão num período (lida com intervalos entre anos)
senado_agenda_comissoes	Agenda de reuniões de todas as comissões numa data
senado_reuniao_comissao	Detalhe completo de uma reunião: partes, itens, convidados, resultados, links pauta/ata
senado_requerimentos_cpi	Requerimentos protocolados numa CPI em atividade, paginados
senado_distribuicao_materias	Estatísticas de carga por senador numa comissão: autoria ou relatoria

Group F — Plenary (7 tools)

Tool	Description
senado_agenda_plenario	Plenary schedule — by day, month or Congress (escopo dia/mes/cn)
senado_resultado_plenario	Session results: items deliberated, opinions, outcomes (SF/CN/month)
senado_orientacao_bancada	Party leadership voting instructions per vote, with tallies
senado_vetos	Presidential vetoes by year or tramitation status
senado_resultado_veto	Nominal veto vote results (by veto, vetoed bill or device)
senado_encontro_plenario	Legislative session detail, agenda items, results or summary
senado_tabelas_plenario	Session types, attendance types, legislatures list

Group G — e-Cidadania (8 tools)

Tool	Description
senado_ecidadania_listar_consultas	Consultas públicas com votação sim/não dos cidadãos
senado_ecidadania_obter_consulta	Detalhe de uma consulta: votos, autor, relator, comentários
senado_ecidadania_consultas_analise	Analisa consultas via modo enum: consenso (alta concordância) ou polarizada (~50/50)
senado_ecidadania_listar_ideias	Ideias legislativas de cidadãos; ranking das mais apoiadas via ordenarPor: apoios
senado_ecidadania_obter_ideia	Detalhe de uma ideia: texto, apoios, status de conversão em projeto
senado_ecidadania_listar_eventos	Eventos interativos (audiências, sabatinas, lives); ranking dos mais comentados via ordenarPor
senado_ecidadania_obter_evento	Detalhe de um evento: pauta, convidados, link de vídeo
senado_ecidadania_sugerir_tema_enquete	Sugere temas para enquete mensal a partir de critérios configuráveis

Group I — Speeches (3 tools)

Tool	Description
senado_discursos_senador	Pronunciamentos de um senador via tipo enum: discursos (próprios) ou apartes (intervenções)
senado_discursos_plenario	Todos os discursos em plenário num intervalo de datas
senado_discurso_texto	Texto integral de um pronunciamento/discurso específico

Group J — Blocs & Leadership (4 tools)

Tool	Description
senado_listar_blocos	Blocos parlamentares do Senado e seus partidos membros
senado_obter_bloco	Detalhes de um bloco parlamentar específico
senado_liderancas	Lideranças do Senado/Congresso (líderes, vice-líderes), filtráveis
senado_mesa	Membros da Mesa Diretora via casa enum: senado (Mesa do SF) ou congresso (Mesa do CN)

Group K — Budget (1 tool)

Tool	Description
senado_orcamento_parlamentar	Dados de emendas orçamentárias via tipo enum: emendas (lotes) ou oficios (ofícios de apoio)

Group L — Federal Law (2 tools)

Tool	Description
senado_buscar_legislacao	Busca normas jurídicas federais por tipo, número, ano ou data (ao menos um obrigatório)
senado_obter_legislacao	Detalhes de uma norma jurídica federal específica

Group M — Committee Voting (1 tool)

Tool	Description
senado_votacao_comissao	Votações em comissões via por enum: comissao, senador ou materia; período opcional

Group N — Taquigrafia (2 tools)

Tool	Description
senado_notas_taquigraficas	Official transcripts of plenary sessions or committee meetings — summary mode with excerpts, full-text mode paginated in blocks, speaker filter
senado_videos_taquigrafia	Video/audio units per session or meeting, with speaker and media links

Group O — Senadores/Administrativo (2 tools)

Tool	Description
senado_ceaps	CEAPS parliamentary quota expenses by year — aggregated by senator, expense type, month or supplier, or itemized detail; filters by senator/month/type/supplier
senado_senadores_admin	Dados administrativos dos senadores via tipo enum: auxilio-moradia, escritorios-apoio ou aposentados

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

Tool	Description
senado_servidores	Civil servants by status (active/effective/commissioned/inactive), filterable by name, unit, position
senado_remuneracoes_servidores	Monthly payroll — summary by payroll type or per-person composition with computed gross
senado_horas_extras	Overtime payments by month with totals
senado_pessoal_tabelas	Tabelas de pessoal via tabela enum: quantitativos (pessoal, cargos-funcoes, previsao-aposentadoria, senadores) e listas (estagiarios, pensionistas, lotacoes, cargos)

Group Q — Contratações (6 tools)

Tool	Description
senado_contratos	Contracts with server-side filters: supplier, CNPJ, year, number, object, labor
senado_contratacao_detalhe	Items, payments, guarantees, amendments or activations of a contract/ata/empenho
senado_licitacoes	Biddings by number or object text
senado_terceirizados	Outsourced collaborators by name, company or unit
senado_empresas_contratadas	Companies contracting with the Senate (requires name/CNPJ filter)
senado_contratacoes_lista	Price-registration atas, commitment notes, young apprentices

Group R — Suprimento de Fundos (1 tool)

Tool	Description
senado_suprimento_fundos	Petty-cash advances by year: recipients, concession acts, commitments, movements, card transactions

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

Tool	Description
senado_execucao_orcamentaria	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

Total: 65 tools

Prompts (4)

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

Prompt	Args	What it guides
senado_gastos_senador	senador, ano	Resolve o senador e agrega/detalha despesas CEAPS.
senado_tramitacao_materia	sigla, numero, ano	Obtém situação atual + histórico de tramitação da matéria.
senado_votos_senador	senador, periodo?	Lista os votos nominais do senador no período.
senado_panorama_ecidadania	—	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
senado://guia	markdown	Visão geral e qual ferramenta usar por objetivo.
senado://catalogo	markdown	As 65 ferramentas agrupadas por domínio.
senado://glossario	markdown	Siglas e termos do Senado (PEC, CEAPS, CCJ, RCN…).
senado://tabelas/tipos-materia	json	Tipos de proposição (sigla/nome/descrição).
senado://tabelas/ufs	json	As 27 unidades federativas.

Project Structure

src/
├── index.ts              # Worker entrypoint (fetch 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
├── 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
    ├── 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
tests/                    # Vitest unit tests mirroring src/ (parsers, cache, throttle, auth, utils)

Environment Variables

Variable	Required	Default	Description
SENADO_BASE_URL	No	https://legis.senado.leg.br/dadosabertos	Legislative API base URL
SENADO_ADM_BASE_URL	No	https://adm.senado.gov.br/adm-dadosabertos	Administrative API base URL
ALLOWED_ORIGIN	No	*	CORS allowed origin
API_KEY	No (secret)	—	When set, requires Authorization: Bearer <key> on all requests except /health, /metrics, and CORS preflight
CACHE_KV	Yes (binding)	—	KV namespace for L2 cache

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 65 tools, it exposes prompts (ready-made pt-BR workflows: senado_gastos_senador, senado_tramitacao_materia, senado_votos_senador, senado_panorama_ecidadania) and resources (senado://guia, senado://catalogo, senado://glossario, senado://tabelas/tipos-materia, senado://tabelas/ufs).

One-click (LobeHub)

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

Claude Desktop / Claude Code

Add to your MCP configuration:

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

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

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

MCP Inspector

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

License

MIT

Credits

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