Servidor MCP

Qué es y qué puedes hacer

Nimlio expone un servidor MCP (Model Context Protocol) para que una herramienta externa, como un agente de código, trabaje sobre el código de uno de tus sitios: leer archivos, buscar, editar, compilar la vista previa, consultar los datos de tu negocio y proponer una publicación. El cliente se conecta con un token de acceso que tú creas, y ese token solo puede hacer lo que le permitan sus permisos.

• Cada token pertenece a un sitio y actúa con tus permisos de administrador de ese sitio.
• Nunca publica por sí solo: solo puede proponer publicar o volver a una versión, y la aprobación siempre es tuya.
• Puedes revocarlo cuando quieras; la sesión abierta se cierra de inmediato.

Crea un token de acceso

Desde tu negocio abre Configuración → Desarrolladores → Administrar credenciales. La pantalla está disponible para propietarios y administradores de la organización dueña del negocio, con membresía para toda la organización. Un rol en otra organización o limitado a negocios seleccionados no concede acceso.

1. 1
   Conectar un agente

   En Conectar un agente de IA (MCP), elige Conectar un agente. Primero crea un sitio web; el sitio debe admitir modo código y la organización necesita Pro o Enterprise. Starter requiere mejorar el plan.

2. 2
   Ponle nombre y elige permisos

   Escribe un Nombre (1–80 caracteres) para el cliente. Selecciona al menos un permiso: read, write, build, publish. Usa los permisos mínimos necesarios. La etiqueta “Publicar sitio” permite proponer la publicación; tú debes aprobarla.

3. 3
   Elige el vencimiento

   Configura Vence en días (1–90). El valor predeterminado es 30 días.

4. 4
   Copia la credencial y la configuración

   En Conexión del agente creada, elige Copiar credencial. Copia la URL del servidor y selecciona Claude Code o Codex, luego Copiar configuración. La configuración incluye una variable de entorno, nunca el token. Guarda el token de forma segura antes de pulsar Listo o cerrar; al cerrar se borra y no se puede volver a mostrar.

La lista muestra nombre, prefijo, permisos, vencimiento, último uso y si hay una sesión activa. Elige Revocar y confirma ¿Revocar credencial? para cortar el acceso y cualquier sesión activa de inmediato. Para renovar o cambiar permisos, crea otra conexión y revoca la anterior. Cada conexión pertenece a este sitio.

Avanzado: gestión autenticada por sesión

Las llamadas de gestión usan tu sesión iniciada, no el token MCP. Incluye el encabezado Origin de la aplicación Nimlio en POST y DELETE.

{
  "businessId": "<business-id>",
  "label": "Coding agent",
  "scopes": ["read", "write"],
  "expiresInDays": 30
}

POST: 201, data.grant, data.token (una vez), data.endpoint. GET: data.items (solo metadatos). DELETE: 200, data.grant; 404 mcp_grant_not_found si no existe.

Conecta tu cliente

El servidor usa Streamable HTTP con respuestas JSON, revisión 2025-06-18, en /mcp. Usa siempre la URL del servidor exacta que devuelve Nimlio y reemplaza <endpoint> en los ejemplos. La URL local de la captura es solo un ejemplo.

Primero carga el token en el entorno de la terminal desde la que iniciarás el cliente. Este prompt de Bash evita incluirlo en el texto del comando y en el historial. Pégalo solo en el prompt privado:

read -rs -p 'MCP token: ' NIMLIO_MCP_TOKEN
export NIMLIO_MCP_TOKEN
printf '\n'

Codex

Selecciona Codex en el diálogo de creación y copia su configuración, o inicia Codex con las opciones de abajo. bearer_token_env_var indica el nombre de la variable de entorno, no el token. Estas opciones de inicio no editan tu configuración global. Consulta la documentación MCP oficial de OpenAI.

codex -c 'mcp_servers.nimlio.url="<endpoint>"' -c 'mcp_servers.nimlio.bearer_token_env_var="NIMLIO_MCP_TOKEN"'

Claude Code

Para Claude Code, guarda este JSON en .mcp.json del proyecto y conserva ${NIMLIO_MCP_TOKEN} de forma literal. Inicia Claude Code desde la terminal donde exportaste la variable y aprueba el servidor del proyecto cuando te lo solicite. Consulta la expansión de variables de Claude Code.

{
  "mcpServers": {
    "nimlio": {
      "type": "http",
      "url": "<endpoint>",
      "headers": {
        "Authorization": "Bearer ${NIMLIO_MCP_TOKEN}"
      }
    }
  }
}

Nimlio autentica al cliente con Authorization: Bearer a partir de esa variable; una clave API (nk_pub_) no reemplaza un token MCP. Las acciones de escritura también pueden requerir aprobación del cliente. El cliente administra Mcp-Session-Id automáticamente. Cada token admite una sesión activa; ciérrala antes de abrir otra. Revocar el token o dejar que venza corta la sesión.

Permisos y herramientas

Cada token lleva uno o más permisos. Los tres primeros son acumulativos: write incluye read, y build incluye write y read. publish es independiente y no incluye ningún otro. tools/list devuelve solo las herramientas que tu token puede usar.

Las herramientas de escritura cambian el borrador del código de tu sitio, no el sitio publicado. propose_publish y propose_rollback solo registran una sugerencia: nada se publica ni se revierte hasta que tú lo apruebas.

Límites y caducidad

Al superar un límite recibes 429 con Retry-After. Un token vencido, revocado o desconocido responde siempre igual, 401, para no revelar cuál de los casos es. Antes de cada llamada se revisa de nuevo el token: si lo revocas o vence, la sesión se corta.

Revoca un acceso

1. 1
   Busca la conexión

   Busca el token por nombre y prefijo en Configuración → Desarrolladores → Conectar un agente de IA (MCP). La lista nunca devuelve el token completo.

2. 2
   Revoca el acceso

   Elige Revocar y confirma. O llama DELETE /api/sites/:siteId/mcp/grants/:grantId?businessId=… con tu sesión iniciada y el encabezado Origin. El acceso y cualquier sesión activa terminan de inmediato.

3. 3
   Reemplaza si lo necesitas

   Un token revocado no se puede reactivar.

Siguientes pasos

• SDK
• API de la plataforma
• Webhooks
• Editor