# Servidor MCP

Conecta tu asistente de IA (Claude, Cursor, VS Code…) a la API de Ticketbai WS con el [Model Context Protocol](https://modelcontextprotocol.io/). Cada método de la API es una herramienta: emite, consulta y anula facturas TicketBAI y Verifactu desde el chat.

## Direcciones

| Entorno | URL del servidor MCP |
| --- | --- |
| Pruebas | `https://api-test.ticketbaiws.eus/mcp-api` |
| Producción | `https://api.ticketbaiws.eus/mcp-api` |

**Gestión de empresas y licencias:** estos métodos se autentican con el **token de desarrollador de tu cuenta de cliente** (no con el de una empresa), así que tienen su propio servidor: `https://api.ticketbaiws.eus/mcp-api/cuenta`, con el token de desarrollador y el NIF de la cuenta en las mismas cabeceras. Añádelo como un segundo conector.

**Empieza siempre en pruebas.** En producción las facturas tienen validez fiscal y se envían a Hacienda: pide al asistente que te confirme cada factura antes de emitirla.

## Conectar tu asistente

**Solo necesitas la URL.** Al añadir el conector, tu asistente te abre una ventana de Ticketbai WS: inicias sesión con tu cuenta, eliges la empresa y das acceso. No tienes que copiar tokens ni configurar cabeceras.

### Claude (claude.ai y Claude Desktop)

1. En **Ajustes → Conectores**, añade un conector personalizado con la URL del servidor MCP.
2. Pulsa **Conectar**, inicia sesión con tu cuenta de Ticketbai WS y elige la empresa.

### ChatGPT

1. Añade un conector personalizado con la URL del servidor MCP (según tu plan, puede que tengas que activar el modo desarrollador de los conectores).
2. Elige autenticación **OAuth**, inicia sesión con tu cuenta de Ticketbai WS y elige la empresa.

### Claude Code

```
claude mcp add --transport http ticketbaiws-test https://api-test.ticketbaiws.eus/mcp-api
```

Después, dentro de Claude Code, escribe `/mcp` y elige **Authenticate** para iniciar sesión.

### Cursor, VS Code y otros clientes

Añade la URL del servidor MCP. Si tu cliente admite OAuth, te pedirá iniciar sesión; si no, usa las cabeceras (abajo).

**Una conexión por empresa y entorno.** El acceso que das vale solo para la empresa que eliges y solo para el entorno de la URL (pruebas o producción). Si gestionas varias empresas, añade un conector por empresa. Para la gestión de empresas y licencias usa `https://api.ticketbaiws.eus/mcp-api/cuenta` e inicia sesión con tu cuenta de cliente.

### Alternativa: cabeceras con tu token

Para clientes sin OAuth o para automatizaciones, el servidor sigue aceptando el token de la empresa en cabeceras HTTP, como la API REST: `Token` y `Nif`. Si tu cliente solo deja elegir cabeceras de una lista, usa `X-API-Token` y `X-Client-ID`; si solo permite `Authorization`, envía `Authorization: Bearer TU_NIF:TU_TOKEN`.

```
claude mcp add --transport http ticketbaiws-test https://api-test.ticketbaiws.eus/mcp-api \
  --header "Token: TU_TOKEN_DE_TEST" \
  --header "Nif: TU_NIF"
```

El servidor no guarda tu token ni accede a nada que no puedas hacer con la API: cada herramienta hace la misma llamada REST que harías tú, con los mismos límites de uso.

### Ejemplos de lo que puedes pedir

Mira conversaciones completas, con las herramientas que usa el asistente, en los [casos de uso del servidor MCP](https://ticketbaiws.eus/es/desarrolladores/casos-de-uso-mcp/).

- «Emite un ticket de 12,10 € IVA incluido, serie T, con un café y un bocadillo.»
- «¿Cómo ha terminado en Hacienda la factura A-2026-0042?»
- «Lista las facturas de ayer que tengan errores.»
- «Anula la factura T-118 y dime la huella de la anulación.»

## Herramientas

Son los métodos de la [documentación del API](https://ticketbaiws.eus/es/documentacion-api/), con los mismos parámetros. Algunos métodos de gestión solo existen en producción.

### Facturas TicketBAI / Verifactu

- `ticketbai_post`: Nueva factura TicketBAI / Verifactu (POST /tbai/)
- `ticketbai_get`: Consulta factura TicketBAI (GET /tbai/)
- `ticketbai_del`: Anular factura TicketBAI (DELETE /tbai/)
- `tbai_completar_post`: TicketBAI - Completar factura simplificada (POST /tbai-completar/)
- `ticketbai_list_get`: Listado facturas TicketBAI (GET /tbai-list/)
- `ticketbai_xml_get`: Descarga XML TicketBAI (GET /tbai-xml/)
- `facturae_get`: Descarga en formato FacturaE (GET /facturae/, solo producción)
- `tbai_pdf_get`: Descarga en formato PDF (GET /tbai-pdf/)
- `status_get`: Estado del sistema (GET /status/)
- `reset_tbai_put`: Reset envío TBAI (PUT /reset-tbai/)
- `validar_nif_post`: Validar NIF en la AEAT (POST /validar-nif/, solo producción)
- `validar_nif_vies_post`: Validar NIF en el VIES (POST /validar-nif-vies/, solo producción)

### Documento de representación (Verifactu, Bizkaia, Gipuzkoa)

- `doc_representante_modelo_get`: Documento de representación - Descargar modelo (GET /doc-representante/modelo/)
- `doc_representante_post`: Documento de representación - Enviar documento (POST /doc-representante/)
- `doc_representante_get`: Documento de representación - Descargar documento cargado (GET /doc-representante/)
- `doc_representante_delete`: Documento de representación - Revocar documento cargado (DELETE /doc-representante/)

### Batuz Bizkaia (LROE)

- `epigrafes_get`: Listado epígrafes (GET /epigrafes/, solo producción)
- `lroe_recibidas_post`: LROE - Envío de facturas recibidas (POST /lroe-recibidas/)
- `lroe_recibidas_put`: LROE - Modificar facturas recibidas (PUT /lroe-recibidas/)
- `lroe_recibidas_get`: LROE - Consulta de facturas recibidas (GET /lroe-recibidas/)
- `lroe_recibidas_del`: LROE - Anular facturas recibidas (DELETE /lroe-recibidas/)
- `lroe_gastos_sin_factura_post`: LROE - Envío de gastos sin factura (POST /lroe-gastos-sinfactura/)
- `lroe_gastos_sin_factura_put`: LROE - Modificar gastos sin factura (PUT /lroe-gastos-sinfactura/)
- `lroe_gastos_sin_factura_get`: LROE - Consulta de gastos sin factura (GET /lroe-gastos-sinfactura/)
- `lroe_gastos_sin_factura_del`: LROE - Anular gastos sin factura (DELETE /lroe-gastos-sinfactura/)
- `lroe_critcaja_cobros_post`: LROE - Criterio de caja - COBROS - Envío de cobros (POST /lroe-critcaja-cobros/)
- `lroe_critcaja_cobros_put`: LROE - Criterio de caja - COBROS - Modificar cobros (PUT /lroe-critcaja-cobros/)
- `lroe_critcaja_cobros_get`: LROE - Criterio de caja - COBROS - Consulta de cobros (GET /lroe-critcaja-cobros/)
- `lroe_critcaja_cobros_del`: LROE - Criterio de caja - COBROS - Anulación de cobros (DELETE /lroe-critcaja-cobros/)
- `lroe_critcaja_pagos_post`: LROE - Criterio de caja - PAGOS - Envío de pagos (POST /lroe-critcaja-pagos/)
- `lroe_critcaja_pagos_put`: LROE - Criterio de caja - PAGOS - Modificar pagos (PUT /lroe-critcaja-pagos/)
- `lroe_critcaja_pagos_get`: LROE - Criterio de caja - PAGOS - Consulta de pagos (GET /lroe-critcaja-pagos/)
- `lroe_critcaja_pagos_del`: LROE - Criterio de caja - PAGOS - Anulación de pagos (DELETE /lroe-critcaja-pagos/)

### Webhooks, empresas y licencias

- `webhooks_post`: Webhooks - Nuevo webhook (POST /webhooks/)
- `webhooks_get`: Webhooks - Consultar webhooks (GET /webhooks/)
- `webhooks_put`: Webhooks - Modificar webhook (PUT /webhooks/{codigo_webhook}/)
- `empresas_post`: Nueva empresa (POST /empresas/, servidor de cuenta)
- `empresas_get`: Listado empresas (GET /empresas/, servidor de cuenta)
- `licencias_post`: Nueva licencia (POST /licencias/, servidor de cuenta)
- `licencias_get`: Consulta licencias (GET /licencias/, servidor de cuenta)
- `empresas_put`: Editar datos empresa (PUT /empresas/{nif}/, servidor de cuenta)

### Factura electrónica B2B (SPFE)

- `spfe_estados_post`: SPFE - Comunicar pago, cobro, rechazo o impago (POST /spfe-estados/)
- `spfe_estados_get`: SPFE - Consulta de pagos, cobros, rechazos e impagos (GET /spfe-estados/)
- `spfe_recibidas_get`: SPFE - Facturas recibidas (GET /spfe-recibidas/)

## Buenas prácticas

- Si alguna herramienta devuelve `TOKEN error`, pide al asistente que use `comprobar_conexion`: te dirá el entorno, qué cabeceras han llegado, el NIF recibido y los 4 últimos caracteres del token.
- El envío a Hacienda es asíncrono: después de emitir, el asistente debe consultar el estado con `ticketbai_get` (o puedes configurar un webhook).
- Los importes de las líneas van sin IVA y las fechas en formato dd/mm/yyyy. Los [ejemplos](https://ticketbaiws.eus/es/desarrolladores/ejemplos/) sirven también como referencia para el asistente.
- Si recibes HTTP 429, se ha superado el límite de peticiones: espera antes de reintentar.
- La especificación completa está en [openapi.json](https://api.ticketbaiws.eus/openapi.json).

Fuente: https://ticketbaiws.eus/es/desarrolladores/mcp/
