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 operational records
- Create and manage business resources through shared domain contracts
- Retrieve fiscal reports and synchronize permitted SAT data
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 remains in the introduction.
{ "steps": [ { "tool": "create_cfdi_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": "cfdi:invoice-example" }, "environments": [ "production" ] }, { "tool": "get_document_file", "arguments": { "documentRef": "cfdi:invoice-example", "file": "preview_pdf" }, "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 each details.issues entry using its path and stable issue code.
unauthenticated- Provide a valid API key or OAuth access token.
forbidden- Use a credential with the required permission.
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; reconcile the provider outcome.
rate_limited- Wait for Retry-After before retrying.
provider_unavailable- Retry only when the response marks the failure as retryable.
internal- Retry later and contact support if the error 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 | Get the active organization profile, fiscal identity, readiness, certificate status, global-invoice settings, SAT synchronization, and essential sales defaults. | Read only |
update_organization | Update one coherent organization settings section: profile, fiscal identity, essential sales defaults, automatic global invoice, or SAT synchronization. Read get_organization first. | External side effect |
get_employees | Search payroll employees or retrieve one employee. Search matches name, RFC, CURP, employee number, job title, or department. | Read only |
save_employee | Create or update one payroll employee. SAT catalog fields use their public business names and corresponding SAT codes. | Writes data |
Setup and configuration
| MCP tool | Purpose | Safety |
|---|---|---|
get_configuration | Search organization configuration or retrieve one location, expense category, or custom receipt field. | Read only |
search_sat_product_catalog | Search the official SAT product and service-key catalog by description or key. | Read only |
save_configuration | Create or update one organization configuration entry: a location, expense category, or custom receipt field. | Writes data |
get_fiscal_series | Get the organization fiscal series and their development and production counters. | Read only |
update_fiscal_series | Edit an existing fiscal series code and its development and production counters. | Destructive and external |
Document discovery and delivery
| MCP tool | Purpose | Safety |
|---|---|---|
search_documents | Search one public document family at a time. Use cfdi for income, credit-note, transfer, payroll, and payment-complement documents; use withholding, sales_receipt, quote, expense, declaration, tax_compliance_opinion, or sales_receipt_refund for the other families. | Read only |
get_document | Retrieve one document by its public documentRef. Sales receipt details include stable lineRef values and remaining refundable amounts for sales receipt refunds. | Read only |
send_document | Send a document to a recipient. CFDI documents support the document or cancellation_receipt attachment set; sales receipts and quotes support document only. | External side effect |
get_document_file | Retrieve one document file as an MCP binary resource. Use preview_pdf to render an unstamped CFDI draft before stamping; the preview has no fiscal validity. CFDIs also support pdf, xml, zip, cancellation_pdf, and cancellation_xml; withholdings support pdf, xml, and zip; sales receipts and quotes support pdf; declarations support pdf, payment_pdf, and full_pdf; opinions support pdf. | Read only |
CFDI and withholding
| MCP tool | Purpose | Safety |
|---|---|---|
create_withholding | Create and immediately stamp a SAT withholding document. Each tax entry uses business names for tax and paymentType; withholdingTypeCode is the explicit SAT catalog code. This operation has no draft mode. | Destructive and external |
create_cfdi_draft_from_sales_receipts | Create a CFDI draft from one or more compatible open sales receipts. Inspect the receipts first; they must match on customer, currency, payment form, and payment timing. This operation never stamps or sends the CFDI. | External side effect |
create_cfdi_draft | Create a CFDI draft with canonical tax validation. Payment complements accept automatic taxes for known CFDIs or caller-provided taxObject and payment-level tax entries for external CFDIs. This tool never stamps. | External side effect |
update_cfdi_draft | Fully replace the contents of an existing CFDI draft. The semantic kind must match the draft; changing fiscal kind requires archiving the old draft and creating a new draft. | External side effect |
stamp_cfdi | Irreversibly stamp an existing CFDI draft. Review the draft first with get_document. Safe retries require reusing the same idempotencyKey. | Destructive and external |
refresh_cfdi_status | Consult SAT directly for the current status of a stamped CFDI and reconcile the local document state. This requires verification data captured from its XML. | External side effect |
cancel_fiscal_document | Request SAT cancellation for a stamped CFDI or withholding document. Drafts should be archived instead. | Destructive and external |
archive_fiscal_document | Archive or restore a CFDI or withholding document without deleting its fiscal or authoring history. | Writes data |
Sales and quotes
| MCP tool | Purpose | Safety |
|---|---|---|
save_quote | Create a draft quote or update an existing quote. operation selects create or update; documentRef is required only for update. | Writes data |
publish_quote | Publish a quote to the customer portal. | External side effect |
cancel_quote | Cancel a draft or sent quote. | Destructive |
record_quote_payment | Record a manual payment for an accepted quote. | Destructive and external |
create_sales_receipt | Create a POS sale receipt. A non-courtesy sale requires paymentForm; credit sales require paymentForm 99 and a stored customer.customerId with credit enabled. This operation never stamps a CFDI. | Writes data |
cancel_sales_receipt | Cancel an open receipt while preserving its operational history. | Destructive |
refund_sales_receipt | Register a receipt refund. A refund may create a CFDI credit note; use the returned receipt refund document to follow its lifecycle. | Destructive and external |
Business catalog and inventory
| MCP tool | Purpose | Safety |
|---|---|---|
get_products | Search products, retrieve one product, or list its linked suppliers. | Read only |
get_contacts | Search customers/suppliers or retrieve one contact. Choose operation search or get, then choose kind customer or supplier. | Read only |
get_inventory | Read product inventory levels, product movements, the organization movement register, grouped inventory operations, or the movements within one inventory operation. | Read only |
save_contact | Create or update one customer/supplier. Use get_contacts to obtain contactId for updates. Credit fields apply only to customers. | Writes data |
save_product | Create a product or update an existing product in the organization catalog. operation selects create or update. | Writes data |
update_inventory | Set or restock a product inventory level. mode selects whether stock is replaced or increased. | Destructive |
receive_inventory | Record a multi-product supplier inventory delivery at a location. | Destructive |
get_price_overrides | List product price overrides for one customer or business location. subjectId is the customerId from get_contacts or locationId from get_configuration. | Read only |
set_price_override | Set or remove one product price override for a customer or location. Set price to null to restore the product default. | Writes data |
Accounts and expenses
| MCP tool | Purpose | Safety |
|---|---|---|
create_expense | Create an operational expense. Credit expenses require supplierId, paymentForm 99, and settlement terms; pay supplier-linked credit expenses with record_payment. | Writes data |
get_accounts | Search receivable/payable accounts, retrieve one account, or list its ledger movements. Use customerId for receivables and supplierId for payables. | Read only |
correct_expense_settlement | Set whether an expense is paid or remains on supplier credit. Paid expenses cannot use payment form 99; credit expenses must use 99. | Writes data |
record_payment | Record money received from a customer or paid to a supplier and allocate it to open balances. Use the same idempotencyKey when retrying the exact payment. | Writes data |
adjust_account_balance | Correct one receivable or payable balance with an auditable reason. kind selects the account family; balanceType selects an operational document or fiscal PPD balance. | Destructive |
reschedule_receivable_plan | Replace the installment schedule for an unpaid receivable plan. Use the same idempotencyKey when retrying the exact schedule change. | Destructive |
set_payable_payment_plan | Create or replace the payment plan for a received PPD invoice. | Destructive |
Reports and synchronization
| MCP tool | Purpose | Safety |
|---|---|---|
get_cfdi_summary | Summarize CFDI activity for a month range: recognized income, recognized expenses, payroll paid, payroll received, balance, and top contributors. Every payroll contributor has a paid or received direction. Uses CFDI aggregates only. It excludes receipt/POS sales and is never a source for taxes paid or owed. | Read only |
get_sales_receipt_summary | Summarize sales recorded as Exac receipts for one business day. Use this for 'how much did I sell?'. It includes receipts later invoiced and receipts never invoiced, and never adds CFDI totals separately. | Read only |
get_expense_cash_summary | Summarize manual operational cash outflows for one business day. It includes paid manual expenses and payments allocated to manual credit expenses. It excludes received CFDI invoices and unpaid manual expenses. Historical coverage is forward-only until a backfill is intentionally run. | Read only |
get_cfdi_collection_summary | Summarize gross cash collected through valid sent Type I invoices for one CFDI civil day. PUE invoices are recognized on Fecha and PPD collections on payment-complement FechaPago. PPD parents are never counted as cash, so payment allocations cannot double count them. Historical coverage is forward-only until an intentional backfill. | Read only |
get_tax_summary | Get authoritative taxes declared, paid, and pending for a fiscal year or month. Tax amounts come only from parsed declarations; CFDI contributor context is informational and never affects tax totals. If declarations are unavailable, tax totals are null rather than estimated. | Read only |
sync_sat_data | Refresh one SAT source for the active organization. Use documents for CFDIs/withholdings in a date range, declarations for one fiscal year, or compliance_opinion for the latest SAT opinion. This starts external SAT work; read results with search_documents or get_tax_summary. | External side effect |
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.