XNS Relayer MCP

@xns-cloud/relayer-mcp

Servidor MCP para XNS Relayer — armazenamento de objetos descentralizado compatível com S3. Fornece 15 ferramentas que permitem que um agente de IA conduza a configuração completa do Relayer e o gerenciamento do dia 2 de forma conversacional via transporte stdio.

npx @xns-cloud/relayer-mcp@latest

Preço: $6,00 por TB-mês — uma única tarifa, proteção incluída, $0 de egress sem limite, retenção mínima de 30 dias sem taxa separada de exclusão antecipada.

Requisitos

• Node.js 20+ — veja Instalando Node.js 20 se sua distribuição trouxer uma versão mais antiga.
• Docker Engine — na mesma máquina, ou em um host remoto via contexto Docker (veja Hosts Docker remotos).

Instalando Node.js 20

O repositório apt padrão do Ubuntu só oferece Node 18, que é antigo demais. Duas maneiras de obter Node 20:

nvm (recomendado — não requer root):

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

NodeSource (em todo o sistema): siga https://github.com/nodesource/distributions#installation-instructions.

Se você iniciar o MCP em um Node mais antigo, ele sai imediatamente com esta mesma orientação em vez de um stack trace de dependência.

Ambiente

O Relayer roda como um contêiner Docker e persiste seus dados em um volume Docker. Se o MCP estiver rodando em um ambiente efêmero (um contêiner sandbox, um runner de CI ou uma VM descartável), qualquer instalação feita ali será perdida quando esse ambiente for encerrado. check_prerequisites detecta isso automaticamente e reporta como um aviso com um próximo passo concreto — nunca bloqueia o fluxo.

Se seu ambiente for efêmero, instale em um host Docker persistente. O caminho mais fácil a partir de um sandbox efêmero é um contexto Docker via SSH:

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

O MCP então conduz a instalação no host persistente através do contexto SSH. Alternativamente, entregue a etapa de instalação a um operador humano na máquina de destino e continue a integração a partir de check_relayer_health em diante.

Conheça a compensação antes de seguir por esse caminho. Com um contexto SSH, os contêineres iniciam no host remoto e os dados vivem nos volumes Docker de lá, mas install_relayer escreve docker-compose.yml e .env na máquina que executa o MCP — não no host Docker. Isso é aceitável para a instalação e para seus dados; não é aceitável para o dia 2. Reiniciar, mudar portas e atualizar a partir do host Docker exigem um arquivo compose que esse host não possui. De um sandbox efêmero é pior: a única cópia desses arquivos sai junto com o sandbox, deixando um Relayer em execução que ninguém consegue administrar.

check_prerequisites avisa sobre isso antes que qualquer coisa seja gravada, e install_relayer retorna um campo action_required além de um bloco move_files carregando a máquina e o caminho de origem, a máquina e o caminho de destino, o endpoint Docker que detectou, de onde veio o arquivo compose e o conteúdo do arquivo de ambiente que gravou. Ou execute o MCP no host Docker, ou mova o diretório de instalação assim que a instalação terminar.

Movendo os arquivos de instalação para o host Docker

O MCP não gera um comando de cópia para você. Acertar um significa adivinhar sua versão do scp, shell, porta ssh, bastion, política de sudo e caminho — e um comando errado que parece certo é pior do que nenhum comando. Abaixo estão três exemplos práticos cobrindo as formas comuns — use o que corresponde à sua configuração e substitua os valores de move_files.

Três coisas para saber antes de adaptar qualquer um deles:

• Mantenha o mesmo nome de diretório nas duas máquinas. O Compose usa o nome do projeto a partir do diretório onde roda, e os nomes dos volumes são prefixados com ele. Coloque os arquivos em /srv/relayer em vez de /opt/xns-relayer e docker compose ali é um projeto diferente: ele não verá os contêineres em execução, e docker compose up criaria um segundo conjunto de volumes vazios e então falharia, porque container_name: xns-relayer está fixado no arquivo compose e esse nome já está em uso. Você obtém um 409 Conflict em vez de um Relayer funcional, além de volumes vazios perdidos para limpar. Use o último segmento do caminho de move_files.destination_path. Manter o caminho inteiro idêntico é o mais seguro — um arquivo compose que vincula um caminho relativo do host o resolve contra o diretório do projeto.
• Copie para o diretório pai. scp -r /opt/xns-relayer host:/opt/xns-relayer copia para dentro de um destino existente, deixando os arquivos em /opt/xns-relayer/xns-relayer/ onde docker compose não os encontrará.
• /opt precisa de root. Se seu usuário ssh não puder gravar no destino, crie-o primeiro — scp não criará um pai ausente.

