XNS Relayer MCP

Instala y gestiona un XNS Relayer autoalojado (almacenamiento de objetos distribuido compatible con S3) de forma conversacional: 15 herramientas, listo para npx, transporte stdio.

GitHub

Prueba este MCPPatrocinado

Documentación

@xns-cloud/relayer-mcp

Servidor MCP para XNS Relayer — almacenamiento de objetos descentralizado compatible con S3. Proporciona 15 herramientas que permiten a un agente de IA gestionar la configuración completa de Relayer y su administración diaria de forma conversacional a través del transporte stdio.

npx @xns-cloud/relayer-mcp@latest

Precio: $6.00 por TB-mes — una tarifa, protección incluida, $0 de salida sin límite, retención mínima de 30 días sin cargo adicional por eliminación anticipada.

Requisitos

Node.js 20+ — consulta Instalación de Node.js 20 si tu distribución incluye una versión anterior.
Docker Engine — en la misma máquina, o en un host remoto mediante un contexto de Docker (consulta Hosts Docker remotos).

Instalación de Node.js 20

El repositorio apt predeterminado de Ubuntu solo incluye Node 18, que es demasiado antiguo. Dos formas de obtener Node 20:

nvm (recomendado — no requiere root):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
\. "$HOME/.nvm/nvm.sh" && nvm install 20

NodeSource (a nivel de sistema): sigue https://github.com/nodesource/distributions#installation-instructions.

Si inicias el MCP con una versión anterior de Node, este sale inmediatamente con esta misma guía en lugar de un rastro de pila de dependencias.

Entorno

Relayer se ejecuta como un contenedor Docker y persiste sus datos en un volumen Docker. Si el MCP se ejecuta en un entorno efímero (un contenedor sandbox, un runner de CI o una VM desechable), cualquier instalación realizada allí se perderá cuando ese entorno termine. check_prerequisites detecta esto automáticamente y lo reporta como una advertencia con un siguiente paso concreto — nunca bloquea el flujo.

Si tu entorno es efímero, instala en un host Docker persistente en su lugar. La ruta más fácil desde un sandbox efímero es un contexto Docker SSH:

docker context create relayer --docker "host=ssh://user@persistent-host"
docker context use relayer

El MCP entonces gestiona la instalación en el host persistente a través del contexto SSH. Alternativamente, entrega el paso de instalación a un operador humano en la máquina objetivo y continúa la incorporación desde check_relayer_health en adelante.

Conoce la compensación antes de tomar este camino. Con un contexto SSH, los contenedores se inician en el host remoto y los datos viven en los volúmenes Docker allí, pero install_relayer escribe docker-compose.yml y .env en la máquina que ejecuta el MCP — no en el host Docker. Eso está bien para la instalación y bien para tus datos; no está bien para el día 2. Reiniciar, cambiar puertos y actualizar desde el host Docker requiere un archivo compose que ese host no tiene. Desde un sandbox efímero es peor: la única copia de esos archivos sale con el sandbox, dejando un Relayer en ejecución que nadie puede administrar.

check_prerequisites advierte sobre esto antes de que se escriba nada, y install_relayer devuelve un campo action_required más un bloque move_files que lleva la máquina y ruta de origen, la máquina y ruta de destino, el endpoint Docker que detectó, de dónde provino el archivo compose y el contenido del archivo de entorno que escribió. Ejecuta el MCP en el host Docker, o mueve el directorio de instalación tan pronto como termine la instalación.

Mover los archivos de instalación al host Docker

El MCP no genera un comando de copia para ti. Hacerlo bien significa adivinar tu versión de scp, shell, puerto ssh, bastión, política de sudo y ruta, y un comando incorrecto que parece correcto es peor que ningún comando. A continuación hay tres ejemplos trabajados que cubren las formas comunes — toma el que coincida con tu configuración y sustituye los valores de move_files.

Tres cosas que debes saber antes de adaptar cualquiera de ellos:

