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, para el emisor https://<tu-host>/api/auth, /.well-known/oauth-authorization-server/api/auth. Los endpoints viven en /api/auth/oauth2/* (register, authorize, token, revoke). Un cliente puede registrarse (alta dinámica, abierta) o usar como client_id la URL https de su documento de metadata (Client ID Metadata Document). Cada autorización pasa por la pantalla de consentimiento; prompt=none se rechaza.

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_…. Están en desuso y se retirarán del MCP en una versión mayor futura, que se anunciará antes en el changelog: 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 bloques_create_document existe — y, cuando la herramienta pertenece a un módulo (como bloques_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.

Todas se llaman con el prefijo bloques_ (bloques_create_document, bloques_list_products…), para que un agente con varios servidores conectados no las confunda con las de otro. Los nombres sin prefijo de la versión 1.x ya no existen: llamarlos devuelve unknown_tool con el nombre nuevo en el mensaje.

Cada herramienta declara además qué efecto tiene, para que tu cliente decida cuándo pedirte confirmación: un title y las cuatro annotations de MCP (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), siempre explícitas. Las de lectura (bloques_list_*, bloques_get_*, bloques_search_customers) son de solo lectura. bloques_create_document es destructiva y de mundo abierto: un comprobante emitido no se deshace, su número se consume aunque SUNAT lo rechace, y la llamada sale a SUNAT; es la única que sale de Bloques. bloques_update_quote, bloques_delete_quote, bloques_update_product, bloques_move_crm_client y bloques_archive_crm_interaction también son destructivas (reemplazan, mueven o borran); las demás altas solo agregan.

Y declara qué devuelve: Bloques revisa cada respuesta contra esa declaración antes de entregarla, y un campo que no está declarado nunca sale. Si alguna vez una respuesta dejara de calzar, tu agente no recibe un objeto a medias sino un error. Cuando la herramienta escribe (emitir, cobrar, crear), el error aclara que la acción sí se realizó, pide no repetirla y dice con qué herramienta revisarla: reintentar una emisión emitiría otro comprobante.

«Hoy» es la fecha de Lima que devuelve Bloques, no la del calendario del modelo ni la del dispositivo, que puede estar en otra zona horaria u otro día. bloques_list_documents, bloques_list_quotes, bloques_list_receivables, bloques_get_crm_pipeline y bloques_get_usage responden con today: la fecha en curso en America/Lima, YYYY-MM-DD. Las instrucciones del servidor le piden al agente resolver «hoy», «ayer» y «este mes» a partir de ella, y la mora de bloques_list_receivables se cuenta con ese mismo día. Los filtros de fecha (from/to) son días de Lima, inclusivos.

Cuando algo falla, la herramienta responde un error (isError) en español que dice qué hacer ahora: con qué herramienta conseguir el id correcto, a quién pedirle un permiso que falta o dónde se activa un módulo. Si el error tiene código, el texto empieza por él (module_not_enabled: …, insufficient_scope: …), y ese código no cambia aunque el texto mejore: guíate por él. Un id que no existe y uno de otra empresa o de una sucursal fuera de tu acceso reciben el mismo texto. Si la herramienta se cae a mitad de una escritura, el error avisa que la acción pudo haberse realizado y dice cómo comprobarlo antes de repetirla.

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 o recuperas tu contraseña, la conexión se borra y reconectar vuelve a pedir tu autorización. 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. La pantalla nombra el sitio que recibirá la autorización (no el nombre que la app dice tener), marca App no verificada a todo cliente que no sea claude.ai, claude.com o chatgpt.com, y avisa cuando la autorización va a un programa en tu computadora.
• 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.
• Una conexión dura 90 días desde la última vez que la autorizaste, aunque el agente se use a diario. Al vencer, tu cliente recibe un 401 y abre el navegador solo: aprietas Autorizar otra vez (e inicias sesión antes solo si tu sesión en Bloques terminó) y vuelve a contar desde cero. Así una conexión olvidada no queda abierta para siempre.
• 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).
• Tus sucursales también. Si solo trabajas en algunas sucursales, tu agente solo ve y emite en esas: bloques_list_documents, bloques_get_document y bloques_get_document_files no alcanzan los documentos de otras (responden «no encontrado», como si no existieran). Se relee en cada llamada: cambiarte las sucursales cambia a tu agente al instante.
• 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. bloques_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.
• El texto de terceros llega como dato. Nombres, descripciones, notas y direcciones los escribe tu personal o tus clientes (por ejemplo, quien reserva desde tu página pública). Antes de llegar al agente, Bloques les quita los caracteres invisibles y de control y los deja en una línea o en párrafos con tope. Las instrucciones del servidor le dicen al agente que ese texto es dato y nunca una orden, y que emitir o registrar algo solo lo pides tú; la descripción de cada herramienta que lo devuelve repite que es dato.
• Registro de cada llamada. Toda llamada a una herramienta, también la denegada y la que falla, deja una fila con quién la hizo (el usuario o el token), qué herramienta, cómo terminó y cuánto tardó; nunca los argumentos ni el resultado. Se guarda 90 días. Las emisiones registran además de dónde vinieron.
• Límite por conexión. Cada conexión puede llamar herramientas hasta 120 veces por minuto; listar las herramientas o iniciar la conexión no cuenta. Pasado el límite la herramienta no se ejecuta y el agente recibe un error de herramienta (isError) con el texto «rate_limited: Hiciste muchas llamadas en poco tiempo. Espera un minuto y vuelve a intentarlo.», así que puede esperar y seguir sin reconectarse.
• 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.

Versión y cambios

El contrato del servidor —los nombres de las herramientas, sus argumentos, lo que devuelven, sus errores y las credenciales que acepta— tiene versión propia, con semver: hoy es 2.0.0, la que tu cliente recibe en serverInfo.version al conectarse. No sigue la versión de la aplicación, que cambia por motivos que no tocan a tu integración.

• Mayor: se quita o se renombra una herramienta o un campo, un argumento se vuelve más estricto (lo que antes pasaba ahora es invalid_input), cambia el significado de un campo o de un error, o deja de aceptarse una credencial. Solo llega en hitos deliberados.
• Menor: una herramienta nueva, o un campo nuevo y opcional de entrada o de salida.
• Parche: arreglos que no cambian la forma del contrato.

Cada versión, con lo que cambia para tu integración, está en el registro de cambios del MCP (/mcp-changelog.md, en inglés como /llms-full.txt, en formato Keep a Changelog). Los cambios de la API REST están en la sección Cambios de su referencia.

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