Fiscalapi MCP

Fiscalapi MCP conecta tu cuenta a un cliente de IA, como Claude Code, Cursor o Codex, o a tu propia aplicación o agente. Emite, consulta y cancela CFDI 4.0 con los mismos permisos y créditos que la API y sin costo adicional.

Cómo funciona

Fiscalapi MCP es un servidor remoto del Model Context Protocol con transporte streamable HTTP. Tu cliente o tu aplicación se conecta con una API key y tu tenant, y cada tool llama a la API de Fiscalapi con esa credencial:

• El agente puede hacer lo mismo que la persona dueña de la API key, con sus permisos.
• Cada emisión consume un timbre, igual que en la API.
• Las reglas fiscales y las validaciones las aplica la API; un rechazo llega al agente con su detalle y, si trae un código del SAT o del PAC, con la página de errores que lo explica.

Lo conectas de dos formas, con el mismo servidor y las mismas tools:

Se autentica igual que la API: con tu API key y tu tenant (ver Credenciales). No usa OAuth, así que no se conecta desde ChatGPT ni desde los conectores de claude.ai.

Ambientes

Cada conexión opera un solo ambiente, el de su URL:

La API key debe ser del mismo ambiente que la URL: una API key de pruebas no funciona en producción. Empieza en pruebas y cambia la URL y la API key cuando tu flujo esté listo.

Credenciales

El servidor pide dos headers en cada solicitud, los mismos de la API:

Crea una API key solo para el MCP en Obtener credenciales y asígnala a la persona cuyos permisos quieres darle al agente. Así puedes revocarla en cualquier momento sin tocar tus otras integraciones.

Guarda las dos credenciales en variables de entorno. Los ejemplos de esta guía las leen de FISCALAPI_API_KEY y FISCALAPI_TENANT_KEY, y ninguno escribe su valor en un archivo de configuración: así no terminan en un repositorio. No pegues la API key en el chat del agente.

# Agrégalas a tu ~/.zshrc o ~/.bashrc y abre una terminal nueva.
export FISCALAPI_API_KEY='<tu-api-key>'
export FISCALAPI_TENANT_KEY='<tu-tenant>'

Un cliente de IA lee las variables al arrancar: después de definirlas, ciérralo por completo y ábrelo de nuevo. En macOS, un editor que abres desde el Dock puede no ver las variables de tu terminal; ábrelo desde la terminal.

En tu aplicación, las credenciales viven en su servidor: en variables de entorno o en el gestor de secretos de tu plataforma. Nunca las envíes al navegador ni las incluyas en el código del frontend: ahí quedan a la vista de cualquiera, y el MCP rechaza las solicitudes que vienen de una página web.

Los CSD y la e.firma (FIEL) no viajan por el MCP. Cárgalos en el dashboard o con Subir certificados. Para emitir, el agente usa como emisor a una persona que ya tiene su CSD cargado, y ninguna tool recibe certificados, llaves privadas ni contraseñas.

Datos de conexión

Estos datos sirven para cualquier cliente o aplicación que se conecte a un servidor MCP remoto:

Como el servidor no guarda sesión, tu aplicación puede abrir una conexión por tarea o reutilizar la misma, y puede conectarse desde funciones serverless.

Desde tu aplicación o agente

Tu backend se conecta con el SDK de MCP de su lenguaje. Los ejemplos se conectan al ambiente de pruebas, listan las tools y llaman a fiscalapi_get_tenant_overview:

// npm install @modelcontextprotocol/client
import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';

const transport = new StreamableHTTPClientTransport(new URL('https://test.mcp.fiscalapi.com/mcp'), {
  requestInit: {
    headers: {
      'X-API-KEY': process.env.FISCALAPI_API_KEY!,
      'X-TENANT-KEY': process.env.FISCALAPI_TENANT_KEY!
    }
  }
});
const client = new Client({ name: 'mi-app', version: '1.0.0' });
await client.connect(transport);

const { tools } = await client.listTools();
// Una emisión puede tardar más de 60 segundos: espera hasta 120.
const result = await client.callTool(
  { name: 'fiscalapi_get_tenant_overview', arguments: {} },
  { timeout: 120_000 }
);

await client.close();

En un agente propio, tu aplicación lista las tools y se las da a su modelo con su nombre, su descripción y su esquema de entrada, con el soporte de tools o function calling de tu proveedor. Cuando el modelo elige una tool, tu aplicación la ejecuta con callTool y le devuelve el resultado al modelo.