Mantén el mismo nombre de directorio en ambas máquinas. Compose toma el nombre del proyecto del directorio en el que se ejecuta, y los nombres de los volúmenes tienen ese prefijo. Coloca los archivos en /srv/relayer en lugar de /opt/xns-relayer y docker compose allí es un proyecto diferente: no verá los contenedores en ejecución, y docker compose up crearía un segundo conjunto de volúmenes vacíos y luego fallaría, porque container_name: xns-relayer está fijado en el archivo compose y ese nombre ya está tomado. Obtienes un 409 Conflict en lugar de un Relayer funcional, más volúmenes vacíos dispersos para limpiar. Usa el último segmento de ruta de move_files.destination_path. Mantener toda la ruta idéntica es lo más seguro — un archivo compose que vincula una ruta de host relativa la resuelve contra el directorio del proyecto.
Copia al directorio padre. scp -r /opt/xns-relayer host:/opt/xns-relayer copia dentro de un destino existente, dejando los archivos en /opt/xns-relayer/xns-relayer/ donde docker compose no los encontrará.
/opt necesita root. Si tu usuario ssh no puede escribir en el destino, créalo primero — scp no creará un padre faltante.

1 — Contexto Docker SSH, ruta predeterminada. El caso común.

ssh -t user@docker-box 'sudo install -d -o $USER /opt/xns-relayer'
scp -r /opt/xns-relayer user@docker-box:/opt

2 — Puerto ssh no estándar, o el host Docker detrás de un bastión. Nota que ssh toma -p para el puerto y scp toma -P; -J es el host de salto.

ssh -t -p 2222 user@docker-box 'sudo install -d -o $USER /opt/xns-relayer'
scp -P 2222 -r /opt/xns-relayer user@docker-box:/opt

# via a bastion — the prepare step needs the same -J
ssh -t -J user@bastion user@docker-box 'sudo install -d -o $USER /opt/xns-relayer'
scp -J user@bastion -r /opt/xns-relayer user@docker-box:/opt

3 — Sin ruta ssh desde esta máquina. Un contexto Docker tcp://, una clave que solo el CLI de Docker puede usar, o un sandbox bloqueado. Solo hay dos archivos pequeños, así que recréalos en el host Docker manualmente.

Revisa move_files.compose_source en la respuesta primero — te dice de dónde provino tu archivo compose, y los tres casos necesitan manejo diferente:

`compose_source`	Dónde obtener `docker-compose.yml`
`channel`	`curl -fsSLO <compose_url>`, usando la URL de `move_files.compose_url`
`bundled-fallback`	Provino de dentro del paquete npm en la máquina MCP, no de una URL. Copia ese archivo por cualquier medio que tengas — pegar desde el portapapeles está bien, son unas pocas docenas de líneas.
`compose_url`	Tu propio compose personalizado, de donde lo hayas proporcionado.

Luego, en un directorio cuyo último segmento de ruta coincida con move_files.destination_path:

# on the Docker host
sudo install -d -o $USER /opt/xns-relayer
cd /opt/xns-relayer
# put docker-compose.yml here per the table above, then write the env file:
printf 'UI_PORT=8888\nS3_PORT=9000\nBIND_ADDRESS=\n' > .env

Usa los valores de move_files.env_contents, no los predeterminados anteriores, si instalaste con puertos personalizados o una dirección de enlace. Si env_contents es null la instalación no escribió ningún archivo de entorno (la ruta compose_url) — tu archivo compose proporciona sus propios valores, o los exportas antes de docker compose up.

Verifica desde el host Docker después — esto debería listar los servicios en ejecución en lugar de un error sobre un archivo de configuración faltante, y debería mostrar los contenedores que ya están activos, no proponer nuevos:

cd /opt/xns-relayer && docker compose ps

Instalación

Claude Code (un comando):

claude mcp add relayer -- npx @xns-cloud/relayer-mcp@latest

Claude Desktop / cualquier cliente MCP — agrega a tu claude_desktop_config.json (o equivalente):

{
  "mcpServers": {
    "relayer": {
      "command": "npx",
      "args": ["@xns-cloud/relayer-mcp@latest"]
    }
  }
}

