# MCP server

> Connect Claude, ChatGPT, Codex, Cursor or any MCP-compatible assistant to your FacturaDirecta account with a single URL. Query invoices, expenses and accounting in plain language.


The FacturaDirecta MCP server connects your AI assistant to your account. Once connected, you can ask it about your invoices, estimates, expenses, contacts, products, accounting or taxes in plain language, and it queries your real data to answer. You can also ask it to create invoices, record payments or send documents: it shows you what it is about to do and asks for your confirmation first.

MCP (Model Context Protocol) is the open standard that AI assistants use to connect to other applications. Our server is remote: there is nothing to install.

## Before you start

- A FacturaDirecta account. Any plan works, including Free.
- An assistant that supports remote MCP servers: Claude, ChatGPT, Codex, Cursor, VS Code and many others.
- Nothing else. No API keys or client IDs: you sign in with your FacturaDirecta user and choose which permissions to grant.

## Connect your assistant

Every client uses the same URL: `https://mcp.facturadirecta.com`.

### Claude

On claude.ai or the desktop app:

1. Use the *Add to Claude* button on this page, or open Claude's connectors (**Customize → Connectors**), click **+ Add** and choose **Add custom connector**.
2. Paste the URL `https://mcp.facturadirecta.com`. There is no client ID or secret to fill in: keep the authentication Claude suggests.
3. Add the connector and connect it. FacturaDirecta shows you which application is requesting access and with which permissions.
4. Sign in with your FacturaDirecta user, choose the companies and permissions, and authorise access.

On Claude Team and Enterprise plans, an organisation owner adds the connector in **Organization settings → Connectors**; then each person connects their own user. Claude's Free plan allows one custom connector.

### Claude Code

```shell
claude mcp add --transport http facturadirecta https://mcp.facturadirecta.com
```

Then, inside Claude Code, type `/mcp`, choose `facturadirecta` and sign in.

### ChatGPT

1. On ChatGPT on the web, open the plugins page (`chatgpt.com/plugins`), click **+** and choose **Add custom MCP server**.
2. Paste the URL `https://mcp.facturadirecta.com` and choose OAuth as the authentication.
3. Accept the warning about custom servers, select **Create as a plugin**, sign in with your FacturaDirecta user and authorise access.

If ChatGPT doesn't offer the option, you may need to turn on developer mode in its settings first.

Available on the ChatGPT plans that allow custom connectors (Plus, Pro, Business, Enterprise and Edu).

### Codex

Codex CLI, the IDE extension and the ChatGPT desktop app share their configuration:

```shell
codex mcp add facturadirecta --url https://mcp.facturadirecta.com
codex mcp login facturadirecta
```

### Cursor, VS Code and other clients

Add a remote MCP server with the URL. The client registers itself and asks you to sign in. In Cursor (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "facturadirecta": { "url": "https://mcp.facturadirecta.com" }
  }
}
```

In VS Code (`.vscode/mcp.json`):

```json
{
  "servers": {
    "facturadirecta": { "type": "http", "url": "https://mcp.facturadirecta.com" }
  }
}
```

## You decide what it can do

- **It acts as you.** The assistant sees the companies and data you have access to in FacturaDirecta, never more.
- **Explicit permissions.** When you connect, FacturaDirecta shows you which application is requesting access, where the authorisation returns to and which permissions it asks for.
- **Read or write, always declared.** Every tool states whether it only reads data or can change it. Assistants ask for your confirmation before using the ones that change something.
- **Several companies.** If you work with more than one, the assistant will ask which one to use; the server does not keep an active company.
- **Disconnecting.** In **Connected apps**, from your profile menu in FacturaDirecta, you remove its access instantly. You can also remove the connector in your assistant's settings.

## Data handling

- The server does not store your data: it queries FacturaDirecta on the spot and returns the result to your assistant.
- It does not read your conversations: it only receives the parameters of each query.
- For security we log which tool is used and its filters (dates, states, pagination). We never log your credentials, free text or amounts.
- More details in the [privacy policy](https://www.facturadirecta.com/en/legal/privacidad/).

## Troubleshooting

**The assistant does not see any tools.** Check that you completed the sign-in and authorised access. If not, disconnect the connector and connect it again.

**It works with the wrong company.** Tell it in the conversation which company you want to work with; you can also ask it which companies it can see.

**My client only accepts static tokens.** Some "custom MCP" dialogs only accept headers or static tokens and not OAuth. In that case use the client's command line (for example `codex mcp add`) or the [FacturaDirecta CLI](https://www.facturadirecta.com/en/desarrolladores/cli/) with an API key.

## Technical details

- **URL:** `https://mcp.facturadirecta.com` (also answers on `/mcp`).
- **Transport:** stateless Streamable HTTP. Compatible with the MCP 2026-07-28 specification and with clients that still use the 2025 versions.
- **Authorization:** OAuth 2.1 with PKCE S256, dynamic client registration and client ID metadata documents (CIMD). Resource metadata at [`/.well-known/oauth-protected-resource`](https://mcp.facturadirecta.com/.well-known/oauth-protected-resource).
- **JSON catalog:** [`https://mcp.facturadirecta.com/tools.json`](https://mcp.facturadirecta.com/tools.json), no authentication: every tool with its summary, status, scopes and input schema.
- **Tools:** one for reading per area (invoices, estimates, purchases, banks, taxes…) and one for writing where changes are allowed, plus search, analytical queries, document reading and file upload. Each area tool exposes its actions, each with its API operation: see the [tools reference](https://www.facturadirecta.com/desarrolladores/mcp/herramientas/) (in Spanish).