Conecta tu agente

Cómo darle a un agente de IA acceso de solo lectura a tu contabilidad y facturación electrónica en Simplo, vía el servidor MCP.

Qué es

Simplo expone tus datos por MCP (Model Context Protocol) en un único endpoint:

POST https://api.simplo.cl/api/v1/mcp

El servidor MCP no es un agente: no lleva LLM ni orquestación. Es la misma API de Simplo expresada como tool-calling, para que un agente externo (Claude Code, Claude Desktop, un script tuyo, etc.) pueda leer tus datos. El agente vive en tu lado; Simplo solo provee los datos.

Características de la v1:

• Solo lectura. Tools de consulta (resúmenes contables, DTEs, folios, certificado, clientes, productos y más). No hay tools de escritura ni de emisión de DTE — la emisión no es (ni será) un tool de MCP; para emitir, integra la API REST desde tu backend.
• Aislada por empresa. La credencial es la empresa: ningún tool acepta un identificador de empresa. Una credencial solo ve los datos de su empresa.
• Dos formas de autenticar: OAuth 2.1 nativo (recomendado para clientes interactivos como Claude Desktop) o una API key estática (simple, buena para CI o scripts). Presupuesto propio de 120 llamadas/min por empresa — ver Límites.

Paso 1 — Elige cómo autenticar

OAuth 2.1 (recomendado)

El endpoint MCP soporta OAuth 2.1 nativo: el cliente descubre el authorization server, se registra dinámicamente y obtiene un token vinculado a su clave privada (DPoP) — sin copiar ni pegar una API key. Los scopes son por módulo (mcp:accounting, mcp:billing, mcp:gastos, mcp:profile) y solo se conceden si la empresa tiene ese módulo contratado; no existen scopes de escritura en v1 y ningún token de OAuth puede emitir un DTE.

El flujo, para un cliente MCP compatible con OAuth (Claude Desktop y otros):

1. Descubre — GET https://api.simplo.cl/.well-known/oauth-authorization-server (RFC 8414) entrega los endpoints; GET https://api.simplo.cl/.well-known/oauth-protected-resource (RFC 9728) entrega el recurso MCP. Un 401 de POST /api/v1/mcp también anuncia esto vía el header WWW-Authenticate.
2. Se registra — POST https://api.simplo.cl/oauth/register (Dynamic Client Registration, RFC 7591; el endpoint solo acepta POST) con tu redirect_uri. Devuelve un client_id público (sin secreto — solo PKCE).
3. Autoriza — abre el navegador en https://app.simplo.cl/oauth/authorize?...&code_challenge_method=S256 (PKCE obligatorio). Inicias sesión, eliges la empresa y ves exactamente qué scopes vas a conceder antes de aceptar.
4. Token — POST /oauth/token intercambia el code por un access_token de corta duración vinculado por DPoP (ES256/RS256, RFC 9449) y un refresh_token rotativo.
5. Llama — POST /api/v1/mcp con Authorization: DPoP <access_token> + un header DPoP con la prueba firmada para esa request. tools/list y tools/call quedan filtrados a los módulos que concediste.

La mayoría de los clientes MCP con soporte OAuth (incluido Claude Desktop, ver abajo) hacen estos cinco pasos automáticamente cuando les das la URL del endpoint — no necesitas construir el flujo a mano. Si estás escribiendo tu propio cliente, la JWKS pública para verificar tokens está en https://api.simplo.cl/.well-known/jwks.json.

API key (alternativa simple / CI)

Una API key estática (X-Api-Key: sk_simplo_..., scope de lectura agent:read — el scope por defecto de una key nueva) funciona sin navegador ni rotación de tokens. Buena para scripts, CI o clientes que no hablan OAuth. Cómo crearla, verla una única vez y revocarla: Autenticación.

Ojo con el scope: el MCP solo acepta keys agent:read. Una key de emisión (billing:dte, la del quickstart) responde 401 aquí — son superficies distintas con keys distintas.

export SIMPLO_API_KEY="sk_simplo_..."   # el valor completo de tu key

Paso 2 — Conectar tu cliente

Claude Desktop (OAuth nativo)

El “custom connector” nativo de Claude Desktop está pensado para servidores que autentican por OAuth — que es justamente el flujo de arriba. Agrega Simplo como connector apuntando al endpoint MCP:

https://api.simplo.cl/api/v1/mcp

Claude Desktop descubre el authorization server, hace el registro dinámico y te abre el navegador para iniciar sesión y conceder los scopes. No hace falta copiar ninguna API key ni editar claude_desktop_config.json a mano.

Claude Code (API key)

Claude Code soporta MCP por HTTP con headers personalizados de forma nativa — la ruta más simple es la API key:

claude mcp add --transport http simplo \
  https://api.simplo.cl/api/v1/mcp \
  --header "X-Api-Key: sk_simplo_..."

Luego, dentro de Claude Code, verás el catálogo de tools de Simplo disponible. Para quitarlo: claude mcp remove simplo.

Otros clientes MCP con OAuth

Cualquier cliente MCP que implemente descubrimiento OAuth (RFC 8414/9728) + DCR (RFC 7591) + PKCE puede conectarse directo a https://api.simplo.cl/api/v1/mcp siguiendo el flujo de OAuth 2.1 descrito arriba, sin configuración especial de parte de Simplo.

Paso 3 — Preguntas que funcionan

Una vez conectado, puedes pedirle a tu agente cosas como:

• “¿Cómo viene mi IVA de mayo?”
• “Lista mis facturas rechazadas de este mes.”
• “¿Quién es mi cliente más grande?”
• “¿Me quedan folios para emitir?”
• “¿Está vigente mi certificado digital?”

El agente decide qué tools usar; tú solo preguntas en lenguaje natural.

Solución de problemas

• 401 con API key: revisa que el header sea exactamente X-Api-Key y que la key empiece con sk_simplo_, no esté revocada y tenga scope agent:read — una key billing:dte (de emisión) no sirve en el MCP. Simplo no distingue el motivo en el 401 (anti-enumeración).
• 401/403 con OAuth: el token expiró (vida corta, ~10 min) — tu cliente debería refrescarlo solo con el refresh_token; si el refresh también falla, la conexión fue revocada (por ti, en /settings/conexiones, o por detección de robo de token) y hay que re-autorizar desde cero.
• Un scope de OAuth no aparece para elegir: la empresa no tiene ese módulo contratado — los scopes ofrecidos son la intersección entre lo que pide el cliente y lo que la empresa tiene habilitado.
• Un tool de facturación devuelve “Esta empresa no tiene facturación electrónica activa”: la empresa no tiene esa habilitación; los tools de contabilidad sí funcionan.
• 429 / te frenan: el rate limit del MCP y los tools de agente es 120 llamadas/min por empresa. Espera y reintenta.
• Claude Desktop no ve los tools: confirma que autorizaste la conexión en el navegador cuando se abrió, y que la empresa elegida tiene al menos un módulo con datos.
• Quiero revocar el acceso: /settings/conexiones en tu cuenta de Simplo lista las conexiones OAuth activas y permite revocarlas — revocar mata la conexión y sus tokens de inmediato.

Relacionado

• Para coding agents — el playbook de integración vía API REST
• SDK — el SDK TypeScript (aún no publicado)