@xns-cloud/relayer-mcp

npm version license node

MCP server for XNS Relayer — S3-compatible decentralized object storage. Provides 15 tools that let an AI agent drive the complete Relayer setup and day-2 management conversationally over stdio transport.

npx @xns-cloud/relayer-mcp@latest

Pricing: 6ドル.00 per TB-month — one rate, protection included, 0ドル egress uncapped, 30-day minimum retention with no separate early-delete fee.

• Node.js 20+ — see Installing Node.js 20 if your distro ships an older version.
• Docker Engine — on the same machine, or on a remote host via a Docker context (see Remote Docker hosts).

Ubuntu's default apt repository only ships Node 18, which is too old. Two ways to get Node 20:

nvm (recommended — no root required):

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

NodeSource (system-wide): follow https://github.com/nodesource/distributions#installation-instructions.

If you start the MCP on an older Node, it exits immediately with this same guidance instead of a dependency stack trace.

The Relayer runs as a Docker container and persists its data in a Docker volume. If the MCP is running inside an ephemeral environment (a sandbox container, a CI runner, or a throwaway VM), any installation performed there will be lost when that environment exits. check_prerequisites detects this automatically and reports it as a warning with a concrete next step — it never blocks the flow.

If your environment is ephemeral, install on a persistent Docker host instead. The easiest path from an ephemeral sandbox is an SSH Docker context:

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

The MCP then drives the install on the persistent host through the SSH context. Alternatively, hand the install step to a human operator on the target machine and continue onboarding from check_relayer_health onwards.

Know the tradeoff before you take this path. With an SSH context the containers start on the remote host and the data lives in Docker volumes there, but install_relayer writes docker-compose.yml and .env on the machine running the MCP — not on the Docker host. That is fine for the install and fine for your data; it is not fine for day 2. Restarting, changing ports, and upgrading from the Docker host all need a compose file that host does not have. From an ephemeral sandbox it is worse: the only copy of those files exits with the sandbox, leaving a running Relayer nobody can administer.

check_prerequisites warns about this before anything is written, and install_relayer returns an action_required field plus a move_files block carrying the source machine and path, the destination machine and path, the Docker endpoint it detected, where the compose file came from, and the contents of the env file it wrote. Either run the MCP on the Docker host, or move the install directory across as soon as the install finishes.

The MCP does not generate a copy command for you. Getting one right means guessing your scp version, shell, ssh port, bastion, sudo policy and path, and a wrong command that looks right is worse than no command. Below are three worked examples covering the common shapes — take the one that matches your setup and substitute the values from move_files.

Three things to know before you adapt any of them:

• Keep the same directory name on both machines. Compose takes the project name from the directory it runs in, and volume names are prefixed with it. Land the files in /srv/relayer instead of /opt/xns-relayer and docker compose there is a different project: it will not see the running containers, and docker compose up would create a second set of empty volumes and then fail, because container_name: xns-relayer is pinned in the compose file and that name is already taken. You get a 409 Conflict rather than a working Relayer, plus stray empty volumes to clean up. Use the last path segment from move_files.destination_path. Keeping the whole path identical is safest — a compose file that binds a relative host path resolves it against the project directory.
• Copy to the parent directory. scp -r /opt/xns-relayer host:/opt/xns-relayer copies into an existing target, leaving the files at /opt/xns-relayer/xns-relayer/ where docker compose will not find them.
• /opt needs root. If your ssh user cannot write the destination, create it first — scp will not create a missing parent.

1 — SSH Docker context, default path. The common case.

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

2 — Non-standard ssh port, or the Docker host behind a bastion. Note ssh takes -p for the port and scp takes -P; -J is the jump host.

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 — No ssh route from this machine. A tcp:// Docker context, a key only the Docker CLI can use, or a locked-down sandbox. There are only two small files, so recreate them on the Docker host by hand.

Check move_files.compose_source in the response first — it tells you where your compose file came from, and the three cases need different handling:

Then, in a directory whose last path segment matches 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 the values from move_files.env_contents, not the defaults above, if you installed with custom ports or a bind address. If env_contents is null the install wrote no env file (the compose_url path) — your compose file supplies its own values, or you export them before docker compose up.

Verify from the Docker host afterwards — this should list the running services rather than an error about a missing configuration file, and should show the containers that are already up, not propose new ones:

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

Claude Code (one command):

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

Claude Desktop / any MCP client — add to your claude_desktop_config.json (or equivalent):

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

Cursor — add to .cursor/mcp.json:

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

No separate install step required — npx fetches the package on demand.

