MCP
MCP server
Connect AI agents to Exac through the production, permission-aware Model Context Protocol server backed by the same domain contracts as the REST API.
MCP server
MCP is currently production-only. OAuth exposes the tools allowed by the user’s role. A production organization API key exposes every tool available to that organization.
What is Exac MCP?
Exac MCP is a production-only remote Streamable HTTP server for the active organization. OAuth follows the user’s role; a production organization API key grants full API access.
https://adventurous-moose-616.convex.site- Search organization documents and fiscal records
- Create and manage business resources through shared domain contracts
- Retrieve fiscal reports and stored SAT data synchronized by Exac
Connect a client
Use the production Exac Convex site origin as the Streamable HTTP endpoint. OAuth is recommended for interactive agents; production organization API keys are suited to fixed integrations. Sandbox keys are not accepted by MCP.
OAuth configuration (recommended)
{ "mcpServers": { "exac": { "url": "https://adventurous-moose-616.convex.site" } }}Organization API-key configuration
{ "mcpServers": { "exac": { "url": "https://adventurous-moose-616.convex.site", "headers": { "Authorization": "Bearer <EXAC_API_KEY>" } } }}Three-step CFDI example
Create a draft, inspect its public documentRef, and stamp it only after review. The full REST and MCP workflow is in Quickstart.
{ "steps": [ { "tool": "create_invoice_draft", "arguments": { "idempotencyKey": "workflow-create-cfdi", "input": { "customerId": "customer-example", "items": [ { "kind": "custom", "description": "Consultoría administrativa · julio 2026", "quantity": 1, "unitPrice": 10000, "satProductCode": "84111506", "satUnitCode": "E48", "taxRate": 0.16, "taxability": "standard" } ], "kind": "income", "cfdiUse": "G03", "payment": { "timing": "deferred_or_installments", "formCode": "99", "conditions": "Crédito a 30 días" } } }, "environments": [ "production" ] }, { "tool": "get_document", "arguments": { "documentRef": "invoice:invoice-example" }, "environments": [ "production" ] }, { "tool": "stamp_invoice", "arguments": { "documentRef": "invoice:invoice-example", "idempotencyKey": "workflow-stamp-cfdi" }, "environments": [ "production" ] } ]}MCP result and error semantics
Every ordinary JSON tool returns a data envelope. Expected failures return an error envelope with a stable code; binary document files remain MCP resources.
Success envelope
JSON Schema{ "data": {}}Error envelope
JSON Schema{ "error": { "code": "validation_error", "message": "Request validation failed", "details": {} }}Recovery by error code
validation_error- Correct the request using error.message and, when present, details.issues paths and codes.
unauthenticated- Provide a valid API key or OAuth access token.
forbidden- Use a credential with the required permission.
payment_required- For details.reason = api_wallet_insufficient, add prepaid API/MCP credit using details.topUpUrl; balanceMinor is the balance in centavos. Otherwise review the billing requirement. Retry only after it is resolved.
not_found- Check the organization-scoped resource identifier.
method_not_allowed- Use the documented HTTP method.
conflict- Refresh the resource and resolve its current state.
idempotency_conflict- Use a new idempotency key for a changed request.
operation_in_progress- Wait for Retry-After, then repeat the exact request.
recovery_required- Do not retry automatically or change the idempotency key. Retrieve details.document.documentRef when present, verify the outcome, and contact support with Request-Id if it remains uncertain.
migration_required- Contact support to complete historical document migration; do not reissue the document.
rate_limited- Wait for Retry-After before retrying.
provider_unavailable- Retry only when the response marks the failure as retryable.
internal- A failed response does not prove that a write had no effect. Retry a read after backoff; retry a write only with its original idempotency key and unchanged request. Contact support with Request-Id if it persists.
Available tools
The server publishes only tools allowed by the active credential. Each MCP client receives the authoritative input schema through tools/list.
Organization and access
| MCP tool | Purpose | Safety |
|---|---|---|
get_organization | Read organization identity, fiscal readiness, SAT synchronization, global invoicing, and essential sales defaults. | Read only |
update_organization | Update one coherent organization settings section. | External side effect |
get_employees | Search or retrieve payroll employee records. | Read only |
save_employee | Create or update a payroll employee. | Writes data |
Setup and configuration
| MCP tool | Purpose | Safety |
|---|---|---|
get_configuration | Search or retrieve organization locations and receipt fields. | Read only |
search_sat_product_catalog | Search the official SAT product and service-key catalog. | Read only |
save_configuration | Create or update an organization location or receipt field. Creating a field with an existing normalized name returns conflict; retrieve it with get_configuration and use operation update with its entryId. For field updates, omit values to preserve options; a supplied array replaces all options and an empty array clears them. Never use an incomplete preview as the replacement. | Writes data |
get_fiscal_series | Read fiscal series and development/production folio counters. | Read only |
update_fiscal_series | Edit an existing fiscal series code and its folio counters. | Destructive and external |
Document discovery and delivery
| MCP tool | Purpose | Safety |
|---|---|---|
search_documents | Search one public document family at a time using stable public document references. | Read only |
get_document | Retrieve one document by its public documentRef. | Read only |
send_document | Deliver a CFDI, withholding, or sales receipt to a recipient. | External side effect |
get_document_file | Retrieve one available document file as an MCP binary resource. | Read only |
Invoices and withholding
| MCP tool | Purpose | Safety |
|---|---|---|
create_withholding | Create and immediately stamp a SAT withholding document. | Destructive and external |
create_invoice_draft_from_sales_receipts | Create a CFDI draft from compatible open sales receipts. | External side effect |
create_invoice_draft | Create a tax-validated CFDI draft for income, credit note, transfer, or payment-complement flows. | External side effect |
create_payroll_invoice_draft | Create a tax-validated payroll CFDI draft. | External side effect |
update_invoice_draft | Replace the contents of an existing CFDI draft. | External side effect |
update_payroll_invoice_draft | Replace the contents of an existing payroll CFDI draft. | External side effect |
stamp_invoice | Irreversibly submit a CFDI draft for SAT stamping. | Destructive and external |
refresh_invoice_status | Ask SAT for the current status of a stamped production CFDI and reconcile local state. Exac sandbox documents are simulated and cannot be verified with SAT; use get_document to read their stored state. | External side effect |
cancel_fiscal_document | Request cancellation of a stamped CFDI or withholding. pending: true acknowledges the request without confirming cancellation. For withholdings, get_document reads stored state; automatic SAT status refresh is unavailable. Verify independently through the [SAT Retenciones verification portal](https://prodretencionverificacion.clouda.sat.gob.mx/). An available acuse does not by itself confirm completion. Never automatically resubmit or change idempotency keys after recovery_required or an uncertain outcome. | Destructive and external |
archive_fiscal_document | Archive or restore a CFDI or withholding document without deleting its history. | Writes data |
get_payroll | Read payroll settings, runs, and their receipts before preparing, adjusting, or stamping them. | Read only |
save_payroll | Prepare a pay period and adjust its receipts before they are stamped. | Writes data |
stamp_payroll | Irreversibly submit a run's ready receipts, or one corrected rejected receipt, for SAT stamping. | Destructive and external |
Sales
| MCP tool | Purpose | Safety |
|---|---|---|
create_sales_receipt | Create a POS sales receipt without stamping a CFDI. Paid and credit lines without productId require satProductCode and satUnitCode at creation; catalog products supply their own fiscal identity. | Writes data |
cancel_sales_receipt | Cancel an open sales receipt while preserving sales history. | Destructive |
refund_sales_receipt | Register a sales receipt refund and, when applicable, create a CFDI credit note. | Destructive and external |
Business catalog and inventory
| MCP tool | Purpose | Safety |
|---|---|---|
get_products | Search products, retrieve one product, or list linked suppliers. | Read only |
get_contacts | Search or retrieve customers and suppliers. | Read only |
get_inventory | Read inventory levels, movements, or grouped movement operations. | Read only |
save_contact | Create or update a customer or supplier. | Writes data |
save_product | Create or update an organization product. | Writes data |
update_inventory | Set or restock a product inventory level. | Destructive |
receive_inventory | Record a multi-product supplier inventory delivery at a location. | Destructive |
get_price_overrides | List product price overrides for a customer or business location. | Read only |
set_price_override | Set or remove a product price override for a customer or location. | Writes data |
Fiscal accounts and analytics
| MCP tool | Purpose | Safety |
|---|---|---|
get_accounts | Search accounts or read one account. | Read only |
archive_account_document | Exclude or restore one document in active receivables or payables. | Destructive |
set_payment_plan | Create, replace, or clear the installment terms of an unpaid PPD invoice. | Destructive |
Reports and fiscal data
| MCP tool | Purpose | Safety |
|---|---|---|
get_income_expenses_summary | Summarize CFDI activity for a fiscal year or month. | Read only |
get_sales_receipt_summary | Summarize sales recorded as Exac receipts for a business day, with its month's top customers, products, and locations. | Read only |
get_invoicing_summary | Summarize recent invoicing, settlement, payment methods, and top counterparties. | Read only |
get_payroll_summary | Summarize recent payroll issued, its net pay and ISR withheld, and top employees. | Read only |
get_tax_summary | Read authoritative declared, paid, and pending tax totals. | Read only |
Official tax law and parameters
| MCP tool | Purpose | Safety |
|---|---|---|
search_tax_law | Find the articles of the official Mexican tax laws that mention given words, on a date. | Read only |
get_tax_law | Read the full text of one article of an official Mexican tax law on a date, or what changed since a date. | Read only |
get_tax_rules | List the approved tax parameters and read their values in force on a date, with evidence. | Read only |
Security guidance
Review tool calls before execution and never paste credentials into prompts. Production organization API keys grant full API access; use OAuth when access should follow a user’s role. Destructive tools remain explicitly annotated for client confirmation.