Skip to main content
Glama

MCP SAT 69 / 69-B · WATR

MCP (Model Context Protocol) server in Python / FastMCP for querying the SAT's public lists:

  • Article 69-B of the CFF (EFOS) — simulated operations: Presumed, Rebutted, Definitive, Favorable Ruling.

  • Article 69 of the CFF — final tax status: final, enforceable, not located, cancelled, forgiven.

Same architecture as the SSC-CDMX mobilizations MCP: FastMCP with stdio + Streamable HTTP transport, OAuth 2.1 (WorkOS AuthKit) with fallback to static bearer, persistence in Turso (libSQL), optional download proxy, and deployment on Render with external cron (GitHub Actions). No OCR: the SAT CSVs already come structured.

Tools

Tool

What it does

verificar_rfc

Verifies an RFC → risk verdict (CRITICO…LIMPIO).

verificar_lote

Validates up to 500 RFCs; returns only findings by severity.

buscar_nombre

Search by name/legal name (FTS5, accent-insensitive).

estado_datos

Validity declared by the SAT, counts, and last import.

actualizar_datos

Downloads + syncs the listings (idempotent by hash).

Risk: CRITICO (definitive EFOS) · ALTO (alleged EFOS) · MEDIO (69 final/enforceable/not located) · BAJO (rebutted/favorable ruling) · INFORMATIVO (69 cancelled/forgiven) · LIMPIO.

The results reflect the latest import of the SAT's public files. They do not constitute tax or legal advice.

Related MCP server: bcra-deudores-mcp

Architecture

CSV del SAT (Latin-1)                     ┌────────── FastMCP ──────────┐
   │  fetcher (httpx + proxy opcional)    │ verificar_rfc / _lote        │
   ▼                                      │ buscar_nombre / estado_datos │
 pipeline (parse 69 / 69b)  ──►  SQLite ──┤ actualizar_datos             │
   │   (FTS5 unicode61, triggers)  ▲  │   └──────────┬──────────────────┘
   ▼                               │  │   stdio (server.py) + HTTP (web.py)
 Turso (libSQL, durable) ◄── push  │  └► pull al arranque      │
                                   └─────────────────── /health /refresh /reload
  • server.py — FastMCP (stdio) + tools + AuthKit.

  • web.py — Starlette/uvicorn (HTTP): /health (open), /refresh and /reload (M2M bearer), /mcp (OAuth or bearer).

  • pipeline.py — download → SHA-256 (skips if unchanged) → Latin-1 parse → SQLite replacement → push to Turso.

  • database.py — SQLite + FTS5 with triggers; RFC via B-tree index (hot path).

  • turso.py — durable Turso ↔ local sync.

  • risk.py — RFC normalization + verdict tree (69-B takes precedence over 69).

Local installation

cd sat69-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Primera ingesta (descarga ~22 MB; el 69 son ~½ millón de filas)
python -c "from sat69 import database as db, config; db.init_db(config.settings.db_path)"
python -c "from sat69.pipeline import process_import; print(process_import())"

# Probar
pytest -q

Connect in Claude Desktop / Cowork (stdio)

{
  "mcpServers": {
    "sat69": { "command": "sat69-mcp" }
  }
}

(or "command": "python", "args": ["-m", "sat69"] with the active venv.)

Deployment on Render

render.yaml provisions the web service with native Python runtime (no Docker):

  1. Push the repo to GitHub and create a Blueprint in Render pointing to render.yaml.

  2. Variables (marked sync:false): MCP_API_KEY (bearer), optional AUTHKIT_DOMAIN+BASE_URL (OAuth), TURSO_DATABASE_URL+TURSO_AUTH_TOKEN.

  3. MCP endpoint: POST https://<servicio>.onrender.com/mcp.

Auth (two modes, same as mobilizations)

  • Static bearer (MCP_API_KEY): simple, protects /mcp, /refresh, /reload.

  • OAuth 2.1 (WorkOS AuthKit): set AUTHKIT_DOMAIN + BASE_URL and /mcp switches to OAuth with Dynamic Client Registration; the bearer still protects the M2M endpoints.

