Relayer MCP

@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 per month — one rate, protection included, $0 egress uncapped, 30-day minimum retention with no separate early-delete fee.

Requirements

On Ubuntu 24.04 or Debian 12, one command sets up everything:

curl -fsSL https://releases.scpri.me/relayer/install.sh | sh

The script installs Docker Engine and the compose plugin, adds you to the docker group, starts the Relayer in /opt/xns-relayer, and waits for the dashboard at http://localhost:8888. If Claude Code is present, it also installs Node.js 20 when Node is missing or older and registers this MCP. Log out and back in afterwards so the docker group applies. On macOS or Windows it installs nothing and points you to Docker Desktop.

Without the script, the MCP needs:

• Node.js 20+ — see Installing Node.js 20 if your distro ships an older version.
• Docker Engine — on the same machine that runs the MCP. install_relayer refuses when the Docker daemon is on another machine (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 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.

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, run the MCP on a persistent Docker host instead (install Node.js 20 there and point your MCP client at it). Alternatively, hand the install step to a human operator on the target machine and continue onboarding from check_relayer_health onwards.

Install

On Ubuntu 24.04 or Debian 12, one command installs the Relayer and registers this MCP when Claude Code is present:

curl -fsSL https://releases.scpri.me/relayer/install.sh | sh

To register the MCP by hand instead:

Claude Code (one command, if you registered nothing yet):

claude mcp add --scope user 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

install_relayer writes docker-compose.yml and .env on the machine running the MCP, then runs docker compose up against whichever daemon the Docker CLI points at. When that daemon is on another machine (DOCKER_HOST=ssh://… or tcp://…, or an SSH Docker context), it refuses before writing or starting anything, and the error names the Docker host.

To install, run the MCP on the Docker host (Node.js 20 there, MCP client pointed at it) and run install_relayer again. Or unset DOCKER_HOST / switch to the default Docker context to install on the machine running the MCP.

check_prerequisites reports the same condition as a failed install_file_location check. Health checks still work against a remote daemon: the MCP honors DOCKER_HOST and the active Docker context, check_relayer_health and verify_storage probe the remote host's ports 8888/9000 instead of localhost, and check_prerequisites skips the local port probes. 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: 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.

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.