# Conecta tu agente

> Dale a un agente de IA acceso de solo lectura a tus datos de Simplo vía MCP — endpoint, Claude Code, Claude Desktop y preguntas que funcionan.

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](/agentes/para-coding-agents/) 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](/referencia/limites/).

## 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](/comienza/autenticacion/).

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

```bash
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:

```bash
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](/agentes/para-coding-agents/) — el playbook de
  integración vía API REST
- [SDK](/agentes/sdk/) — el SDK TypeScript (aún no publicado)

---

Versión HTML: https://docs.simplo.cl/agentes/conecta-tu-agente/ · Índice para agentes: https://docs.simplo.cl/llms.txt