# Servidor MCP

> Connecta Claude, ChatGPT, Codex, Cursor o qualsevol assistent compatible amb MCP al teu compte de FacturaDirecta amb una sola URL. Consulta factures, despeses i comptabilitat en llenguatge natural.


El servidor MCP de FacturaDirecta connecta el teu assistent d'IA amb el teu compte. Un cop connectat, li pots preguntar per les teves factures, pressupostos, despeses, contactes, productes, comptabilitat o impostos en llenguatge natural, i ell consulta les teves dades reals per respondre't. També li pots demanar que creï factures, registri cobraments o enviï documents: t'ensenya què farà i et demana confirmació abans.

MCP (Model Context Protocol) és l'estàndard obert amb què els assistents d'IA es connecten a altres aplicacions. El nostre servidor és remot: no cal instal·lar res.

## Abans de començar

- Un compte de FacturaDirecta. Serveix qualsevol pla, també el Gratis.
- Un assistent compatible amb servidors MCP remots: Claude, ChatGPT, Codex, Cursor, VS Code i molts altres.
- Res més. No calen API keys ni client ID: inicies sessió amb el teu usuari de FacturaDirecta i tries quins permisos dones.

## Connecta el teu assistent

Tots els clients fan servir la mateixa URL: `https://mcp.facturadirecta.com`.

### Claude

A claude.ai o a l'aplicació d'escriptori:

1. Fes servir el botó *Afegir a Claude* d'aquesta pàgina, o obre els connectors de Claude (*Customize → Connectors* a la interfície en anglès), prem **+** i tria afegir un connector personalitzat.
2. Enganxa la URL `https://mcp.facturadirecta.com`. No cal omplir client ID ni secret: deixa l'autenticació que proposa Claude.
3. Afegeix el connector i connecta'l. FacturaDirecta et mostra quina aplicació demana accés i amb quins permisos.
4. Inicia sessió amb el teu usuari de FacturaDirecta, tria les empreses i els permisos, i autoritza l'accés.

Als plans Team i Enterprise de Claude, el connector l'afegeix un propietari a la configuració de l'organització; després cada persona el connecta amb el seu propi usuari. El pla Free de Claude admet un sol connector personalitzat.

### Claude Code

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

Després, dins de Claude Code, escriu `/mcp`, tria `facturadirecta` i inicia sessió.

### ChatGPT

1. Al web de ChatGPT, obre la pàgina de plugins (`chatgpt.com/plugins`), prem **+** i tria afegir un servidor MCP personalitzat.
2. Enganxa la URL `https://mcp.facturadirecta.com` i tria OAuth com a autenticació.
3. Accepta l'avís sobre els servidors personalitzats, crea el plugin, inicia sessió amb el teu usuari de FacturaDirecta i autoritza l'accés.

Si ChatGPT no t'ofereix l'opció, pot ser que abans hagis d'activar el mode desenvolupador a la seva configuració.

Disponible als plans de ChatGPT que permeten connectors personalitzats (Plus, Pro, Business, Enterprise i Edu).

### Codex

Codex CLI, l'extensió d'IDE i l'aplicació d'escriptori de ChatGPT comparteixen configuració:

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

### Cursor, VS Code i altres clients

Afegeix un servidor MCP remot amb la URL. El client es registra sol i et demana iniciar sessió. A Cursor (`~/.cursor/mcp.json`):

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

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

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

## Tu decideixes què pot fer

- **Actua amb el teu usuari.** L'assistent veu les empreses i les dades a què tu tens accés a FacturaDirecta, mai més.
- **Permisos explícits.** En connectar, FacturaDirecta t'ensenya quina aplicació demana accés, on torna l'autorització i quins permisos sol·licita.
- **Consulta o modificació, sempre declarat.** Cada eina indica si només consulta dades o si les pot canviar. Els assistents et demanen confirmació abans de fer servir les que modifiquen alguna cosa.
- **Diverses empreses.** Si treballes amb més d'una, l'assistent et preguntarà amb quina fer-ho; el servidor no guarda cap empresa activa.
- **Desconnexió.** A **Aplicacions connectades**, des del menú del teu perfil a FacturaDirecta, li retires l'accés al moment. També pots treure el connector a la configuració del teu assistent.

## Tractament de dades

- El servidor no guarda les teves dades: consulta FacturaDirecta en el moment i torna el resultat al teu assistent.
- No llegeix les teves converses: només rep els paràmetres de cada consulta.
- Per seguretat registrem quina eina es fa servir i els seus filtres (dates, estats, paginació). Mai registrem les teves credencials, textos lliures ni imports.
- Més detalls a la [política de privacitat](https://www.facturadirecta.com/ca/legal/privacidad/).

## Problemes freqüents

**L'assistent no veu cap eina.** Comprova que vas completar l'inici de sessió i vas autoritzar l'accés. Si no, desconnecta el connector i torna'l a connectar.

**Treballa amb l'empresa que no és.** Digues-li a la conversa amb quina empresa vols treballar; també li pots preguntar quines empreses veu.

**El meu client només admet tokens fixos.** Alguns diàlegs de "MCP personalitzat" només accepten capçaleres o tokens estàtics i no OAuth. En aquest cas fes servir la línia d'ordres del client (per exemple `codex mcp add`) o la [CLI de FacturaDirecta](https://www.facturadirecta.com/ca/desarrolladores/cli/) amb una API key.

## Detalls tècnics

- **URL:** `https://mcp.facturadirecta.com` (també respon a `/mcp`).
- **Transport:** Streamable HTTP sense estat. Compatible amb l'especificació MCP 2026-07-28 i amb els clients que encara fan servir les versions de 2025.
- **Autorització:** OAuth 2.1 amb PKCE S256, registre dinàmic de clients i documents de metadades de client (CIMD). Metadades del recurs a [`/.well-known/oauth-protected-resource`](https://mcp.facturadirecta.com/.well-known/oauth-protected-resource).
- **Catàleg en JSON:** [`https://mcp.facturadirecta.com/tools.json`](https://mcp.facturadirecta.com/tools.json), sense autenticació: cada eina amb el seu resum, el seu estat, els seus permisos i el seu esquema d'entrada.
- **Eines:** una de consulta per àrea (factures, pressupostos, compres, bancs, impostos…) i una d'escriptura en les que admeten canvis, més la cerca, la consulta analítica, la lectura de documents i la pujada de fitxers. Cada eina d'àrea exposa les seves accions, cadascuna amb la seva operació de l'API: consulta la [referència d'eines](https://www.facturadirecta.com/desarrolladores/mcp/herramientas/) (en castellà).