# Saudi Invoice MCP

> A remote MCP server that lets any AI agent report and clear Saudi Arabia tax invoices through ZATCA (Fatoora Phase 2), the national e-invoicing gateway. It wraps the submission calls only: ECDSA signing and the ICV/PIH hash-chain stay merchant-side. Stateless, bring-your-own CSID, never stores anything.

- MCP endpoint (Streamable HTTP): https://inv-sa.wishpool.app/mcp
- Credentials headers: x-zatca-csid-token (your CSID binarySecurityToken from ZATCA EGS onboarding) + x-zatca-csid-secret (its secret). Sent to ZATCA as HTTP Basic auth. Your certificate and private key never leave your side.
- Mode header: x-zatca-mode: core submits to production (real fiscal effect); simulation = simulation env; developer (default) = developer-portal sandbox (no fiscal effect).
- Design: this server ONLY forwards ZATCA reporting/clearance submission calls. You build + ECDSA-sign the UBL 2.1 invoice, compute its invoiceHash, and pass { invoiceHash, uuid, invoice(base64 signed XML) }. We never sign and never store hash-chain (ICV/PIH) state — signing/chain stay merchant-side. We add the mandatory ZATCA headers (Accept-Version: V2, Accept-Language: en, and Clearance-Status: 1 on clearance).
- Reporting vs clearance: report_invoice = simplified invoices (B2C, فاتورة مبسطة), reported after issuing. clear_invoice = standard invoices (B2B, فاتورة ضريبية), cleared/stamped by ZATCA before issuing (returns cleared_invoice).
- Endpoints wrapped: gw-fatoora.zatca.gov.sa/e-invoicing/{developer-portal|simulation|core}/invoices/reporting/single, .../invoices/clearance/single, .../compliance/invoices.

## Tools

- report_invoice: Report a simplified (B2C) tax invoice to ZATCA — { invoiceHash, uuid, invoice(base64 signed UBL) } in, reporting_status REPORTED out (or accepted-with-warnings). Signing stays merchant-side.
- clear_invoice: Clear a standard (B2B) tax invoice through ZATCA — same envelope in, clearance_status CLEARED + cleared_invoice (ZATCA-stamped base64 XML) out. Sent with Clearance-Status: 1.
- check_invoice_compliance: Validate a signed invoice against the ZATCA compliance endpoint WITHOUT reporting/clearing it (onboarding / debugging, no fiscal effect).
- Owner policy guardrails: x-agentpay-max-amount (hard cap on invoice grand total in SAR, read from TaxInclusiveAmount when present), x-agentpay-approval-above (returns an unsigned draft for human review), x-agentpay-allowed-tools (tool allow-list) — set by the human owner in the MCP client config; the agent cannot relax them.

## Safety

Stateless translation layer that forwards the ZATCA submission calls only. ECDSA signing and the ICV/PIH hash-chain stay merchant-side; the CSID token and secret travel per-request in headers and are never stored. This server never stores credentials, invoices, or customer data. Privacy policy: https://inv-sa.wishpool.app/privacy

## Sister servers

Invoices: Poland KSeF https://inv-pl.wishpool.app/mcp, Mexico CFDI 4.0 https://inv-mx.wishpool.app/mcp, Chile DTE https://inv-cl.wishpool.app/mcp, Brazil NF-e https://inv-br.wishpool.app/mcp, Peru CPE https://inv-pe.wishpool.app/mcp, India GST e-invoicing https://inv-in.wishpool.app/mcp. Same stateless BYO pattern, local payments in 81 countries — full list: https://mcp.wishpool.app/llms.txt (Taiwan e-invoice 電子發票 lives in https://mcp.wishpool.app/mcp).