WonderFatoora WonderFatoora
العربية Log in Start now
Developers

AI agents and MCP

Wonder Fatoora MCP lets AI agents read a company's invoices and customers and prepare drafts with the company's approval, while issuing always waits for a person to approve it in WonderFatoora.

What it is

Wonder Fatoora MCP is a remote server for the Model Context Protocol (MCP), the open standard that AI assistants and agent frameworks use to call tools. An agent connected to a company can use these tools:

Tool Scope What it does
get_company_profile, get_integration_status companies:read Read the company profile and whether it is ready to issue.
search_customers, get_customer customers:read Find customers.
search_products, get_product products:read Find products and services, with their prices and VAT rates.
list_invoices, get_invoice, get_invoice_status, list_invoice_notes, get_note, list_invoice_payments invoices:read Read invoices, credit and debit notes, their ZATCA status and the payments recorded on them.
get_document_download_link invoices:download A PDF link valid for five minutes, never the file inline.
create_customer, update_customer customers:write Maintain customers.
create_product, update_product products:write Maintain products and services.
create_invoice_draft, validate_invoice_draft, create_note_draft invoices:draft Prepare drafts and check whether they can be issued. Drafting never issues.
record_payment payments:write and invoices:read Record a customer payment against an issued invoice, up to the balance still owed.
list_projects (companies:read), get_project_summary (invoices:read), set_invoice_project (invoices:draft) see each tool Read projects and each project's sales, costs and profit; put an invoice on a project. The project is an internal tag: it changes nothing in the invoice or what ZATCA receives.
issue_invoice, issue_note, create_credit_note, create_debit_note invoices:issue Irreversible. Off by default, and every call waits for a person's approval.

Each tool also needs the permission of the person who connected the app, as on the REST API, and answers with the same fields. Write tools accept client_request_id: a retry with the same id returns the first answer instead of doing the work twice.

REST API or MCP?

REST API MCP
Who calls it Your own code: a store, a booking system, a SaaS backend An AI assistant or agent framework that speaks the Model Context Protocol
How it signs in An API key of one company, or an OAuth connection An OAuth connection a company admin approved, or an API key created for AI agents
What it can do Everything its scopes allow, including issuing with invoices:issue Read data and prepare drafts; the issuing tools run only on an OAuth connection where a company admin enabled them, never with an API key
Issuing an invoice Immediate when the key holds invoices:issue Waits for a person to approve exactly that document inside WonderFatoora
Best for Automated invoicing at volume Assistants that help a person prepare, check and find invoices

Both reach the same company data under the same permissions, and an invoice issued either way is numbered, signed and sent to ZATCA in exactly the same way. Calling an MCP tool never, by itself, issues a final tax invoice.

Connect

  • Endpoint: POST https://fatoora.tw.sa/mcp, Streamable HTTP with JSON answers. GET and DELETE answer 405: there is no event stream and no session.
  • Protocol versions: 2026-07-28 (send MCP-Protocol-Version, _meta with the version and the client's capabilities, and Mcp-Method and Mcp-Name), and 2025-11-25 and 2025-06-18 (start with initialize; no session id is issued).
  • Authorization: OAuth 2.1 with PKCE. Register your client under Settings → Developers → My apps and ask for resource=https://fatoora.tw.sa/mcp. The server's metadata is at /.well-known/oauth-protected-resource/mcp. Without a token the server answers 401 with WWW-Authenticate pointing at that document; a missing scope answers 403 insufficient_scope.
  • Clients that register themselves (RFC 7591), such as an AI assistant connector: when self-registration is switched on, the authorization server metadata lists registration_endpoint (POST /oauth/register). A self-registered app has no company behind it: it connects live companies only, a limited number of them, and only after a person who manages the company allows it on the consent screen, which says the app registered itself.
  • A token issued for the REST API is refused here, and an MCP token is refused by the REST API. An API key works only if it was created with Allow use by AI agents (MCP), for clients that can send only a fixed header. An expired key answers 401 with error.data.code token_expired and error.data.renew_url.
  • Browser clients must come from an allowed origin: a request carrying any other Origin is refused.

How approval works

  1. A company admin turns a tool that issues on for your app under Settings → Developers → Connected apps. Until then the tool answers tool_disabled.
  2. The agent calls it. WonderFatoora checks the draft and records a pending approval tied to that company, connection, person and document as stored. Nothing is issued: the answer is approval_required with a link and a confirmation_id. A 2026-07-28 client that supports URL elicitation is given the link that way.
  3. The person the app acts as opens the link, confirms their password, sees the document as WonderFatoora stores it, and approves or denies it. Waiting requests are also listed under Settings → Developers → Approvals.
  4. The agent calls the same tool again with the same arguments and the confirmation_id. It runs once, within 15 minutes, and only if the document has not changed since it was approved.

Safety model

  • Nothing the agent sends counts as approval. There is no approval tool and no argument that approves; only a signed-in person in WonderFatoora can.
  • One company per connection. The company comes from the connection, never from tool arguments.
  • Your records are data. Text inside invoices and customer records is returned as data and never treated as instructions.
  • No token passthrough. The agent's token is used only by WonderFatoora and never forwarded anywhere else.
  • Logged and limited. Every call is logged with the tool's name, never its arguments, and rate limited per connection.
  • Sandbox results are marked. In a sandbox company every result says SANDBOX; nothing there is a tax invoice.
WonderFatoora is independent. It is not affiliated with ZATCA or with any AI provider.

Related

Ready to build?

API access is part of the Business and Enterprise plans. Create a key in Settings → API keys and make your first call in minutes.

Get an API key Quick start Talk to us