Si construyes tu agente con un framework que acepta un servidor MCP remoto por streamable HTTP con headers propios, configúralo con la URL y los dos headers de Datos de conexión.

Esperas y reintentos

• Una emisión puede tardar más de 60 segundos. Configura una espera de al menos 120 segundos por llamada.
• Cada tool de emisión exige una idempotencyKey. Genera una llave nueva por emisión; si una llamada se corta, repítela con la misma llave: si ya se timbró, recibes la misma factura.
• Cada credencial tiene su propio límite de solicitudes. Si recibes 429, espera los segundos que indica el header Retry-After.

Confirmación de emitir y cancelar en tu aplicación

Las 7 tools de emisión y fiscalapi_cancel_invoice piden confirmación desde el servidor solo si tu cliente declara la capacidad elicitation de formulario y negocia la versión 2026-07-28 del protocolo, la que trae las solicitudes de entrada en varias vueltas. En ese caso, la llamada responde con una solicitud de entrada que trae el resumen de la operación: muéstrasela a la persona y repite la llamada con su respuesta.

Si tu cliente no declara elicitation, la tool se ejecuta en cuanto la llamas. Tu aplicación es responsable de pedirle la confirmación a la persona antes de llamar a esas tools, o de conectarse a la ruta de solo lectura.

Prompts en tu aplicación

Los 3 prompts se listan con prompts/list y se obtienen con prompts/get.

Desde un cliente de IA

Estos son los pasos para los clientes más comunes. Cualquier otro cliente que acepte un servidor MCP remoto con headers se conecta con los Datos de conexión.

Los ejemplos usan el ambiente de pruebas. Para producción, cambia test por live en la URL y usa una API key de producción.

Claude Code

Agrega el servidor con un comando. Las comillas simples guardan la referencia a la variable, no su valor, y Claude Code la resuelve cada vez que se conecta:

claude mcp add --transport http fiscalapi https://test.mcp.fiscalapi.com/mcp \
  --header 'X-API-KEY: ${FISCALAPI_API_KEY}' \
  --header 'X-TENANT-KEY: ${FISCALAPI_TENANT_KEY}'

El comando lo agrega solo para el proyecto actual; con --scope user queda en todos tus proyectos. Para compartirlo con tu equipo, usa el archivo .mcp.json en la raíz del proyecto: Claude Code te pide aprobarlo la primera vez.

Comprueba la conexión con claude mcp list, que debe mostrar fiscalapi como conectado. Dentro de Claude Code, /mcp muestra sus tools.

Cursor

Agrega el servidor a ~/.cursor/mcp.json, o a .cursor/mcp.json para un solo proyecto. Cursor resuelve ${env:...} en los headers:

{
  "mcpServers": {
    "fiscalapi": {
      "url": "https://test.mcp.fiscalapi.com/mcp",
      "headers": {
        "X-API-KEY": "${env:FISCALAPI_API_KEY}",
        "X-TENANT-KEY": "${env:FISCALAPI_TENANT_KEY}"
      }
    }
  }
}

Las tools de fiscalapi aparecen en la configuración de MCP de Cursor. Si no conecta, revisa el panel Output, en el canal MCP Logs.

VS Code

Con el agente de GitHub Copilot, agrega el servidor a .vscode/mcp.json. Cada credencial va en un input con password, y VS Code te la pide la primera vez que arranca el servidor.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "fiscalapi-api-key",
      "description": "API key de Fiscalapi",
      "password": true
    },
    {
      "type": "promptString",
      "id": "fiscalapi-tenant-key",
      "description": "Tenant de Fiscalapi",
      "password": true
    }
  ],
  "servers": {
    "fiscalapi": {
      "type": "http",
      "url": "https://test.mcp.fiscalapi.com/mcp",
      "headers": {
        "X-API-KEY": "${input:fiscalapi-api-key}",
        "X-TENANT-KEY": "${input:fiscalapi-tenant-key}"
      }
    }
  }
}

Ese archivo lo lee el harness Local de VS Code. Si tus sesiones de chat usan el harness Copilot, configura el servidor en ~/.copilot/mcp-config.json, que lee las variables de entorno. Comprueba la conexión con el comando MCP: List Servers.

Codex

Agrega el servidor a ~/.codex/config.toml. env_http_headers asocia cada header con el nombre de su variable de entorno, y tool_timeout_sec da tiempo a una emisión, que puede tardar más que los 60 segundos que Codex espera por omisión:

