@xns-cloud/relayer-mcp

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.

Requirements

• 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).

Installing Node.js 20

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 .

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

Environment

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.

Moving the install files to the Docker host

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

Install

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.

Tools

Onboarding Flow

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.

Day-2 Management

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.

Fresh installs vs. existing deployments

`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).

Remote Docker hosts

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

Troubleshooting

Authentication

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:*`).

Development

npm install
npm test

Requires Node.js 20+.

Note on `relayer-native` client

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.

Privacy Policy

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

Desktop extension (MCPB)

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.

License

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