Conectar un agente

Suite completa, no un wrapper delgado. Emisión, recepción y la capa tributaria están todas aquí.

Ejecución directa, con una salida de emergencia para quien la quiera. El paso de aprobación de herramientas del propio cliente MCP es el humano en el ciclo por defecto. Las empresas que quieran más pueden encender un doble paso borrador-y-confirmación.

Ser AI-first es resolver ambigüedad, no rechazarla. draft_document acepta un receptor por nombre, porque así le habla una persona a un agente. Los ítems van estructurados ([{description, quantity, unit_price}]): la prosa la convierte el modelo, que es quien la entiende mejor y más barato, y draft_document devuelve los totales para que la persona los vea antes de que se firme nada. No hay un parser de prosa en la API, y no lo va a haber: un parser escondido detrás de un endpoint convierte una cantidad mal leída en un documento tributario.

Cómo se identifica el cliente. La especificación de MCP fija un orden de prioridad para que un cliente diga quién es: un cliente pre-registrado primero, después un documento de metadatos del client_id (CIMD), y el registro dinámico al final, como respaldo.

• Documento de metadatos del client_id (CIMD). El cliente puede usar una URL https como client_id — por ejemplo https://claude.ai/.well-known/oauth-client.json — en vez de registrarse antes de conectarse. El servidor la obtiene al momento de la conexión (GET, 3 s de plazo, 32 KB máximo, sin redirecciones, nunca hacia una dirección privada o loopback) y valida el JSON: el client_id que declara el documento tiene que ser exactamente esa URL, client_name y redirect_uris son obligatorios, y solo se aceptan clientes públicos (token_endpoint_auth_method ausente o "none", PKCE S256 como siempre). El resultado se cachea respetando Cache-Control: max-age, acotado entre 1 y 24 horas — un error nunca se cachea. El redirect_uri de cada autorización tiene que calzar exacto con uno de los que declara el documento, la misma regla que un cliente registrado — con una sola excepción, la de RFC 8252 §7.3: si el documento declara http://localhost/… o http://127.0.0.1/…, el puerto no se compara, porque un cliente nativo como Claude Code abre uno distinto en cada sesión.
• Registro dinámico de cliente (RFC 7591). El respaldo para el cliente que todavía no publica un CIMD — Cursor, VS Code, Windsurf, ChatGPT y similares siguen aquí. Cualquier cliente MCP se registra en la primera conexión, sin aprobación previa ni lista blanca de aplicaciones. El registro devuelve un client_id público; no hay client_secret, porque PKCE es el mecanismo de confidencialidad de un cliente público que no puede guardar un secreto.

POST https://mcp.facturia.cl/register        (RFC 7591)
GET  https://mcp.facturia.cl/.well-known/oauth-authorization-server

Ese mismo GET declara si el servidor acepta CIMD:

{ "client_id_metadata_document_supported": true }

Qué ve la persona en la pantalla de consentimiento. Con un cliente CIMD la pantalla muestra su nombre y el origen de su documento de metadatos («Claude · claude.ai») — ese origen es verificable, porque ahí vive el documento. Un cliente que se registró dinámicamente sigue con la advertencia «Esta aplicación se registró sola y eligió su propio nombre — nosotros no lo verificamos». En los dos casos la pantalla sigue mostrando el host al que va el código de autorización («A dónde va esto»), con una advertencia extra si ese host es localhost o 127.0.0.1.

Autorización y consentimiento. Flujo estándar de authorization-code + PKCE. La pantalla de consentimiento no es un timbre de goma: ahí decides qué credencial de Facturia queda envuelta en el grant.

GET https://mcp.facturia.cl/authorize
  ?client_id=mcpc_01K2SC9X4M
  &redirect_uri=https://claude.ai/api/mcp/auth_callback
  &response_type=code
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &scope=documents:read documents:write tax:read
  &state=af0ifjsldkj

Token. POST /token cambia el código (con el verificador PKCE) por un access token de vida corta y un refresh token de vida más larga, revocable individualmente.

{
  "access_token": "mcpat_9lQpV3fA2mKcRt7wZxYb1Nde",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "mcprt_qT8vN2wLmR5xKpJ7hYdCbA3s",
  "scope": "documents:read documents:write tax:read"
}