---
title: "MCP server"
description: "Connect AI agents to Exac through the production, permission-aware Model Context Protocol server backed by the same domain contracts as the REST API."
language: en
canonical_url: "https://exac.mx/docs/en/mcp"
md_url: "https://exac.mx/docs/en/mcp.md"
---

# 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.

## 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.

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.

Endpoint: `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)

```json
{
  "mcpServers": {
    "exac": {
      "url": "https://adventurous-moose-616.convex.site"
    }
  }
}
```

### Organization API-key configuration

```json
{
  "mcpServers": {
    "exac": {
      "url": "https://adventurous-moose-616.convex.site",
      "headers": {
        "Authorization": "Bearer <EXAC_API_KEY>"
      }
    }
  }
}
```

## 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.

```json
{
  "data": {}
}
```

```json
{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": {}
  }
}
```

Recommended action by 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 MCP tools

### Organization and access

- [`get_organization`](/docs/en/mcp/tools/get_organization.md) — Get the active organization profile, fiscal identity, readiness, certificate status, global-invoice settings, SAT synchronization, and essential sales defaults.

- [`update_organization`](/docs/en/mcp/tools/update_organization.md) — Update one coherent organization settings section: profile, fiscal identity, essential sales defaults, automatic global invoice, or SAT synchronization. Read get_organization first.

- [`get_employees`](/docs/en/mcp/tools/get_employees.md) — Search payroll employees or retrieve one employee. Search matches name, RFC, CURP, employee number, job title, or department.

- [`save_employee`](/docs/en/mcp/tools/save_employee.md) — Create or update one payroll employee. SAT catalog fields use their public business names and corresponding SAT codes.

### Setup and configuration

- [`get_configuration`](/docs/en/mcp/tools/get_configuration.md) — Search organization configuration or retrieve one location, expense category, or custom receipt field.

- [`search_sat_product_catalog`](/docs/en/mcp/tools/search_sat_product_catalog.md) — Search the official SAT product and service-key catalog by description or key.

- [`save_configuration`](/docs/en/mcp/tools/save_configuration.md) — Create or update one organization configuration entry: a location, expense category, or custom receipt field.

- [`get_fiscal_series`](/docs/en/mcp/tools/get_fiscal_series.md) — Get the organization fiscal series and their development and production counters.

- [`update_fiscal_series`](/docs/en/mcp/tools/update_fiscal_series.md) — Edit an existing fiscal series code and its development and production counters.

### Document discovery and delivery

- [`search_documents`](/docs/en/mcp/tools/search_documents.md) — 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.

- [`get_document`](/docs/en/mcp/tools/get_document.md) — Retrieve one document by its public documentRef. Sales receipt details include stable lineRef values and remaining refundable amounts for sales receipt refunds.

- [`send_document`](/docs/en/mcp/tools/send_document.md) — Send a document to a recipient. CFDI documents support the document or cancellation_receipt attachment set; sales receipts and quotes support document only.

- [`get_document_file`](/docs/en/mcp/tools/get_document_file.md) — 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.

### CFDI and withholding

- [`create_withholding`](/docs/en/mcp/tools/create_withholding.md) — 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.

- [`create_cfdi_draft_from_sales_receipts`](/docs/en/mcp/tools/create_cfdi_draft_from_sales_receipts.md) — 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.

- [`create_cfdi_draft`](/docs/en/mcp/tools/create_cfdi_draft.md) — 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.

- [`update_cfdi_draft`](/docs/en/mcp/tools/update_cfdi_draft.md) — 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.

- [`stamp_cfdi`](/docs/en/mcp/tools/stamp_cfdi.md) — Irreversibly stamp an existing CFDI draft. Review the draft first with get_document. Safe retries require reusing the same idempotencyKey.

- [`refresh_cfdi_status`](/docs/en/mcp/tools/refresh_cfdi_status.md) — 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.

- [`cancel_fiscal_document`](/docs/en/mcp/tools/cancel_fiscal_document.md) — Request SAT cancellation for a stamped CFDI or withholding document. Drafts should be archived instead.

- [`archive_fiscal_document`](/docs/en/mcp/tools/archive_fiscal_document.md) — Archive or restore a CFDI or withholding document without deleting its fiscal or authoring history.

### Sales and quotes

- [`save_quote`](/docs/en/mcp/tools/save_quote.md) — Create a draft quote or update an existing quote. operation selects create or update; documentRef is required only for update.

- [`publish_quote`](/docs/en/mcp/tools/publish_quote.md) — Publish a quote to the customer portal.

- [`cancel_quote`](/docs/en/mcp/tools/cancel_quote.md) — Cancel a draft or sent quote.

- [`record_quote_payment`](/docs/en/mcp/tools/record_quote_payment.md) — Record a manual payment for an accepted quote.

- [`create_sales_receipt`](/docs/en/mcp/tools/create_sales_receipt.md) — 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.

- [`cancel_sales_receipt`](/docs/en/mcp/tools/cancel_sales_receipt.md) — Cancel an open receipt while preserving its operational history.

- [`refund_sales_receipt`](/docs/en/mcp/tools/refund_sales_receipt.md) — Register a receipt refund. A refund may create a CFDI credit note; use the returned receipt refund document to follow its lifecycle.

### Business catalog and inventory

- [`get_products`](/docs/en/mcp/tools/get_products.md) — Search products, retrieve one product, or list its linked suppliers.

- [`get_contacts`](/docs/en/mcp/tools/get_contacts.md) — Search customers/suppliers or retrieve one contact. Choose operation search or get, then choose kind customer or supplier.

- [`get_inventory`](/docs/en/mcp/tools/get_inventory.md) — Read product inventory levels, product movements, the organization movement register, grouped inventory operations, or the movements within one inventory operation.

- [`save_contact`](/docs/en/mcp/tools/save_contact.md) — Create or update one customer/supplier. Use get_contacts to obtain contactId for updates. Credit fields apply only to customers.

- [`save_product`](/docs/en/mcp/tools/save_product.md) — Create a product or update an existing product in the organization catalog. operation selects create or update.

- [`update_inventory`](/docs/en/mcp/tools/update_inventory.md) — Set or restock a product inventory level. mode selects whether stock is replaced or increased.

- [`receive_inventory`](/docs/en/mcp/tools/receive_inventory.md) — Record a multi-product supplier inventory delivery at a location.

- [`get_price_overrides`](/docs/en/mcp/tools/get_price_overrides.md) — List product price overrides for one customer or business location. subjectId is the customerId from get_contacts or locationId from get_configuration.

- [`set_price_override`](/docs/en/mcp/tools/set_price_override.md) — Set or remove one product price override for a customer or location. Set price to null to restore the product default.

### Accounts and expenses

- [`create_expense`](/docs/en/mcp/tools/create_expense.md) — Create an operational expense. Credit expenses require supplierId, paymentForm 99, and settlement terms; pay supplier-linked credit expenses with record_payment.

- [`get_accounts`](/docs/en/mcp/tools/get_accounts.md) — Search receivable/payable accounts, retrieve one account, or list its ledger movements. Use customerId for receivables and supplierId for payables.

- [`correct_expense_settlement`](/docs/en/mcp/tools/correct_expense_settlement.md) — Set whether an expense is paid or remains on supplier credit. Paid expenses cannot use payment form 99; credit expenses must use 99.

- [`record_payment`](/docs/en/mcp/tools/record_payment.md) — 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.

- [`adjust_account_balance`](/docs/en/mcp/tools/adjust_account_balance.md) — Correct one receivable or payable balance with an auditable reason. kind selects the account family; balanceType selects an operational document or fiscal PPD balance.

- [`reschedule_receivable_plan`](/docs/en/mcp/tools/reschedule_receivable_plan.md) — Replace the installment schedule for an unpaid receivable plan. Use the same idempotencyKey when retrying the exact schedule change.

- [`set_payable_payment_plan`](/docs/en/mcp/tools/set_payable_payment_plan.md) — Create or replace the payment plan for a received PPD invoice.

### Reports and synchronization

- [`get_cfdi_summary`](/docs/en/mcp/tools/get_cfdi_summary.md) — 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.

- [`get_sales_receipt_summary`](/docs/en/mcp/tools/get_sales_receipt_summary.md) — 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.

- [`get_expense_cash_summary`](/docs/en/mcp/tools/get_expense_cash_summary.md) — 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.

- [`get_cfdi_collection_summary`](/docs/en/mcp/tools/get_cfdi_collection_summary.md) — 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.

- [`get_tax_summary`](/docs/en/mcp/tools/get_tax_summary.md) — 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.

- [`sync_sat_data`](/docs/en/mcp/tools/sync_sat_data.md) — 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.

## 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.

Complete documentation: https://exac.mx/docs/en.md
Agent documentation index: https://exac.mx/docs/en/llms.txt