[mcp_servers.fiscalapi]
url = "https://test.mcp.fiscalapi.com/mcp"
env_http_headers = { "X-API-KEY" = "FISCALAPI_API_KEY", "X-TENANT-KEY" = "FISCALAPI_TENANT_KEY" }
tool_timeout_sec = 120

codex mcp add no acepta headers, así que el servidor se agrega en el archivo. Comprueba la configuración con codex mcp list; dentro de Codex, /mcp muestra sus tools. Si una variable no está definida, Codex no envía su header y el servidor responde 401.

Windsurf

En Cascade, abre el menú de MCP y elige Open MCP config file. Agrega el servidor; Windsurf resuelve ${env:...} en los headers:

{
  "mcpServers": {
    "fiscalapi": {
      "serverUrl": "https://test.mcp.fiscalapi.com/mcp",
      "headers": {
        "X-API-KEY": "${env:FISCALAPI_API_KEY}",
        "X-TENANT-KEY": "${env:FISCALAPI_TENANT_KEY}"
      }
    }
  }
}

Guarda el archivo y presiona el botón de actualizar del panel de MCP para cargar las tools.

Solo lectura

Para un agente que solo consulta, conéctalo a la ruta de solo lectura de su ambiente en lugar de /mcp. Esa ruta publica solo las 10 tools de lectura y ningún prompt.

La ruta limita lo que ve el agente, no la API key: con la misma key, otra conexión a /mcp sí puede emitir y cancelar. Úsala para analizar CFDI recibidos o eventos de webhook (ver Contenido de terceros).

Tools

Las tools no administran API keys, certificados ni webhooks, y no borran registros. Para eso usa el dashboard o la API.

Prompts

Los prompts guían al agente en un flujo completo y le piden tu confirmación antes de emitir o cancelar. Según el cliente, aparecen como comandos del chat.

Créditos y efectos recurrentes

El MCP consume los mismos créditos que la API. Consulta tu saldo con fiscalapi_get_tenant_overview o en el dashboard.

Las demás tools no consumen créditos. En el ambiente de pruebas no hay conexión con el SAT: crear una regla de descarga responde 403, y fiscalapi_request_sat_download crea una solicitud de prueba con hasta 3 CFDI recientes de tu cuenta.

Personas y acceso al portal

Una persona que crea el agente nace sin contraseña y sin acceso al portal: no puede iniciar sesión en el dashboard. Si necesita entrar, el owner le da el acceso desde el dashboard o con loginEnabled en la API de Emisores. Las tools del MCP nunca cambian el correo, la contraseña ni el acceso al portal de una persona.

Seguridad

Datos que recibe el proveedor del modelo

Lo que escribes en el chat o lo que tu aplicación le envía al modelo, y lo que devuelven las tools (RFC, razones sociales, nóminas, conceptos), llega al proveedor del modelo que usan tu cliente o tu aplicación. Revisa sus condiciones antes de operar datos reales.

Confirmación de emitir y cancelar

Las 7 tools de emisión y fiscalapi_cancel_invoice piden tu confirmación desde el servidor, con un resumen de lo que van a hacer, en los clientes que soportan la confirmación del protocolo MCP (elicitation). Si rechazas, no se emite ni se cancela nada.

En los demás clientes, la confirmación es la aprobación de tools de tu cliente. Si activas su aprobación automática, el agente emite y cancela sin preguntarte. En tu propia aplicación, la confirmación le toca a tu aplicación (ver Desde tu aplicación o agente).

Si tu cliente declara la confirmación, pero no hay una persona que la responda (un modo no interactivo o un script), la emisión y la cancelación no se ejecutan. Para automatizar sin una persona delante, usa la API o los SDK.

Archivos XML y PDF

Ninguna tool devuelve el XML ni el PDF en el chat. fiscalapi_send_invoice_email los envía por correo al receptor de la factura o a la dirección que indiques.

Contenido de terceros

Los CFDI recibidos y los eventos de webhook traen texto que escribe otra persona, como razones sociales y descripciones de conceptos. El servidor le indica al agente que ese texto es un dato y no una instrucción, pero un agente con tools de escritura puede ser inducido por él. Para analizar ese contenido, conéctate a la ruta de solo lectura.

Solución de problemas

Fiscalapi MCP y docs-mcp

Son dos servidores distintos y se complementan. Conecta los dos si tu agente también escribe código que integra la API.

docs-mcp se instala aparte, como @fiscalapi/docs-mcp; las instrucciones por cliente están en su repositorio.