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 — para emitir, usa el SDK desde tu backend.
• Aislada por empresa. La credencial es la empresa: ningún tool acepta un identificador de empresa. Una API key solo ve los datos de su empresa.
• La misma auth y el mismo rate limit que la API REST — ver Límites.

Paso 1 — Obtener una API key

La autenticación es por API key (X-Api-Key: sk_simplo_...), con el scope de lectura agent:read. Cómo crearla, verla una única vez y revocarla: Autenticación.

En lo que sigue, asume:

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

Paso 2 — Conectar tu cliente

Claude Code

Claude Code soporta MCP por HTTP con headers personalizados de forma nativa:

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.

Claude Desktop

El “custom connector” nativo de Claude Desktop está pensado para servidores que autentican por OAuth, no para inyectar un header estático como X-Api-Key. Como el MCP de Simplo v1 autentica por API key (OAuth está en el roadmap), usa el puente mcp-remote, que corre como servidor stdio local y reenvía a tu endpoint remoto agregando el header. En claude_desktop_config.json:

{
  "mcpServers": {
    "simplo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.simplo.cl/api/v1/mcp",
        "--header",
        "X-Api-Key:${SIMPLO_API_KEY}"
      ],
      "env": {
        "SIMPLO_API_KEY": "sk_simplo_..."
      }
    }
  }
}

Notas:

• El formato X-Api-Key:${SIMPLO_API_KEY} (sin espacio después de los dos puntos) evita problemas de parseo de argumentos en algunas versiones de mcp-remote; la key va por la variable de entorno env para no quedar en texto plano en args.
• mcp-remote requiere Node.js instalado. Reinicia Claude Desktop tras editar el config.

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 / la conexión es rechazada: 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. Simplo no distingue el motivo en el 401 (anti-enumeración).
• 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 es 120 llamadas/min por empresa, compartido entre REST y MCP. Espera y reintenta.
• Claude Desktop no ve los tools: confirma que npx/Node está instalado y que reiniciaste la app tras editar claude_desktop_config.json.

Relacionado

• Para coding agents — el playbook de integración con el SDK
• SDK — la superficie de escritura (emisión)