Fiscalapi MCP

Fiscalapi MCP connects your tenant (the space in Fiscalapi that holds your issuers, recipients, credits, and data) to an AI client such as Claude Code, Cursor, or Codex, or to your own app or agent. Issue, look up, and cancel CFDI 4.0 invoices (CFDI: Mexico's electronic invoice) with the same permissions and credits as the API, at no extra cost.

How it works

Fiscalapi MCP is a remote Model Context Protocol server with the streamable HTTP transport. Your client or your app connects with an API key and your tenant, and each tool calls the Fiscalapi API with that credential:

• The agent can do what the person (any individual or legal entity registered in your tenant) who owns the API key can do, with that person's permissions.
• Each CFDI the agent issues uses one stamp (one credit, used each time you stamp a CFDI), as in the API.
• The API applies the tax rules and validations. A rejection reaches the agent with its details and, if it carries a SAT (Mexico's tax authority, Servicio de Administración Tributaria) or PAC (Proveedor Autorizado de Certificación, a SAT-authorized provider that stamps CFDIs) code, with the errors page that explains it.

You can connect it in two ways, with the same server and the same tools:

It authenticates the same way as the API: with your API key and your tenant (see Credentials). It doesn't use OAuth, so you can't connect from ChatGPT or from claude.ai connectors.

Environments

Each connection works in a single environment, the one in its URL:

The API key must belong to the same environment as the URL: a test API key doesn't work in production. Start in test, and switch the URL and the API key when your flow is ready.

Credentials

The server requires two headers on every request, the same ones as the API:

Create an API key only for the MCP in Get credentials and assign it to the person whose permissions you want to give the agent. You can revoke it at any time without affecting your other integrations.

Store both credentials in environment variables. The examples in this guide read them from FISCALAPI_API_KEY and FISCALAPI_TENANT_KEY, and none of them writes their values to a configuration file, so they don't end up in a repository. Don't paste the API key into the agent's chat.

# Add them to your ~/.zshrc or ~/.bashrc and open a new terminal.
export FISCALAPI_API_KEY='<tu-api-key>'
export FISCALAPI_TENANT_KEY='<tu-tenant>'

An AI client reads the variables when it starts: after you set them, quit it completely and open it again. On macOS, an editor you open from the Dock might not see your terminal's variables; open it from the terminal.

In your app, the credentials live on its server: in environment variables or in your platform's secrets manager. Never send them to the browser or include them in your frontend code: anyone can see them there, and the MCP rejects requests that come from a web page.

CSDs (Certificado de Sello Digital, the digital seal certificate used to sign CFDIs) and the e.firma (the SAT advanced electronic signature that identifies a taxpayer, formerly FIEL) never travel through the MCP. Upload them in the dashboard or with Upload tax files. To issue, the agent uses a person whose CSD is already uploaded as the issuer, and no tool accepts certificates, private keys, or passwords.

Connection details

These details work for any client or app that connects to a remote MCP server:

Because the server doesn't keep a session, your app can open one connection per task or reuse the same one, and it can connect from serverless functions.

From your app or agent

Your backend connects with the MCP SDK for its language. The examples connect to the test environment, list the tools, and call 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();
// An issuance can take longer than 60 seconds: wait up to 120.
const result = await client.callTool(
  { name: 'fiscalapi_get_tenant_overview', arguments: {} },
  { timeout: 120_000 }
);

await client.close();

In your own agent, your app lists the tools and gives them to its model with their name, description, and input schema, through your provider's tool use or function calling. When the model picks a tool, your app runs it with callTool and returns the result to the model.

If you build your agent with a framework that accepts a remote MCP server over streamable HTTP with custom headers, configure it with the URL and the two headers in Connection details.

Timeouts and retries

• An issuance can take longer than 60 seconds. Set a timeout of at least 120 seconds per call.
• Each issuance tool requires an idempotencyKey. Generate a new key for each issuance; if a call is cut off, repeat it with the same key: if it was already stamped, you get the same invoice.
• Each credential has its own request limit. If you get a 429, wait the number of seconds in the Retry-After header.

Confirmation to issue and cancel in your app

The 7 issuance tools and fiscalapi_cancel_invoice ask for confirmation from the server only if your client declares the form elicitation capability and negotiates the 2026-07-28 version of the protocol, the one that adds input requests across several round trips. In that case, the call responds with an input request that carries a summary of the operation: show it to the person and repeat the call with their answer.

If your client doesn't declare elicitation, the tool runs as soon as you call it. Your app is responsible for asking the person for confirmation before it calls those tools, or for connecting to the read-only path.

Prompts in your app

You list the 3 prompts with prompts/list and get each one with prompts/get.

From an AI client

These are the steps for the most common clients. Any other client that accepts a remote MCP server with headers connects with the Connection details.

The examples use the test environment. For production, change test to live in the URL and use a production API key.

Claude Code

Add the server with a command. The single quotes store a reference to the variable, not its value, and Claude Code resolves it each time it connects:

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}'

The command adds the server for the current project only; with --scope user, it's available in all your projects. To share it with your team, use the .mcp.json file at the project root: Claude Code asks you to approve it the first time.

Check the connection with claude mcp list, which should show fiscalapi as connected. Inside Claude Code, /mcp shows its tools.

Cursor

Add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json for a single project. Cursor resolves ${env:...} in the 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}"
      }
    }
  }
}

