Claude Code plugin

Install the official factuarea-mcp plugin to connect Claude Code to the Factuarea MCP server in one command — the recommended setup.

The fastest way to connect Claude Code to the Factuarea MCP server is the official factuarea-mcp plugin. It registers the server (https://mcp.factuarea.com) and bundles a skill that teaches Claude how to use the tools well — scopes, cursor pagination, the error envelope and test mode — so you don't have to wire anything by hand.

This is the recommended way to connect Claude Code. Prefer to wire the server manually (other clients, headless setups)? See Connecting a client.

Install

Add the marketplace

/plugin marketplace add factuarea/claude-plugins

Install the plugin

/plugin install factuarea-mcp@factuarea

Claude Code installs the plugin and registers the factuarea MCP server.

To pull in later updates, run /plugin marketplace update factuarea.

Connect the server

The plugin declares the server without an auth header, so the recommended path is OAuth — nothing secret is ever pasted into a config file.

Authenticate

/mcp

Pick factuarea, choose Authenticate. Your browser opens the Factuarea consent screen. Dynamic Client Registration and PKCE happen automatically — there's no client id or secret to paste.

Approve

On the consent screen you select the company, the environment (live or test) and the scopes to grant. Sensitive scopes (deletes, invoices:void) are flagged and not pre-checked. Claude Code stores the token and refreshes it transparently.

Use it

Ask Claude to work with your Factuarea data — "list this quarter's unpaid invoices in test mode", "create a draft invoice for Acme S.L.", "check the VeriFactu chain". The skill loads automatically; you can also invoke it explicitly:

/factuarea-mcp:factuarea-mcp

Connect with an API key instead

For headless setups, or when you already have a fact_ key, connect with a static header instead of OAuth:

claude mcp add --transport http factuarea https://mcp.factuarea.com \
  --header "Authorization: Bearer fact_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Use a fact_test_ key to point at the isolated sandbox. The API surface is identical — only the prefix changes the environment. With a key header you do not need the OAuth flow; the key authenticates every request.

What the plugin ships

The MCP server

The factuarea server declaration (https://mcp.factuarea.com, HTTP transport), so Claude can call all the Factuarea tools directly.

A guidance skill

A skill that gives Claude the context to use the tools well — the channel policy, the 15 tool domains and their scopes, UUID v7 identity, cursor pagination, the error envelope and test mode.

The skill knows the channel policy (an API key reaches all 232 tools; OAuth uses the curated 218, never granting verifactu:write, the FacturaE scopes or the GDPR signature-forget operation to third-party apps), how plan/module and feature flags further narrow tools/list, and that state changes are discrete tools (mark_invoice_as_paid, void_invoice, accept_quote…), not a generic change_status.

Building a code integration against the REST API rather than using tools? Use the official SDKs (TypeScript and PHP) or generate a client from the OpenAPI spec.

Troubleshooting

Symptom	Cause	Fix
A tool returns `401`	Not authenticated, or the key/token expired.	Run `/mcp` → factuarea → Authenticate to (re)start OAuth, or check your API-key header.
`insufficient_scope` (`403`)	The credential lacks the tool's required scope.	Re-authenticate and approve the scope, or use a key that has it. Remember `verifactu:write` and the signature-forget tool are API-key only.
A tool you expected isn't listed	`tools/list` is filtered by your scopes and feature flags.	Grant the scope (or use a wider key); confirm the credential's channel can reach it (OAuth excludes the API-key-only tools). This is expected, not a bug.
`addon_not_active` (`-32007`)	The company's developer API add-on is inactive.	Activate it in the dashboard; the whole MCP surface requires it.
`429` with `Retry-After`	A rate-limit bucket was hit.	Wait the `Retry-After` seconds before retrying — don't hammer.
OAuth says the company isn't allowed	The public API is in private beta.	Request access at info@factuarea.com — see Request beta access.

See Errors & rate limits for the full code table.