Claude Code plugin

Two official plugins in one marketplace — factuarea-mcp connects Claude Code to the Factuarea MCP server, and factuarea-api ships five skills for building the integration itself.

The Factuarea marketplace publishes two Claude Code plugins, for two different jobs. factuarea-mcp is the fastest way to connect Claude Code to the Factuarea MCP server: 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. factuarea-api serves the other audience, the developer who writes the integration code, and deliberately declares no MCP server at all.

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 you need

/plugin install factuarea-mcp@factuarea

Claude Code installs the plugin and registers the factuarea MCP server. Writing integration code too? Add factuarea-api as well — the two are complementary.

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 `factuarea-mcp` 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 tool domains and their scopes, UUID v7 identity, cursor pagination, the error envelope and test mode.

The factuarea-api plugin

A separate, lighter install for writing the integration itself — five skills, and no MCP server declaration, so no OAuth and no tools loaded.

The guidance skill knows the channel policy (an API key reaches all 391 tools; OAuth uses the curated 305, never granting verifactu:write, the FacturaE, Payments or gestoría/account-write 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 the integration: the `factuarea-api` plugin

The plugin above is for operating your account through MCP tools. A second plugin covers the opposite job — writing the code that calls the REST API from your own backend:

/plugin install factuarea-api@factuarea

It declares no MCP server, which is what makes it cheap to keep installed: no OAuth consent, and no tool surface loaded into the session. Its five skills load from the task at hand and lean on the official SDKs, the live spec and these docs.

Skill	Loads when the task is…	What it covers
`factuarea-api`	Starting out, or asking what the API supports, how auth works, or what the docs say	The entry point: ten golden rules, the two accepted auth headers and the prefix that picks the environment, searching these docs locally with `factuarea docs`, and recipes that route to the four skills below
`factuarea-implement`	Wiring the client and making the first calls	Choosing between the TypeScript and PHP SDK, resolving the key from the environment, the `data` envelope, cursor pagination, `Idempotency-Key` on writes, and starting in the sandbox
`factuarea-webhooks`	Writing or fixing the endpoint that receives deliveries	Raw-body HMAC verification of `Factuarea-Signature`, constant-time comparison, dedup by `Factuarea-Event-Id`, a fast 2xx with the heavy work deferred, the rotation grace window, and local testing with `factuarea listen`
`factuarea-audit`	Reviewing an integration that already exists	Six rule families — signature verification, idempotency on writes, API-key exposure, error handling by `code`, rate limits, document lifecycle — reporting each finding with a severity, a `file:line` and the concrete fix
`factuarea-upgrade`	Realigning after a contract or SDK change	Drift between the code and the live spec, the pinned SDK version against the latest published one, and a report that separates breaking changes from additive ones, in the order to apply them

The two plugins are complementary, not alternatives. factuarea-mcp reads and acts on your data through tools; factuarea-api never calls the API on your behalf — it writes and reviews the code that does. Teams building an integration usually install both. You can also generate a client yourself 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 has no active Factuarea plan that includes API access (e.g. an expired trial).	Subscribe to or renew a plan from the dashboard; the whole MCP surface requires an active plan.
`429` with `Retry-After`	A rate-limit bucket was hit.	Wait the `Retry-After` seconds before retrying — don't hammer.

See Errors & rate limits for the full code table.