The fiscalapi tools appear in Cursor's MCP settings. If it doesn't connect, check the Output panel, in the MCP Logs channel.

VS Code

With the GitHub Copilot agent, add the server to .vscode/mcp.json. Each credential goes in an input with password, and VS Code prompts you for it the first time the server starts.

{
  "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}"
      }
    }
  }
}

The VS Code Local harness reads that file. If your chat sessions use the Copilot harness, configure the server in ~/.copilot/mcp-config.json, which reads the environment variables. Check the connection with the MCP: List Servers command.

Codex

Add the server to ~/.codex/config.toml. env_http_headers maps each header to the name of its environment variable, and tool_timeout_sec gives issuances enough time, since they can take longer than the 60 seconds Codex waits by default:

[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 doesn't accept headers, so you add the server in the file. Check the configuration with codex mcp list; inside Codex, /mcp shows its tools. If a variable isn't set, Codex doesn't send its header and the server responds with a 401.

Windsurf

In Cascade, open the MCP menu and choose Open MCP config file. Add the server; Windsurf resolves ${env:...} in the 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}"
      }
    }
  }
}

Save the file and press the refresh button in the MCP panel to load the tools.

Read-only

For an agent that only looks things up, connect it to the read-only path of its environment instead of /mcp. That path publishes only the 10 read tools and no prompts.

The path limits what the agent sees, not the API key: with the same key, another connection to /mcp can still issue and cancel. Use it to analyze received CFDIs or webhook events (see Third-party content).

Tools

The tools don't manage API keys, tax files, or webhooks, and they don't delete records. For that, use the dashboard or the API.

Prompts

The prompts guide the agent through a complete flow and ask for your confirmation before they issue or cancel. Depending on the client, they appear as chat commands.

Credits and recurring effects

The MCP uses the same credits as the API. Check your balance with fiscalapi_get_tenant_overview or in the dashboard.

The other tools don't use credits. The test environment has no connection to the SAT: creating a download rule responds with a 403, and fiscalapi_request_sat_download creates a test request with up to 3 recent CFDIs from your tenant.

People and dashboard access

A person the agent creates has no password and no dashboard access: they can't sign in to the dashboard. If they need to, the owner (the person who created the tenant) gives them access from the dashboard or with loginEnabled in the Issuers API. The MCP tools never change a person's email, password, or dashboard access.

Security

Data the model provider receives

What you write in the chat or what your app sends to the model, and what the tools return (RFCs, legal names, payroll, line items), reaches the provider of the model that your client or your app uses. Review its terms before you work with real data.

Confirmation to issue and cancel

The 7 issuance tools and fiscalapi_cancel_invoice ask for your confirmation from the server, with a summary of what they'll do, in clients that support the MCP confirmation (elicitation). If you decline, nothing is issued or canceled.

In other clients, the confirmation is your client's tool approval. If you turn on its automatic approval, the agent issues and cancels without asking you. In your own app, asking for the confirmation is your app's job (see From your app or agent).

If your client declares the confirmation but no one is there to answer it (a non-interactive mode or a script), issuance and cancellation don't run. To automate without a person present, use the API or the SDKs.

XML and PDF files

No tool returns the XML or the PDF in the chat. fiscalapi_send_invoice_email emails them to the invoice's recipient or to the address you specify.

Third-party content

Received CFDIs and webhook events carry text that someone else writes, such as legal names and line item descriptions. The server tells the agent that this text is data, not an instruction, but an agent with write tools can be steered by it. To analyze that content, connect to the read-only path.

Troubleshooting

Fiscalapi MCP and docs-mcp

They're two different servers that complement each other. Connect both if your agent also writes code that integrates the API.

You install docs-mcp separately, as @fiscalapi/docs-mcp; the instructions for each client are in its repository.