Automatic refresh

.github/workflows/refresh.yml performs a daily POST /refresh (11:30 UTC ≈ 05:30 CDMX). Repo secrets: RENDER_BASE_URL, MCP_API_KEY. Manual: workflow_dispatch (with force).

Persistence (Turso)

Local SQLite (ephemeral on Render, /tmp) serves the queries; Turso is the durable store that survives redeploys. On startup a pull from Turso is performed; after each actualizar_datos//refresh a push is performed. Without TURSO_*, it runs in pure local mode.

Download proxy (optional)

FETCH_PROXY or DATAIMPULSE_* route only the CSV downloads. In testing, the SAT did not block datacenter IPs (direct 200 downloads), so it's usually not needed; it's kept for parity and resilience.

Data sources (SAT · Open Data)

  • 69-B: Listado_Completo_69-B.csv (~14 k records, 20 columns, header on line 3).

  • 69: Firmes.csv, Cancelados.csv, NoLocalizados.csv, Exigibles.csv, Sentencias.csv, Condonados.csv (~½ million records, 6 columns). URLs in config.py.

Available Tools

6 tools
actualizar_datosBInspect

Descarga y sincroniza los listados del SAT (idempotente por hash).

Inputs: dataset, force_refresh. Returns: object

buscar_nombreAInspect

Busca contribuyentes por nombre / razón social parcial (FTS5, sin acentos).

Inputs: texto (required), limite, dataset. Returns: object

estado_datosAInspect

Estado del dataset: vigencia declarada por el SAT, conteos y última importación.

Inputs: no named parameters. Returns: object

resumen_carteraAInspect

Resumen ejecutivo en lenguaje natural de una cartera de RFCs.

El riesgo de cada RFC lo calcula el motor de reglas (DETERMINISTA); la IA sólo redacta el brief a partir de esos veredictos ya calculados — nunca decide el riesgo. Proveedor de IA conmutable por env var (LLM_PROVIDER).

Inputs: rfcs (required). Returns: object

verificar_loteBInspect

Verifica una lista de RFCs (p. ej. proveedores). Devuelve sólo hallazgos.

Inputs: rfcs (required). Returns: object

verificar_rfcAInspect

Verifica un RFC contra las listas del SAT (Art. 69, 69-B y 69-B Bis).

Inputs: rfc (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct concern: data status/update, single/batch verification, portfolio summary, and name search. The closest pair, verificar_rfc and verificar_lote, is disambiguated by singular vs batch operation.

    Naming Consistency4/5

    Most tools follow a clear verb_noun pattern: actualizar_datos, verificar_rfc, verificar_lote, buscar_nombre. Two names are noun phrases, estado_datos and resumen_cartera, which is a minor deviation from the otherwise consistent style.

    Tool Count5/5

    Six tools are well-scoped for this SAT list verification server. Each tool adds a distinct capability, covering data ingestion, verification, search, and summary without redundancy or bloat.

    Completeness4/5

    The toolset covers the core workflow: update and inspect dataset state, verify single or batch RFCs, search by name, and generate portfolio summaries. A dedicated detailed taxpayer-profile tool could be a minor addition, but the main use cases are well supported.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables querying the Colombian Business Registry (RUES) for company searches by name, location grouping, and detailed company information.
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables consultation of Argentine credit situations (Central de Deudores) via BCRA API, providing tools for current status, historical trends, rejected checks, and consolidated reports.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Query Brazilian Federal Revenue (Receita Federal) tax situation data from official sources via a single read-only tool, hosted and billed per use.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to validate Mexican RFC, CURP, CLABE and NSS identifiers with real check digits, parse CFDI 4.0 invoices with labelled SAT catalogue codes and verified totals, and query the SAT's public status service to see whether an invoice is still valid. It also generates coherent test people and companies, all read-only and without API keys, certificates or PAC contracts.
      9
      108 npm
      1
      MIT