1 — Contexto Docker via SSH, caminho padrão. O caso comum.

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

2 — Porta ssh não padrão, ou host Docker atrás de um bastion. Observe que ssh usa -p para a porta e scp usa -P; -J é o 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 — Sem rota ssh a partir desta máquina. Um contexto Docker tcp://, uma chave que apenas o CLI do Docker pode usar, ou um sandbox restrito. São apenas dois arquivos pequenos, então recrie-os manualmente no host Docker.

Verifique move_files.compose_source na resposta primeiro — ele informa de onde veio seu arquivo compose, e os três casos exigem tratamento diferente:

compose_source	Onde obter docker-compose.yml
channel	curl -fsSLO <compose_url>, usando a URL de move_files.compose_url
bundled-fallback	Veio de dentro do pacote npm na máquina do MCP, não de uma URL. Copie esse único arquivo por qualquer meio que você tiver — colar da área de transferência é suficiente, são algumas dezenas de linhas.
compose_url	Seu próprio compose personalizado, de onde você o forneceu.

Então, em um diretório cujo último segmento do caminho corresponda a 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

Use os valores de move_files.env_contents, não os padrões acima, se você instalou com portas personalizadas ou endereço de bind. Se env_contents for null, a instalação não gravou arquivo de ambiente (o caminho compose_url) — seu arquivo compose fornece seus próprios valores, ou você os exporta antes de docker compose up.

Verifique a partir do host Docker depois — isso deve listar os serviços em execução em vez de um erro sobre arquivo de configuração ausente, e deve mostrar os contêineres que já estão ativos, não propor novos:

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

Instalação

Claude Code (um comando):

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

Claude Desktop / qualquer cliente MCP — adicione ao seu claude_desktop_config.json (ou equivalente):

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

Cursor — adicione ao .cursor/mcp.json:

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

Nenhuma etapa de instalação separada é necessária — o npx busca o pacote sob demanda.

Ferramentas

