MCP overview
Connect AI agents to Factuarea over the Model Context Protocol — 391 tools across invoicing, catalog, compliance, time tracking and webhooks, with OAuth 2.1 and API-key auth.
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 391 tools
The full catalog grouped by domain, with the scope each tool requires.
What it can do
The server publishes 391 tools across 27 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
Clients, suppliers, products, numbering series and tax rates.
Compliance
VeriFactu (AEAT) records, events and certificates, FACe (FacturaE) submissions, 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.
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 391 — you grant any scopes you want, including * |
| OAuth 2.1 | Access token issued via consent | Third-party apps acting on a user's behalf | 305 — a curated catalog that excludes VeriFactu writes, GDPR erasure, FacturaE (FACe), Payments & gateways, and the gestoría and account-write tools |
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.