# 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 — para emitir, usa el [SDK](/agentes/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](/referencia/limites/).

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

En lo que sigue, asume:

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

```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`.

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

```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](/agentes/para-coding-agents/) — el playbook de
  integración con el SDK
- [SDK](/agentes/sdk/) — la superficie de escritura (emisión)

---

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