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

Claude Code

claude mcp add --transport http bloques https://<tu-host>/api/mcp \
  --header "Authorization: Bearer sk_live_..."

Listo: en la siguiente sesión verás las herramientas bloques disponibles. 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. Como el servidor se autentica con cabecera Bearer (no OAuth), necesitas un plan/cliente que permita configurar cabeceras personalizadas para conectores; si tu cliente no lo permite, usa Claude Code o la API REST.

Otros clientes MCP (config JSON genérica)

{
  "mcpServers": {
    "bloques": {
      "type": "http",
      "url": "https://<tu-host>/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_..."
      }
    }
  }
}

Cualquier cliente que soporte transporte http (Streamable HTTP) con cabeceras personalizadas funciona.

Herramientas

Cada token solo ve las herramientas que sus scopes permiten — un token 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

• Scopes por token filtran las herramientas visibles. tools/list solo devuelve lo que el token 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. Cada token pertenece a exactamente una empresa; toda herramienta opera únicamente sobre los datos de esa empresa. 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 token como actor. Las emisiones registran además qué token las originó.
• Sin estado, sin divulgación anónima. El servidor no responde nada (ni siquiera su nombre) sin un Bearer válido, 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.