@xns-cloud/relayer-mcp

MCP server for XNS Relayer onboarding and day-2 management. Provides 15 tools that let an AI agent drive the complete Relayer setup — and afterward adjust settings, manage backups, and tune the VPD — conversationally over stdio transport.

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

Related MCP server: Linode MCP Server

Claude Desktop / Claude Code Configuration

Add to your claude_desktop_config.json (or claude mcp add relayer -- npx @xns-cloud/relayer-mcp@latest for Claude Code):

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

No separate install step required.

Tools

Onboarding Flow

1. Agent checks prerequisites (Tool 1).

2. Agent registers account or skips if existing (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_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.

License

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