Cursor — agrega a .cursor/mcp.json:

{
  "mcpServers": {
    "relayer": {
      "command": "npx",
      "args": ["@xns-cloud/relayer-mcp@latest"]
    }
  }
}

No se requiere un paso de instalación separado — npx obtiene el paquete bajo demanda.

Herramientas

#	Herramienta	Propósito
1	`check_prerequisites`	Verifica Docker (local o remoto), puertos (8888, 9000), una instalación existente, disco y conectividad de red.
2	`start_registration`	Obtén la URL de registro en el navegador para crear una cuenta XNS — el agente nunca maneja credenciales.
3	`check_email_verified`	Consulta el estado de verificación de correo electrónico (intervalo de 15s, tiempo de espera de 30 min).
4	`install_relayer`	Obtén el paquete canónico del canal beta — relayer + pila de monitoreo Prometheus/Grafana (`https://releases.scpri.me/relayer/beta/docker-compose.yml`, extracción anónima, sin `docker login`) — escribe el `.env` e inicia los contenedores. Recurre a una copia de paridad de servicios incluida si la obtención falla. Solo instalaciones nuevas — consulta Instalaciones nuevas vs. implementaciones existentes. El usuario no crea nada; `compose_url` es una anulación opcional para instalaciones personalizadas.
5	`check_relayer_health`	Consulta UI, S3, HostIO y los sidecars de monitoreo (intervalo de 10s, tiempo de espera de 300s). Una pila de monitoreo faltante se reporta como degradada sin bloquear el flujo. Apunta automáticamente al host Docker.
6	`start_claim`	Inicia una sesión de reclamo — devuelve una URL para confirmación en el navegador.
7	`check_claim_status`	Consulta el estado del reclamo (STATE_1 / STATE_2 / STATE_3).
8	`get_host_tags`	Recupera las etiquetas de host disponibles para la configuración de VPD, más la selección de datos/paridad actualmente aplicada (lectura con una bandera `is_default`).
9	`configure_vpd`	Establece la selección de hosts de datos/paridad mediante expresiones CEL. `dry_run: true` previsualiza los recuentos de hosts coincidentes sin aplicar (requiere una compilación de Relayer con el endpoint de evaluación HostIO; las compilaciones anteriores reportan `preview_supported: false`).
10	`verify_storage`	Prueba S3 de ida y vuelta (crear bucket, poner objeto, obtener objeto) contra la puerta de enlace S3. Aprovisiona automáticamente una credencial IAM temporal y limitada desde tu sesión OIDC — no se necesita gestión manual de claves. La herramienta intenta eliminar los datos de prueba y la credencial desechable después de la prueba; se reporta un `cleanup_warning` si algún recurso no pudo eliminarse. `relayer_ui_url` debe apuntar a un host de loopback o red privada.
11	`setup_cli_credentials`	Aprovisiona credenciales IAM S3 y escribe `~/.xns/credentials` para que el CLI de XNS funcione sin configuración adicional.
12	`describe_settings`	Lista los ajustes configurables — ajuste de trabajadores/concurrencia, programación de respaldo, centro de costos (CCID) — con valores actuales, predeterminados y orientación. El MCP expone deliberadamente solo este conjunto curado, nunca el catálogo avanzado completo.
13	`update_settings`	Aplica un mapa de cambios de ajustes (aplicado por lista blanca). Devuelve `require_restart`. Requiere relayer-ui >= 3.43.3 — los servidores más antiguos pueden sobrescribir la contraseña de la base de datos en los viajes de ida y vuelta de configuración.
14	`restart_service`	Reinicia `hostio`, `gateway`, `s3gateway`, `database` o todos los servicios. Disruptivo; se combina con `check_relayer_health` para verificar la recuperación.
15	`manage_backups`	Lista / inicia / restaura / elimina respaldos de configuración. La restauración es destructiva y admite componentes selectivos (`db`, `conf`, `hostio`, `samba`).

Flujo de incorporación