#	Ferramenta	Finalidade
1	check_prerequisites	Verificar Docker (local ou remoto), portas (8888, 9000), uma instalação existente, disco e conectividade de rede.
2	start_registration	Obter a URL de cadastro no navegador para criar uma conta XNS — o agente nunca lida com credenciais.
3	check_email_verified	Consultar o status de verificação de e-mail (intervalo de 15s, timeout de 30 min).
4	install_relayer	Buscar o pacote canônico do canal beta — relayer + stack de monitoramento Prometheus/Grafana (https://releases.scpri.me/relayer/beta/docker-compose.yml, pull anônimo, sem docker login) — gravar o .env e iniciar os contêineres. Usa uma cópia de paridade de serviço embutida se a busca falhar. Somente instalações novas — veja Instalações novas vs. implantações existentes. O usuário não escreve nada; compose_url é uma substituição opcional para instalações personalizadas.
5	check_relayer_health	Consultar UI, S3, HostIO e os sidecars de monitoramento (intervalo de 10s, timeout de 300s). Um stack de monitoramento ausente é reportado como degradado sem bloquear o fluxo. Aponta para o host Docker automaticamente.
6	start_claim	Iniciar uma sessão de reivindicação — retorna uma URL para confirmação no navegador.
7	check_claim_status	Consultar o estado da reivindicação (STATE_1 / STATE_2 / STATE_3).
8	get_host_tags	Recuperar tags de host disponíveis para configuração de VPD, além da seleção atual de dados/paridade aplicada (leitura de retorno com um sinalizador is_default).
9	configure_vpd	Definir seleção de hosts de dados/paridade via expressões CEL. dry_run: true pré-visualiza as contagens de hosts correspondentes sem aplicar (requer uma build do Relayer com o endpoint de avaliação HostIO; builds mais antigas reportam preview_supported: false).
10	verify_storage	Teste S3 de ida e volta (criar bucket, colocar objeto, obter objeto) contra o gateway S3. Provisiona automaticamente uma credencial IAM temporária e limitada a partir da sua sessão OIDC — sem necessidade de gerenciamento manual de chaves. A ferramenta tenta remover os dados de teste e a credencial descartável após o teste; um cleanup_warning é reportado se algum recurso não puder ser removido. relayer_ui_url deve apontar para um host de loopback ou rede privada.
11	setup_cli_credentials	Provisionar credenciais IAM S3 e gravar ~/.xns/credentials para que o CLI XNS funcione sem configuração adicional.
12	describe_settings	Listar as configurações ajustáveis — ajuste de workers/concorrência, agendamento de backup, centro de custo (CCID) — com valores atuais, padrões e orientação. O MCP expõe deliberadamente apenas este conjunto selecionado, nunca o catálogo avançado completo.
13	update_settings	Aplicar um mapa de alterações de configuração (com lista de permissões). Retorna require_restart. Requer relayer-ui >= 3.43.3 — servidores mais antigos podem sobrescrever a senha do banco de dados em round-trips de configuração.
14	restart_service	Reiniciar hostio, gateway, s3gateway, database ou todos os serviços. Disruptivo; combina com check_relayer_health para verificar a recuperação.
15	manage_backups	Listar / iniciar / restaurar / excluir backups de configuração. Restauração é destrutiva e suporta componentes seletivos (db, conf, hostio, samba).

Fluxo de Integração

1. O agente verifica pré-requisitos (Ferramenta 1).
2. O agente obtém a URL de cadastro no navegador; o usuário cria uma conta no navegador (Ferramenta 2).
3. O usuário clica no link de verificação de e-mail; o agente consulta (Ferramenta 3).
4. O agente instala e inicia os contêineres do Relayer (Ferramenta 4) — ele grava o compose publicado + .env ele mesmo; o usuário nunca é solicitado a fornecer uma URL de compose.
5. O agente consulta a saúde até que UI + S3 estejam ativos (Ferramenta 5).
6. O agente inicia a reivindicação; o usuário abre a URL de reivindicação no navegador (Ferramentas 6 + 7).
7. O agente faz login via OIDC para configurar preferências de host (Ferramentas 8 + 9).
8. O agente verifica se o armazenamento S3 está funcionando (Ferramenta 10).
9. Opcionalmente, o agente provisiona credenciais CLI (Ferramenta 11).

As únicas ações obrigatórias do operador são: clicar em um link de e-mail, concluir um login no navegador e confirmar uma reivindicação.

Gerenciamento do Dia 2

Após a integração, as ferramentas 12-15 cobrem ajustes rotineiros: describe_settings → update_settings → restart_service para ajuste (workers, concorrência, agendamento de backup, centro de custo), e manage_backups para o ciclo de vida de backups. Todas as quatro usam a mesma sessão OIDC das ferramentas 8-9. Operações destrutivas (restauração, reinício, alteração do centro de custo) são confirmadas pelo agente com o operador antes da execução — as descrições e respostas das ferramentas carregam os avisos.

Instalações novas vs. implantações existentes

install_relayer realiza somente instalações novas — não atualiza uma implantação existente no lugar. Os nomes de contêineres Docker são únicos por daemon, então qualquer contêiner xns-relayer existente (em execução ou parado, qualquer canal — incluindo uma instalação do canal alpha de releases.scpri.me) bloqueia a instalação. Tanto check_prerequisites quanto install_relayer detectam isso e informam antes que algo quebre.

Para substituir uma implantação existente:

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

então execute install_relayer novamente. Para manter a implantação existente, pule install_relayer e continue a integração contra ela (check_relayer_health em diante).

Hosts Docker remotos

O Claude Code não precisa rodar na máquina Docker. Se você o executar em um nó de gerenciamento ou host de salto, aponte o CLI Docker para o servidor remoto com um contexto SSH:

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

(Requer o CLI docker no nó de gerenciamento — o binário estático é suficiente — e acesso por chave SSH ao host Docker.)

O MCP detecta isso automaticamente (ele respeita DOCKER_HOST e o contexto Docker ativo):

• install_relayer executa docker compose contra o daemon remoto.
• check_relayer_health e verify_storage verificam as portas 8888/9000 do host remoto em vez de localhost — certifique-se de que elas estejam acessíveis a partir do nó de gerenciamento.
• check_prerequisites pula as verificações locais de disponibilidade de porta (os contêineres vinculam portas no host remoto) e as reporta como puladas com instruções.
• check_prerequisites também emite um aviso de install_file_location, e install_relayer retorna action_required mais um bloco file_location nomeando ambas as máquinas — porque os arquivos de instalação são gravados no nó de gerenciamento enquanto os contêineres rodam no host Docker. Veja Ambiente para saber o que fazer a respeito.

check_relayer_health aceita uma substituição de host, e verify_storage uma substituição de endpoint, para configurações que a detecção automática não consegue ver (encaminhamentos de porta, NAT).

Solução de problemas

Sintoma	Causa	Correção
O MCP encerra com "requer Node.js 20 ou mais recente"	O Node da distribuição é muito antigo (o apt do Ubuntu fornece Node 18)	Instalando Node.js 20
install_relayer relata um contêiner xns-relayer existente	Uma implantação anterior (qualquer canal) possui o nome do contêiner	Instalações novas vs. implantações existentes
Porta 8888/9000 já em uso	Outro serviço no host Docker (outro serviço compatível com S3 ocupando a 9000)	Pare-o, ou instale com portas personalizadas: install_relayer ui_port / s3_port (as verificações de saúde aceitam o mesmo)
As verificações de saúde falham, mas os contêineres rodam em um host Docker remoto	As portas 8888/9000 não estão acessíveis a partir do nó de gerenciamento	Abra-as, ou passe as substituições host / endpoint
docker compose no host Docker diz que nenhum arquivo de configuração foi encontrado, após uma instalação bem-sucedida	O MCP rodou em outra máquina, então os arquivos compose e env foram gravados lá	Movendo os arquivos de instalação para o host Docker, ou reinstale com o MCP rodando no host Docker
install_relayer falha com "Falha ao criar diretório … nesta máquina"	O caminho de instalação requer root na máquina que executa o MCP (comum em estações macOS/Windows para caminhos sob /opt)	Passe um install_path gravável, ou execute o MCP no host Docker

Autenticação

As ferramentas 8-9 e 12-15 exigem um token OIDC para acessar a API do Relayer e o proxy HostIO. O MCP adquire um automaticamente usando o fluxo Authorization Code + PKCE (S256) contra o realm scprime do Keycloak com o cliente público relayer-native. O usuário conclui um login no navegador; o MCP captura o código em um listener local de loopback 127.0.0.1 e o troca por um token.

Pré-requisito: O cliente público relayer-native deve estar registrado no realm scprime do Keycloak (PKCE S256, redirecionamento http://127.0.0.1:*).

Desenvolvimento

npm install
npm test

Requer Node.js 20+.

Nota sobre o cliente relayer-native

Este pacote usa o ID de cliente relayer-native do Keycloak para autenticação OIDC. O mesmo ID de cliente é destinado à reutilização por um futuro CLI standalone do Relayer (@xns-cloud/relayer-cli), com o módulo OIDC (src/lib/oidcAuth.js) extraído para um pacote compartilhado @xns-cloud/relayer-auth.

Política de Privacidade

Política canônica: https://xns.tech/privacy-policy/. Detalhes específicos do produto para este servidor estão em PRIVACY.md.

A versão resumida:

• Sem telemetria. Sem análises, relatórios de falhas ou contadores de uso. Ele não faz contato com o servidor.
• Os tokens vivem apenas na memória. Tokens de acesso OIDC nunca são gravados em disco; eles são descartados quando o processo encerra.
• O agente nunca vê sua senha. O login acontece no seu próprio navegador contra auth.xns.tech.
• Apenas rede privada. Nenhuma ferramenta pode ser apontada para um Relayer público: as que aceitam um argumento de host o executam através de uma lista de permissões (localhost, loopback, RFC 1918, *.local), e as demais não expõem parâmetro de URL e são fixadas em localhost. Os três serviços XNS que ele contata são auth.xns.tech, console.xns.tech e releases.scpri.me.
• Seus objetos armazenados nunca passam por ele. O Relayer que você hospeda lida com seus dados diretamente.

Extensão para desktop (MCPB)

O mesmo servidor é distribuído como um MCP Bundle para instalação com um clique no Claude Desktop. Compile-o a partir de um checkout limpo:

npm run bundle

Isso reinstala dependências apenas de produção, valida o manifesto e grava o .mcpb. A versão do CLI MCPB está fixada no script — não o invoque sem versão, ou o bundle que você distribui não é o bundle que foi validado. Execute npm ci depois para restaurar as dependências de desenvolvimento para testes.

Para validar apenas o manifesto sem reempacotar:

npm run bundle:validate

manifest.json na raiz do repositório é o manifesto do bundle. mcpbManifest.test.js fixa seu version e a lista de ferramentas em package.json, server.json e no servidor em execução, para que desvios falhem na suíte em vez de serem distribuídos.

Licença

Apache-2.0 © SCP Corp. Veja LICENSE e NOTICE.