Argos MCP Server

Model Context Protocol server that gives Claude direct, structured access to Argos / Horos Bank — AI-native fiscal risk data for all 5,570 Brazilian municipalities and 27 states.

Once connected, Claude can answer questions like "what is the fiscal profile of Salvador?" or "simulate a R$50M credit operation for IBGE 2927409" without leaving the conversation. The server is a thin, read-only client over argos-brown.vercel.app/api/hb/.

Quickstart

Requirements: Node.js 18+ and an ARGOS_API_KEY (the Horos Bank x-api-key).

Add Argos to your Claude Desktop config — %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "argos": {
      "command": "npx",
      "args": ["-y", "argos-mcp-server@latest"],
      "env": {
        "ARGOS_API_BASE": "https://argos-brown.vercel.app",
        "ARGOS_API_KEY": "your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop — the 15 tools appear under the tools icon. For Claude Code / Cowork, use an .mcp.json at the project root with the same mcpServers block.

From source

cd mcp
npm install
npm run build      # emits dist/index.js
npm start          # runs dist/index.js

To run from source inside a client config, point command at the built file: "command": "node", "args": ["/absolute/path/to/argos/mcp/dist/index.js"].

Getting an API key

Every tool authenticates with a Horos Bank x-api-key, supplied through the ARGOS_API_KEY environment variable. Request a key — and check current plans and coverage — at argos-brown.vercel.app. Without a valid key the Horos Bank routes return 401/403 and every tool fails.

Tools

15 tools, all read-only over the Argos API. Municipalities are addressed by their 7-digit IBGE code; states by their 2-letter UF.

| Tool | What it does | |---|---| | buscar_municipio | Search municipalities by name (optional UF filter) | | perfil_municipal | Full fiscal profile: CAPAG, RCL, consolidated debt, score, risk class | | score_credito_municipal | Credit scores per engine: LRF, CTN, fiscal health, payment capacity | | simular_operacao_credito | Simulate a credit operation and check LRF limits (DCL/RCL ≤ 120%) | | alertas_fiscais | Active fiscal-deterioration alerts for a municipality | | historico_fiscal | Historical time series of fiscal scores | | listar_municipios | List municipalities with UF/CAPAG filters and pagination | | gerar_laudo_completo | Full senior-analyst credit report: narrative, composite score, LRF framing, recommendation | | comparar_municipios | Compare 2–5 municipalities side by side; flags the lowest risk | | avaliar_carteira | Portfolio assessment: average score, CAPAG distribution, critical names, aggregate exposure | | risco_estado | State fiscal risk: DCL/RCL vs the 200% Law 9.496/97 limit, debt service, state CAPAG | | detalhe_motores | Per-engine score breakdown with analyst-language alerts and legal classification | | alerta_antecipado | Leading indicators of imminent fiscal degradation (CAUC trajectory, EWS variation) | | pipeline_emendas | Pending parliamentary amendments: executable vs CAUC-blocked value, sponsor concentration | | confiabilidade_setorial | Success rate of federal transfer agreements by ministry/agency |

Data Coverage

Argos is built for national scope by design — every tool resolves for all 5,570 Brazilian municipalities and all 27 federative units, not a sample. Underlying data domains:

• Fiscal accounts — SICONFI RREO/RGF: revenue, consolidated debt, personnel spend, statutory fiscal limits.
• Payment capacity — National Treasury CAPAG rating and its components.
• Compliance — CAUC pending items (the federal-transfer blocklist).
• Labor — CAGED formal-employment flows.
• Federal transfers — parliamentary amendments and intergovernmental agreement execution.
• Derived scores — deterministic analytical engines producing per-municipality credit and risk scores plus early-warning signals.

Coverage of any single metric depends on what the source publishes; the API returns nulls rather than fabricated values where a source has no datum.

Use Cases

• Municipal credit underwriting — pull a full profile and gerar_laudo_completo before lending to a municipality; check LRF headroom with simular_operacao_credito.
• Portfolio monitoring — run avaliar_carteira over a book of exposures to track average score, CAPAG mix and concentration of critical names.
• Early warning — alerta_antecipado and alertas_fiscais surface deterioration before a CAUC block freezes transfers.
• Receivables financing — pipeline_emendas quantifies parliamentary-amendment receivables and how much is blocked vs executable.
• Contagion analysis — risco_estado checks whether a municipality sits inside a fiscally stressed state.
• B2G intelligence — confiabilidade_setorial and comparar_municipios benchmark how well a municipality executes federal agreements, by sector.

How it works

Authentication: every API call sends the x-api-key: <ARGOS_API_KEY> header. Configuration is read from the process environment:

• ARGOS_API_BASE — API base URL (default https://argos-brown.vercel.app).
• ARGOS_API_KEY — required; without it the Horos Bank routes return 401/403 and every tool fails.

The server speaks MCP over stdio — it opens no network port. Diagnostic logs go to stderr (stdout is reserved for the protocol). A failed API call returns an error result (isError: true) so Claude can see the failure and react to it.

License

MIT.