El agente verifica los requisitos previos (Herramienta 1).
El agente obtiene la URL de registro en el navegador; el usuario crea una cuenta en el navegador (Herramienta 2).
El usuario hace clic en el enlace de verificación de correo electrónico; el agente consulta (Herramienta 3).
El agente instala e inicia los contenedores de Relayer (Herramienta 4) — escribe el compose publicado + .env él mismo; nunca se le pide al usuario una URL de compose.
El agente consulta el estado de salud hasta que UI + S3 estén activos (Herramienta 5).
El agente inicia el reclamo; el usuario abre la URL de reclamo en el navegador (Herramientas 6 + 7).
El agente inicia sesión vía OIDC para configurar las preferencias de host (Herramientas 8 + 9).
El agente verifica que el almacenamiento S3 funcione (Herramienta 10).
Opcionalmente, el agente aprovisiona credenciales CLI (Herramienta 11).

Las únicas acciones requeridas del operador son: hacer clic en un enlace de correo electrónico, completar un inicio de sesión en el navegador y confirmar un reclamo.

Gestión del día 2

Después de la incorporación, las herramientas 12-15 cubren ajustes rutinarios: describe_settings → update_settings → restart_service para ajuste (trabajadores, concurrencia, programación de respaldo, centro de costos), y manage_backups para el ciclo de vida de respaldos. Las cuatro usan la misma sesión OIDC que las herramientas 8-9. Las operaciones destructivas (restaurar, reiniciar, cambiar el centro de costos) son confirmadas por el agente con el operador antes de la ejecución — las descripciones y respuestas de las herramientas llevan las advertencias.

Instalaciones nuevas vs. implementaciones existentes

install_relayer realiza solo instalaciones nuevas — no actualiza una implementación existente en su lugar. Los nombres de contenedores Docker son únicos por daemon, por lo que cualquier contenedor xns-relayer existente (en ejecución o detenido, cualquier canal — incluida una instalación del canal alfa de releases.scpri.me) bloquea la instalación. Tanto check_prerequisites como install_relayer detectan esto y te lo indican antes de que algo se rompa.

Para reemplazar una implementación existente:

docker stop xns-relayer && docker rm xns-relayer   # does NOT delete the data directory

luego ejecuta install_relayer nuevamente. Para mantener la implementación existente, omite install_relayer y continúa la incorporación contra ella (check_relayer_health en adelante).

Hosts Docker remotos

Claude Code no tiene que ejecutarse en la máquina Docker. Si lo ejecutas en un nodo de gestión o host de salto, apunta el CLI de Docker al servidor remoto con un contexto SSH:

docker context create relayer --docker "host=ssh://user@docker-box"
docker context use relayer

(Requiere la CLI docker en el nodo de gestión — el binario estático es suficiente — y acceso por clave SSH al host de Docker).

El MCP lo detecta automáticamente (respeta DOCKER_HOST y el contexto activo de Docker):

install_relayer ejecuta docker compose contra el daemon remoto.
check_relayer_health y verify_storage sondean los puertos 8888/9000 del host remoto en lugar de localhost — asegúrate de que sean accesibles desde el nodo de gestión.
check_prerequisites omite las comprobaciones locales de disponibilidad de puertos (los contenedores enlazan puertos en el host remoto) y las reporta como omitidas con instrucciones.
check_prerequisites también eleva una advertencia install_file_location, y install_relayer devuelve action_required más un bloque file_location nombrando ambas máquinas — porque los archivos de instalación se escriben en el nodo de gestión mientras los contenedores se ejecutan en el host de Docker. Consulta Entorno para saber qué hacer al respecto.

check_relayer_health acepta una anulación host, y verify_storage una anulación endpoint, para configuraciones que la detección automática no puede ver (reenvíos de puertos, NAT).

Solución de problemas

