MCP overview
Connect AI agents to Factuarea over the Model Context Protocol — tools across invoicing, catalog, pricing, compliance, time tracking, projects and tasks, automations, webhooks and the account model, with OAuth 2.1 and API-key auth.
The server implements MCP revision 2026-07-28 and also serves clients on 2025-11-25 and 2025-06-18. See protocol and transport for server/discover, headers and pagination; use resources and prompts for fiscal guidance. Its public repository, with the npm package and the registry manifest, is factuarea/factuarea-mcp.
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, over OAuth or an API key, or run the local npm server.
Browse the 668 tools
The full catalog grouped by domain, with the scope each tool requires.
What it can do
The server publishes 668 tools across the public API domains. Nearly everything you can do with the REST API you can do here, in the agent's native tool-calling format; the bulk import of managed accounts, for example, has no tool (see the catalog):
Sales & purchases
Invoices, quotes, pro-forma invoices, delivery notes, transport control documents (DeCA), recurring invoices and expenses — 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.
Accounts & tax IDs
The account model — members and their grants, tax ID transfers, the tax ID portfolio
with its state and readiness to issue, account webhooks and request logs — and, with
the privileged accounts:* scopes, managed accounts. API key only.
Projects & tasks
Projects with their boards and custom fields, tasks with their comments, relations, attachments and logged time, the timer, draft invoices from billable hours, the company members, notifications and the combined agenda.
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 holder automating their own account and tax IDs (like a GitHub PAT) | Up to 668 — you grant any scopes you want, including * (the privileged accounts:* scopes are never covered by *) |
| OAuth 2.1 | Access token issued via consent | Third-party apps acting on a user's behalf | 541 — the curated catalog; 127 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.