# Tupana — Guía de conexión al servidor MCP

> Tupana es una plataforma chilena de facturación electrónica y contabilidad. Emite documentos tributarios electrónicos (DTE) integrada con el SII (Servicio de Impuestos Internos), sincroniza libros de compra y venta, concilia el banco y lleva la contabilidad.

Esta guía explica cómo conectar un asistente de IA a Tupana mediante su servidor MCP (Model Context Protocol). Con la conexión, el asistente consulta y opera sobre las empresas del usuario en su nombre.

Esta guía no describe la API REST campo por campo. Para integraciones de sistema a sistema, ver la sección "Cuándo usar la API REST en vez del MCP".

Versión para personas: https://docs.tupana.ai/user-guide/mcp

---

## 1. Datos de conexión

| Dato | Valor |
|---|---|
| URL del servidor | `https://mcp.tupana.ai/mcp` |
| Transporte | Streamable HTTP (MCP remoto) |
| Autenticación | OAuth 2.1 con PKCE y registro dinámico de clientes |
| API key o client ID | No se necesitan |
| Inicio de sesión | Cuenta Tupana: email y clave, o Google |
| Configuración adicional | Ninguna |

Sin sesión iniciada, el servidor responde `401` y el cliente MCP abre el flujo de inicio de sesión de Tupana en el navegador. Después de iniciar sesión, el cliente guarda el token y lo renueva solo.

---

## 2. Cómo conectarse, por cliente

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

1. Abre Configuración → Conectores.
2. Elige "Agregar conector personalizado".
3. Pega la URL `https://mcp.tupana.ai/mcp` y guarda.
4. Al conectar, inicia sesión con tu cuenta Tupana.

### Claude Code

```bash
claude mcp add --transport http tupana https://mcp.tupana.ai/mcp
```

Luego, dentro de Claude Code, ejecuta `/mcp` y elige `tupana` para iniciar sesión.

### Cursor

Agrega el servidor en `mcp.json` (global en `~/.cursor/mcp.json` o por proyecto en `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "tupana": {
      "url": "https://mcp.tupana.ai/mcp"
    }
  }
}
```

Cursor pedirá iniciar sesión con tu cuenta Tupana la primera vez que use el servidor.

### ChatGPT y otros clientes MCP remotos

Cualquier cliente que soporte servidores MCP remotos con OAuth sirve:

1. Busca en la configuración del cliente la opción para agregar un servidor MCP remoto (a veces llamado conector o integración).
2. Indica la URL `https://mcp.tupana.ai/mcp`.
3. Si el cliente pregunta por el tipo de autenticación, elige OAuth. No hay client ID ni secreto que ingresar: el registro del cliente es automático.
4. Inicia sesión con tu cuenta Tupana cuando el cliente lo pida.

Los nombres de los menús cambian según el cliente y su versión; consulta su documentación si no encuentras la opción.

---

## 3. Permisos y seguridad

- El asistente actúa con los permisos del usuario que inició sesión: sólo ve y opera sobre las empresas a las que ese usuario pertenece en Tupana.
- Las acciones que emiten documentos al SII o envían correos piden confirmación explícita en la conversación antes de ejecutarse. Sin confirmación, un documento queda como borrador.
- Para revocar el acceso, desconecta el servidor en el cliente.

---

## 4. Qué se puede hacer

Las herramientas se describen solas al conectarse, así que la lista siempre está al día. Para conocerlas:

- `list_capabilities`: lista lo que el servidor puede hacer, por categoría.
- `how_to`: paso a paso para una tarea (por ejemplo, emitir una factura o una nota de crédito).

Categorías principales:

- **Documentos:** consultar y buscar documentos emitidos y recibidos; emitir facturas afectas (33) y exentas (34), notas de crédito (61), facturas de compra (46) y facturas de exportación (110); crear facturas programadas o recurrentes; obtener el PDF.
- **Clientes y proveedores:** datos de una empresa por RUT, cuentas por cobrar y por pagar.
- **Libros del SII y F29:** libros de compra y venta, resumen de IVA y del F29.
- **Banco y conciliación:** movimientos bancarios, sugerencias de conciliación y conciliación de movimientos.
- **Contabilidad:** asientos, libro mayor, balance y estado de resultados.
- **Gráficos:** reportes y gráficos de ventas, compras y otros indicadores.

---

## 5. Qué no hace el MCP

- No emite guías de despacho (DTE 52). Se pueden consultar, pero para emitirlas usa la plataforma o la API REST (`POST /v2/documents/batch/` o `POST /v1/documents/batch/`).
- No reemplaza las tareas que sólo existen en pantalla, como subir archivos masivos o configurar credenciales del SII; en esos casos el asistente entrega el link a la plataforma.
- No es una integración de sistema a sistema: requiere un usuario que inicie sesión y confirme las acciones.

---

## 6. Cuándo usar la API REST en vez del MCP

Usa la API REST cuando:

- Integras un sistema (ERP, e-commerce, backoffice) que emite sin intervención humana.
- Emites en volumen (hasta 200 documentos por llamada) o necesitas webhooks con el resultado.
- Necesitas tipos o campos que el MCP no cubre, como la guía de despacho con datos de transporte y Aduana.

La API usa API key (`Authorization: Api-Key TU_API_KEY`), no la sesión del usuario.

- API v2 (por defecto): https://docs.tupana.ai/api-reference/v2/introduction
- API v1: https://docs.tupana.ai/api-reference/introduction
- Tipos de documentos: https://docs.tupana.ai/user-guide/documents

Especificación legible por máquina (la fuente para agentes de código que integran la API; se actualiza con cada cambio de contrato):

- OpenAPI v2: https://docs.tupana.ai/api-reference/openapi-v2.json
- OpenAPI v1: https://docs.tupana.ai/api-reference/openapi-combined.json

---

## 7. Aclaración: MCP de Tupana y buscador de documentación

`https://mcp.tupana.ai/mcp` es el servidor de Tupana: da acceso a los datos y operaciones de tus empresas, con inicio de sesión.

No es el buscador de documentación que Mintlify puede exponer en el dominio de la documentación (`docs.tupana.ai`). Ese buscador sólo lee páginas públicas de la documentación y no accede a tus empresas ni emite documentos.