Síntoma	Causa	Solución
El MCP sale con "requires Node.js 20 or newer"	El Node de la distribución es demasiado antiguo (Ubuntu apt incluye Node 18)	Instalando Node.js 20
`install_relayer` reporta un contenedor `xns-relayer` existente	Un despliegue anterior (cualquier canal) posee el nombre del contenedor	Instalaciones nuevas vs. despliegues existentes
El puerto 8888/9000 ya está en uso	Otro servicio en el host de Docker (otro servicio compatible con S3 ocupando el 9000)	Detenlo, o instala con puertos personalizados: `install_relayer` `ui_port` / `s3_port` (las comprobaciones de salud aceptan lo mismo)
Las comprobaciones de salud fallan pero los contenedores se ejecutan en un host de Docker remoto	Los puertos 8888/9000 no son accesibles desde el nodo de gestión	Ábrelos, o pasa las anulaciones `host` / `endpoint`
`docker compose` en el host de Docker dice que no se encontró ningún archivo de configuración, después de una instalación exitosa	El MCP se ejecutó en otra máquina, por lo que los archivos compose y env se escribieron allí	Moviendo los archivos de instalación al host de Docker, o reinstala con el MCP ejecutándose en el host de Docker
`install_relayer` falla con "Failed to create directory … on this machine"	La ruta de instalación requiere root en la máquina que ejecuta el MCP (común en estaciones de trabajo macOS/Windows para rutas bajo `/opt`)	Pasa un `install_path` escribible, o ejecuta el MCP en el host de Docker

Autenticación

Las herramientas 8-9 y 12-15 requieren un token OIDC para acceder a la API de Relayer y al proxy HostIO. El MCP adquiere uno automáticamente usando el flujo Authorization Code + PKCE (S256) contra el realm de Keycloak scprime con el cliente público relayer-native. El usuario completa un inicio de sesión en el navegador; el MCP captura el código en un listener local de loopback 127.0.0.1 y lo intercambia por un token.

Requisito previo: El cliente público relayer-native debe estar registrado en el realm de Keycloak scprime (PKCE S256, redirección http://127.0.0.1:*).

Desarrollo

npm install
npm test

Requiere Node.js 20+.

Nota sobre el cliente `relayer-native`

Este paquete usa el ID de cliente de Keycloak relayer-native para la autenticación OIDC. El mismo ID de cliente está destinado a ser reutilizado por una futura CLI independiente de Relayer (@xns-cloud/relayer-cli), con el módulo OIDC (src/lib/oidcAuth.js) extraído a un paquete compartido @xns-cloud/relayer-auth.

Política de privacidad

Política canónica: https://xns.tech/privacy-policy/. Detalles específicos del producto para este servidor están en PRIVACY.md.

La versión corta:

Sin telemetría. Sin analíticas, informes de errores o contadores de uso. No se comunica con el exterior.
Los tokens viven solo en memoria. Los tokens de acceso OIDC nunca se escriben en disco; se descartan cuando el proceso termina.
El agente nunca ve tu contraseña. El inicio de sesión ocurre en tu propio navegador contra auth.xns.tech.
Solo red privada. Ninguna herramienta puede apuntarse a un Relayer público: las que aceptan un argumento de host lo ejecutan a través de una lista de permitidos (localhost, loopback, RFC 1918, *.local), y el resto no expone ningún parámetro de URL y está fijado a localhost. Los tres servicios XNS que contacta son auth.xns.tech, console.xns.tech y releases.scpri.me.
Tus objetos almacenados nunca pasan por él. El Relayer que alojas maneja tus datos directamente.

Extensión de escritorio (MCPB)

El mismo servidor se distribuye como un MCP Bundle para instalación con un clic en Claude Desktop. Constrúyelo desde un checkout limpio:

npm run bundle

Eso reinstala dependencias solo de producción, valida el manifiesto y escribe el .mcpb. La versión de la CLI MCPB está fijada en el script — no la invoques sin versión, o el bundle que distribuyas no será el que fue validado. Ejecuta npm ci después para recuperar las dependencias de desarrollo para pruebas.

Para validar solo el manifiesto sin reempaquetar:

npm run bundle:validate

manifest.json en la raíz del repositorio es el manifiesto del bundle. mcpbManifest.test.js fija su version y la lista de herramientas a package.json, server.json y el servidor en ejecución, de modo que la deriva falle la suite en lugar de distribuirse.