Servidor MCP (asistentes IA)

Emitoo expone un servidor MCP (Model Context Protocol) en https://api.emitoo.io/mcp. Claude, ChatGPT, Cursor, Claude Code o tu propio agente pueden consultar los comprobantes emitidos, las ventas, los clientes, las compras y los cobros de una empresa en lenguaje natural: «¿cuánto facturé en septiembre?», «¿qué facturas de ACME siguen con saldo?», «muéstrame el resumen fiscal del mes».

Claude.ai y ChatGPT (Conectores)

Los hosts que soportan OAuth se conectan sin copiar claves. El flujo es OAuth 2.1 con PKCE y registro dinámico del cliente; a ti solo te toca aprobar.

1. En el asistente, añade un conector personalizado con la URL https://api.emitoo.io/mcp.
2. El asistente te lleva a app.emitoo.io/conectar. Inicia sesión con un usuario administrador de la empresa.
3. Elige la empresa (si administras varias) y los alcances que autorizas. La pantalla muestra a qué dominio volverá el navegador: si no lo esperabas, cancela.
4. Vuelves al asistente ya conectado. Empieza preguntando «¿a qué empresa estás conectado?» (usa empresa_actual).

La conexión vence a los 90 días; al vencer, el asistente vuelve a pedir autorización. Puedes revocarla antes desde API keys → Asistentes IA en el panel.

Claude Code, Cursor y Claude Desktop

Para hosts que se configuran con un archivo o un comando, crea una conexión en API keys → Asistentes IA → Nueva conexión. Te da una clave fmk_… (se muestra una sola vez) que viaja como Authorization: Bearer.

claude mcp add --transport http emitoo https://api.emitoo.io/mcp \
  --header "Authorization: Bearer fmk_..."

{
  "mcpServers": {
    "emitoo": {
      "url": "https://api.emitoo.io/mcp",
      "headers": { "Authorization": "Bearer fmk_..." }
    }
  }
}

curl -X POST https://api.emitoo.io/mcp \
  -H "Authorization: Bearer $EMITOO_MCP_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": { "name": "ventas_periodo",
                "arguments": { "desde": "2026-09-01", "hasta": "2026-09-30" } }
  }'

Qué puede consultar

24 herramientas, todas anotadas como readOnlyHint. Los listados devuelven como mucho 100 filas y un siguiente_offset para paginar; los importes van en USD y las fechas en hora de Ecuador. Cada alcance agrupa un conjunto de herramientas:

comprobantes:read — Comprobantes emitidos y reportes de ventas

catalogo:read — Clientes, proveedores y servicios

compras:read — Compras, cobros y pagos a proveedores

Seguridad y control

• Una conexión = una empresa. El asistente nunca ve otra empresa aunque tu usuario administre varias; para dos empresas se crean dos conexiones.
• Solo un administrador autoriza. Las cuentas de plataforma y los roles contador, usuario o admin de sucursal no pueden conectar asistentes.
• Alcances recortables. Al autorizar eliges qué grupos de datos puede leer; el resto responde «esta conexión no tiene acceso».
• Auditoría. Cada llamada a una herramienta queda en la bitácora de la empresa (método MCP, herramienta, argumentos, IP, duración), junto a las peticiones de la API REST.
• Revocación inmediata desde el panel; la conexión también vence sola a los 90 días.
• Mismo rate limit que la API pública, por conexión y por IP.

Planes

El servidor MCP está incluido en todos los planes de pago. En el plan Gratis, empresa_actual responde (para que el asistente pueda explicarlo) y el resto de herramientas devuelve «Tu plan no incluye el Asistente IA (MCP)». Se activa al subir de plan, sin reconectar.

Para desarrolladores: el protocolo

Es MCP estándar sobre Streamable HTTP, sin estado y con respuestas JSON, así que cualquier cliente compatible funciona. Los endpoints relevantes cuelgan de https://api.emitoo.io:

Sin credencial, /mcp responde el 401 que dispara el flujo OAuth en el host:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token",
  resource_metadata="https://api.emitoo.io/.well-known/oauth-protected-resource/mcp"

Y la respuesta de /token tras el consentimiento:

{
  "access_token": "fmk_…",
  "token_type": "Bearer",
  "expires_in": 7776000,
  "scope": "comprobantes:read catalogo:read compras:read"
}

Errores habituales