# MCP de CANGOPAL DeCA

El **MCP (Model Context Protocol)** de DeCA permite que un agente de IA (Claude,
Cursor, pi, un asistente propio) opere una cuenta de DeCA **en lenguaje
natural**: consultar el cupo, dar de alta clientes y direcciones, crear
recogidas, emitir DeCAs, gestionar rutas multiparada y diagnosticar webhooks —
sin escribir código contra la API REST.

Es la **misma API** que la referencia REST de la aplicación: cada herramienta
ejecuta un endpoint de la API v1, con las mismas validaciones, los mismos
límites y el mismo cupo.

- Página del producto: https://deca.cangopal.com/integraciones/mcp
- Referencia REST (requiere sesión): https://app.deca.cangopal.com/docs/api
- Guía del MCP en la aplicación (requiere sesión): https://app.deca.cangopal.com/docs/mcp

## Conexión

| Dato | Valor |
|---|---|
| Endpoint | `https://app.deca.cangopal.com/mcp` |
| Transporte | JSON-RPC 2.0 sobre HTTP (streamable, sin SSE). Un `GET` responde `405 Method Not Allowed`. |
| Autenticación | Cabecera `X-API-Key` con la clave de la API REST. El servidor **no** lee `Authorization`. |
| Protocolo | `2025-06-18` — servidor `deca-mcp 1.0.0` |

## Clientes compatibles

El servidor se autentica con una **cabecera fija** (`X-API-Key`) y no publica endpoints OAuth, así que solo sirven los clientes que permiten enviar cabeceras propias. Guías paso a paso, verificadas contra la documentación oficial de cada fabricante:

| Cliente | Se conecta | Guía |
|---|---|---|
| Claude (app y escritorio) | Sí — conector personalizado, cabeceras fijas («Request headers») | https://deca.cangopal.com/integraciones/mcp/claude |
| Claude Code | Sí — `claude mcp add --transport http … --header` | https://deca.cangopal.com/integraciones/mcp/claude-code |
| Cursor | Sí — `url` + `headers` en `~/.cursor/mcp.json` | https://deca.cangopal.com/integraciones/mcp/cursor |
| Visual Studio Code | Sí — `type: http` + `headers` en `mcp.json` | https://deca.cangopal.com/integraciones/mcp/vscode |
| Codex | Sí — `http_headers` en `~/.codex/config.toml` | https://deca.cangopal.com/integraciones/mcp/codex |
| Microsoft Copilot Studio | Sí — API key en cabecera, con nombre propio | https://deca.cangopal.com/integraciones/mcp/copilot-studio |
| ChatGPT | **No** (a día de hoy) — su MCP autentica con OAuth | https://deca.cangopal.com/integraciones/mcp/chatgpt |

```bash
curl -s https://app.deca.cangopal.com/mcp \
  -H "X-API-Key: TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

La respuesta devuelve el catálogo completo con el `inputSchema` de cada
herramienta: esa descripción es el contrato que lee el agente.

## Requisitos: las tres puertas (y una cuarta para escribir)

1. **Clave de API** — se genera en Mi Cuenta → API y se muestra una sola vez.
2. **Add-on API REST** activo y vigente. Estar en el plan Enterprise no basta
   por sí solo. El add-on cuesta 50 €/mes o 480 €/año, va incluido en
   Enterprise y se contrata sobre cualquier plan base, incluido Free.
3. **Interruptor MCP** de la cuenta, activo por defecto; se puede apagar sin
   revocar la clave.
4. **Permiso `mcp_write`** (escritura), apagado por defecto. Sin él, el agente
   puede leerlo todo —cuenta, expedientes, recogidas, rutas, catálogo,
   webhooks, PDF y QR— pero cualquier escritura devuelve el error `-32603` con
   las instrucciones para activarlo.

## Herramientas (36)

**Lectura**

`consultar_cuenta`, `listar_recogidas`, `listar_expedientes`,
`consultar_expediente`, `consultar_estado_expediente`, `descargar_pdf_deca`,
`obtener_qr_expediente`, `consultar_modificaciones`, `buscar_articulo`,
`listar_catalogo`, `listar_clientes`, `listar_direcciones`, `listar_vehiculos`,
`listar_rutas`, `consultar_ruta`, `listar_webhooks`,
`consultar_entregas_webhook`.

**Escritura** (requieren `mcp_write`)

`crear_recogida_deca`, `completar_expediente`, `emitir_expediente`,
`cambiar_matriculas`, `editar_recogida`, `cancelar_expediente`,
`cancelar_recogida`, `crear_cliente`, `editar_cliente`, `crear_direccion`,
`editar_direccion`, `crear_vehiculo`, `editar_vehiculo`, `crear_articulo`,
`editar_articulo`, `crear_ruta`, `editar_ruta`, `cambiar_matriculas_ruta`,
`reintentar_entrega_webhook`.

`crear_articulo` y `editar_articulo` exigen además el add-on **Soporte ADR**.

## El flujo principal

`crear_recogida_deca` crea recogida, expediente y —con `emit: true`— emite el
DeCA en **una sola llamada**. Es el camino recomendado:

```
consultar_cuenta → crear_cliente → crear_recogida_deca(emit: true)
```

Contrato de emisión: para que `emit:true` funcione, el expediente debe quedar
completo —fecha prevista (`planned_pickup`), origen (el cliente o la dirección
fiscal de la cuenta) y destino (`deca.locations.unloading_place`)—. La matrícula
es diferida (se cierra por el QR del papel) pero puede viajar en
`deca.transport_means.tractor_plate`.

## Cupo, idempotencia y límites

- El **cupo se consume al emitir**, no al crear: un borrador no gasta cupo.
- `emit:true` es **todo-o-nada**: si la emisión falla, el `422` trae
  `details.gaps` con los campos que faltan y **nada se creó**; se corrige y se
  reintenta con la misma `source_reference` (el rollback la libera).
- `source_reference` (recogidas) e `Idempotency-Key` (cabecera) dan reintentos
  seguros contra duplicados.
- **Web y API comparten el contador mensual** del plan. Una ruta multiparada
  consume **una sola unidad**, no una por parada.
- Tope de **20 partidas** por expediente (límite del dominio, no del plan).

## Lo que NO se puede hacer por MCP

| No disponible | Alternativa |
|---|---|
| Crear, rotar o borrar webhooks (el secreto se muestra una sola vez) | Mi Cuenta → Webhooks o la API REST |
| Contactos transportistas de la Libreta | La app web (Libreta) |
| Cambiar de plan, facturación o add-ons | Mi Cuenta → Plan y facturación |
| Importar catálogo desde Excel/CSV | Mi Cuenta → Catálogo (el alta unitaria sí es por MCP) |
| Panel de administración | Panel admin |

## Trampas conocidas

- El **token del QR es el del documento**, no el del portal: en
  `consultar_expediente` viaja anidado en el documento.
- `crear_cliente` espera la dirección **anidada** en `address`.
- El NIF/CIF **se valida con dígito de control**.
- Las direcciones exigen `kind` (`origin` o `destination`).
- Cambiar de transportista en una ruta con DeCA en servicio exige reemisión;
  en caliente solo se pueden corregir matrículas (`cambiar_matriculas_ruta`).

## Soporte

Los errores de la API y del MCP están en español y llevan `request_id`. Si algo
falla, pídeselo al agente y cítalo en tu ticket: support@cangopal.com.