1. Agent checks prerequisites (Tool 1).
2. Agent gets the browser sign-up URL; user creates an account in the browser (Tool 2).
3. User clicks email verification link; agent polls (Tool 3).
4. Agent installs and starts Relayer containers (Tool 4) — it writes the released compose + .env itself; the user is never asked for a compose URL.
5. Agent polls health until UI + S3 are up (Tool 5).
6. Agent initiates claim; user opens claim URL in browser (Tools 6 + 7).
7. Agent signs in via OIDC to configure host preferences (Tools 8 + 9).
8. Agent verifies S3 storage is working (Tool 10).
9. Optionally, agent provisions CLI credentials (Tool 11).

The operator's only required actions are: clicking one email link, completing one browser sign-in, and confirming one claim.

After onboarding, tools 12-15 cover routine adjustments: describe_settings → update_settings → restart_service for tuning (workers, concurrency, backup schedule, cost center), and manage_backups for the backup lifecycle. All four use the same OIDC session as tools 8-9. Destructive operations (restore, restart, changing the cost center) are agent-confirmed with the operator before execution — the tool descriptions and responses carry the warnings.

install_relayer performs fresh installs only — it does not upgrade an existing deployment in place. Docker container names are unique per daemon, so any existing xns-relayer container (running or stopped, any channel — including an alpha-channel install from releases.scpri.me) blocks the install. Both check_prerequisites and install_relayer detect this and tell you before anything breaks.

To replace an existing deployment:

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

then run install_relayer again. To keep the existing deployment, skip install_relayer and continue onboarding against it (check_relayer_health onwards).

Claude Code doesn't have to run on the Docker machine. If you run it on a management node or jump host, point the Docker CLI at the remote server with an SSH context:

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

(Requires the docker CLI on the management node — the static binary is enough — and SSH key access to the Docker host.)

The MCP detects this automatically (it honors DOCKER_HOST and the active Docker context):

• install_relayer runs docker compose against the remote daemon.
• check_relayer_health and verify_storage probe the remote host's ports 8888/9000 instead of localhost — make sure those are reachable from the management node.
• check_prerequisites skips the local port-availability probes (the containers bind ports on the remote host) and reports them as skipped with instructions.
• check_prerequisites also raises an install_file_location warning, and install_relayer returns action_required plus a file_location block naming both machines — because the install files are written on the management node while the containers run on the Docker host. See Environment for what to do about it.

check_relayer_health accepts a host override, and verify_storage an endpoint override, for setups the auto-detection can't see (port forwards, NAT).

Tools 8-9 and 12-15 require an OIDC token to access the Relayer API and HostIO proxy. The MCP acquires one automatically using Authorization Code + PKCE (S256) flow against the scprime Keycloak realm with the relayer-native public client. The user completes a browser sign-in; the MCP captures the code on a local 127.0.0.1 loopback listener and exchanges it for a token.

Prerequisite: The relayer-native public client must be registered on the Keycloak scprime realm (PKCE S256, redirect http://127.0.0.1:*).

npm install
npm test

Requires Node.js 20+.

This package uses the relayer-native Keycloak client ID for OIDC authentication. The same client ID is intended for reuse by a future standalone Relayer CLI (@xns-cloud/relayer-cli), with the OIDC module (src/lib/oidcAuth.js) extracted to a shared @xns-cloud/relayer-auth package.

Canonical policy: https://xns.tech/privacy-policy/ . Product-specific detail for this server is in PRIVACY.md.

The short version:

• No telemetry. No analytics, crash reporting, or usage counters. It does not phone home.
• Tokens live in memory only. OIDC access tokens are never written to disk; they are discarded when the process exits.
• The agent never sees your password. Sign-in happens in your own browser against auth.xns.tech.
• Private network only. No tool can be pointed at a public Relayer: the ones taking a host argument run it through an allowlist (localhost, loopback, RFC 1918, *.local), and the rest expose no URL parameter and are fixed to localhost. The three XNS services it contacts are auth.xns.tech, console.xns.tech, and releases.scpri.me.
• Your stored objects never pass through it. The Relayer you host handles your data directly.

The same server ships as an MCP Bundle for one-click install in Claude Desktop. Build it from a clean checkout:

npm run bundle

That reinstalls production-only dependencies, validates the manifest, and writes the .mcpb. The MCPB CLI version is pinned in the script — do not invoke it unversioned, or the bundle you ship is not the bundle that was validated. Run npm ci afterwards to get the dev dependencies back for testing.

To validate the manifest alone without repacking:

npm run bundle:validate

manifest.json at the repo root is the bundle manifest. mcpbManifest.test.js pins its version and tool list to package.json, server.json, and the running server, so drift fails the suite rather than shipping.

Apache-2.0 © SCP Corp. See LICENSE and NOTICE.