MCP overview
Connect AI agents to Factuarea over the Model Context Protocol — 457 tools across invoicing, catalog, pricing, compliance, time tracking, automations and webhooks, with OAuth 2.1 and API-key auth.
The server requires MCP revision 2026-07-28. See protocol and transport for server/discover, mandatory headers and pagination; use resources and prompts for fiscal guidance. Server registration or plugin installation does not guarantee that an older client supports this revision.
The Factuarea MCP server exposes the public API as Model Context Protocol tools, so AI agents (Claude, ChatGPT, Cursor, your own LLM app) can read and operate on your invoicing data through a single, governed endpoint instead of hand-writing HTTP calls. It speaks the Streamable HTTP transport and lives at:
https://mcp.factuarea.comThe canonical endpoint is the subdomain root. The earlier path form
https://mcp.factuarea.com/mcp continues to work as a compatibility alias, so
existing configurations keep connecting.
Every tool maps to the same https://api.factuarea.com/v1 contract documented
in the API Reference: identical resources, the same
opaque id (UUID v7), the same normalized errors, the same multi-tenant
isolation by company. The MCP layer adds discovery (tools/list), per-tool
scope enforcement and a consent flow for third-party apps.
Install the Claude Code plugin
The recommended setup — two commands install the official factuarea-mcp
plugin and connect Claude Code over OAuth.
Connect any client
Wire up Claude Desktop, the MCP Inspector or any MCP client manually, using OAuth or an API key.
Browse the 457 tools
The full catalog grouped by domain, with the scope each tool requires.
What it can do
The server publishes 457 tools across 29 domains. Anything you can do with the REST API you can do here, in the agent's native tool-calling format:
Sales & purchases
Invoices, quotes, pro-forma invoices, delivery notes, recurring invoices and vendor bills — create, update, transition, send and generate PDFs.
Catalog & CRM
Contacts with customer/supplier roles, measured products, presentations, variants, supplier offers, price lists, numbering series and tax rates.
Compliance
VeriFactu (AEAT) records, events and certificates, FACe (FacturaE) submissions, the Modelo 303/347/130 filings, plus webhooks and the event catalog.
Time tracking
Employees, work schedules, the time-clock ledger, monthly closes, absences, presence and public holidays — the RD-ley 8/2019 register.
Automations
The rule engine — the trigger and action catalog, rules and their sealed versions, the dry run, run history with its steps, replay and the monthly quota.
When to use MCP vs REST vs SDKs
The MCP server, the REST API and the official SDKs are three front doors to the same backend. Pick by who (or what) is calling:
| You are building… | Use | Why |
|---|---|---|
| An AI agent / assistant that reasons over your data and acts on it | MCP server | Tools are self-describing; the model discovers and calls them without you wiring each endpoint. Scopes and consent are enforced per call. |
| A backend service, cron job or integration with fixed logic | REST API | Deterministic, no model in the loop, full control over requests and retries. |
| A typed client in your app (TypeScript or PHP) | Official SDKs | @factuarea/sdk and factuarea/factuarea-php wrap the REST API with types, retries and idempotency helpers. |
The three surfaces share the same identifiers, error envelope and scopes, so you can mix them: prototype a flow with an agent over MCP, then harden the critical path as a REST or SDK integration.
Two ways to authenticate
The same /mcp endpoint accepts two kinds of credential, for two different
audiences:
| Channel | Credential | For | Reachable tools |
|---|---|---|---|
| API key | fact_live_… / fact_test_… Bearer token | The account owner automating their own company (like a GitHub PAT) | Up to 457 — you grant any scopes you want, including * |
| OAuth 2.1 | Access token issued via consent | Third-party apps acting on a user's behalf | 368 — the curated catalog; 89 owner-only tools (including payments, account management and privileged workforce writes) require an API key |
See Connecting a client for the full channel policy, and Scopes & permissions for the scope catalog.
Build in test mode first
Just like the REST API, a fact_test_ key — or an OAuth consent with the Test
environment selected — operates on an isolated sandbox company with external
effects switched off (no AEAT transmission, no real emails, no outbound
webhooks). Build and validate against test, then switch to live. See
Test mode.
The MCP server is included in every Factuarea plan, alongside the rest of the public API. Create an API key from Dashboard → Developers → API Keys (or connect via OAuth) and start calling tools.