Connect your agent

Give an AI agent read-only access to your Simplo data over MCP — endpoint, Claude Code, Claude Desktop and questions that work.

How to give an AI agent read-only access to your Simplo accounting and electronic invoicing data, via the MCP server.

What it is

Simplo exposes your data over MCP (Model Context Protocol) at a single endpoint:

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

The MCP server isn’t an agent: it carries no LLM or orchestration. It’s the same Simplo API expressed as tool-calling, so an external agent (Claude Code, Claude Desktop, your own script, etc.) can read your data. The agent lives on your side; Simplo only provides the data.

v1 characteristics:

Read-only. Query tools (accounting summaries, DTEs, folios, certificate, customers, products and more). No write or DTE-emission tools — emission is not (and won’t be) an MCP tool; to emit, integrate the REST API from your backend.
Isolated per company. The credential is the company: no tool accepts a company identifier. A credential only sees its own company’s data.
Two ways to authenticate: native OAuth 2.1 (recommended for interactive clients like Claude Desktop) or a static API key (simple, good for CI or scripts). Its own budget of 120 calls/min per company — see Limits.

Step 1 — Choose how to authenticate

OAuth 2.1 (recommended)

The MCP endpoint supports native OAuth 2.1: the client discovers the authorization server, registers dynamically and gets a token bound to its private key (DPoP) — no copying and pasting an API key. Scopes are per module (mcp:accounting, mcp:billing, mcp:gastos, mcp:profile) and are only granted if the company has that module contracted; there are no write scopes in v1, and no OAuth token can emit a DTE.

The flow, for an OAuth-capable MCP client (Claude Desktop and others):

Discover — GET https://api.simplo.cl/.well-known/oauth-authorization-server (RFC 8414) returns the endpoints; GET https://api.simplo.cl/.well-known/oauth-protected-resource (RFC 9728) returns the MCP resource. A 401 from POST /api/v1/mcp also advertises this via the WWW-Authenticate header.
Register — POST https://api.simplo.cl/oauth/register (Dynamic Client Registration, RFC 7591; the endpoint only accepts POST) with your redirect_uri. Returns a public client_id (no secret — PKCE only).
Authorize — open the browser to https://app.simplo.cl/oauth/authorize?...&code_challenge_method=S256 (PKCE required). You log in, pick the company, and see exactly which scopes you’re about to grant before accepting.
Token — POST /oauth/token exchanges the code for a short-lived access_token bound by DPoP (ES256/RS256, RFC 9449) and a rotating refresh_token.
Call — POST /api/v1/mcp with Authorization: DPoP <access_token> + a DPoP header carrying the signed proof for that request. tools/list and tools/call are filtered to the modules you granted.

Most OAuth-capable MCP clients (including Claude Desktop, see below) do these five steps automatically once you give them the endpoint URL — you don’t need to build the flow by hand. If you’re writing your own client, the public JWKS for verifying tokens is at https://api.simplo.cl/.well-known/jwks.json.

API key (simple / CI alternative)

A static API key (X-Api-Key: sk_simplo_..., read scope agent:read — the default scope of a new key) works without a browser or token rotation. Good for scripts, CI, or clients that don’t speak OAuth. How to create it, see it once and revoke it: Authentication.

Mind the scope: the MCP only accepts agent:read keys. An emission key (billing:dte, the one from the quickstart) gets a 401 here — they’re different surfaces with different keys.

export SIMPLO_API_KEY="sk_simplo_..."   # your key's full value

Step 2 — Connect your client

Claude Desktop (native OAuth)

Claude Desktop’s native “custom connector” is built for servers that authenticate via OAuth — which is exactly the flow above. Add Simplo as a connector pointing at the MCP endpoint:

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

Claude Desktop discovers the authorization server, performs dynamic registration, and opens your browser to log in and grant scopes. No API key to copy, no claude_desktop_config.json to hand-edit.

Claude Code (API key)

Claude Code supports MCP over HTTP with custom headers natively — the simplest path is the API key:

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

Then, inside Claude Code, you’ll see Simplo’s tool catalog available. To remove it: claude mcp remove simplo.

Other OAuth-capable MCP clients

Any MCP client implementing OAuth discovery (RFC 8414/9728) + DCR (RFC 7591) + PKCE can connect directly to https://api.simplo.cl/api/v1/mcp following the OAuth 2.1 flow described above, with no special configuration on Simplo’s side.

Step 3 — Questions that work

Once connected, you can ask your agent things like:

“How’s my VAT for May looking?”
“List my rejected invoices for this month.”
“Who’s my biggest customer?”
“Do I have folios left to issue?”
“Is my digital certificate valid?”

The agent decides which tools to use; you just ask in natural language.

Troubleshooting

401 with an API key: check that the header is exactly X-Api-Key and that the key starts with sk_simplo_, isn’t revoked, and has the agent:read scope — a billing:dte (emission) key doesn’t work on the MCP. Simplo doesn’t distinguish the reason in a 401 (anti-enumeration).
401/403 with OAuth: the token expired (short-lived, ~10 min) — your client should refresh it automatically with the refresh_token; if the refresh also fails, the connection was revoked (by you, in /settings/conexiones, or via token-theft detection) and you need to re-authorize from scratch.
An OAuth scope isn’t offered: the company doesn’t have that module contracted — offered scopes are the intersection of what the client requests and what the company has enabled.
A billing tool returns “This company doesn’t have electronic invoicing active”: the company doesn’t have that feature enabled; accounting tools still work.
429 / getting throttled: the rate limit for the MCP and agent tools is 120 calls/min per company. Wait and retry.
Claude Desktop doesn’t see the tools: confirm you authorized the connection in the browser when it opened, and that the chosen company has at least one module with data.
I want to revoke access: /settings/conexiones in your Simplo account lists active OAuth connections and lets you revoke them — revoking kills the connection and its tokens immediately.

For coding agents — the REST API integration playbook
SDK — the TypeScript SDK (not yet published)