Documentación

Servidor MCP

Bloques incluye un servidor MCP (Model Context Protocol): el estándar abierto con el que asistentes y agentes IA — Claude, Claude Code, y cualquier cliente MCP — usan herramientas externas. Conectándolo, tu agente puede emitir boletas y facturas, consultar documentos, gestionar el catálogo y revisar tu consumo, conversando: "emite una boleta de S/ 118 por consultoría a CLIENTES VARIOS".

Endpoint y protocolo

Cómo conectarlo

En todos los clientes es lo mismo: pega la URL. El cliente recibe un 401 con la dirección de la metadata, se registra solo, te abre el navegador y ahí inicias sesión en Bloques y apruebas lo que el agente podrá hacer. Nada de tokens en archivos de configuración.

Claude Code

claude mcp add --transport http bloques https://<tu-host>/api/mcp

La primera vez que lo uses se abrirá el navegador para autorizar. Verifica con claude mcp list.

claude.ai (conector personalizado)

En claude.ai ve a Settings → Connectors → Add custom connector y registra la URL https://<tu-host>/api/mcp. Claude hace el flujo OAuth solo: no necesitas configurar cabeceras ni pegar ningún secreto.

Otros clientes MCP (config JSON genérica)

{
  "mcpServers": {
    "bloques": {
      "type": "http",
      "url": "https://<tu-host>/api/mcp"
    }
  }
}

Cualquier cliente que soporte transporte http (Streamable HTTP) con OAuth funciona. Los documentos de descubrimiento están donde manda la spec: /.well-known/oauth-protected-resource y /.well-known/oauth-authorization-server.

Tokens sk_live_… (método anterior, en retiro)

Los tokens de API siguen aceptándose en /api/mcp durante la transición, con la cabecera Authorization: Bearer sk_live_…. Se retiran del MCP en una versión próxima: reconecta tus agentes por OAuth. En la API REST no cambia nada — ahí los tokens siguen siendo el método.

Herramientas

Cada conexión solo ve las herramientas que sus permisos alcanzan — un agente de solo lectura ni siquiera sabe que create_document existe — y, cuando la herramienta pertenece a un módulo (como create_expense, del módulo Finanzas), solo si tu empresa tiene ese módulo activo. La lista que ve tu agente es, por eso, la intersección de las dos cosas.

Modelo de seguridad

• El agente nunca puede más que tú. La conexión se hace con tu cuenta: lo que se ejecuta es lo que aprobaste y tu rol permite, comprobado en cada llamada. Si mañana te quitan un permiso, tu agente lo pierde al instante; si te sacan del equipo, deja de tener acceso. No hay que revocar nada.
• Autorizas en pantalla, y ves qué autorizas. Antes de conectar, Bloques enumera lo que el agente podrá hacer — y lo que no, porque tu rol no lo permite. Sin ese paso no se emite ningún acceso.
• Acceso corto y renovación de un solo uso. El acceso del agente dura una hora y se renueva solo; cada renovación invalida la credencial anterior, así que una copia robada deja de servir apenas el agente legítimo se renueva.
• Los permisos filtran las herramientas visibles. tools/list solo devuelve lo que la conexión puede ejecutar; la superficie no autorizada permanece oculta (no solo bloqueada).
• Los módulos filtran igual que los scopes. Una herramienta de un módulo que tu empresa no tiene activo no se lista, y llamarla igual falla — el servidor lo vuelve a verificar al ejecutar.
• Gastos y dinero: escritura sin lectura. create_expense registra, pero ninguna herramienta lee gastos, saldos ni movimientos de dinero. Es deliberado: un agente puede anotar lo que se gastó sin poder consultar cuánta plata tienes ni en qué se va. Esa información se ve únicamente iniciando sesión en la app.
• Aislamiento por empresa. Toda herramienta opera únicamente sobre los datos de la empresa a la que perteneces. No existe forma de cruzar tenants.
• Auditoría de cada llamada. Toda ejecución de herramienta queda registrada en la bitácora de eventos de la empresa (mcp.tool_call), con el usuario (o el token) como actor. Las emisiones registran además de dónde vinieron.
• Sin estado, sin divulgación anónima. El servidor no responde nada (ni siquiera su nombre) sin autorización válida, y no mantiene sesiones que secuestrar.

¿Vas a programar la integración tú mismo (o tu agente)? Sigue con la guía para agentes IA o apunta directamente a /llms-full.txt.