relay MCP

Control your agent from any AI tool.

relay-mcp is an MCP server that exposes your Relay agent as 26 structured tools. Any MCP-aware client — Cursor, Claude Desktop, VS Code Copilot — can deploy apps, stream build logs, approve promotions, manage secrets, and roll back lanes without leaving the IDE.

~/.cursor/mcp.json

{
  "mcpServers": {
    "relay": {
      "command": "npx",
      "args": ["-y", "@relay-org/relay-mcp"],
      "env": {
        "RELAY_URL": "http://your-server:8080",
        "RELAY_TOKEN": "your-token"
      }
    }
  }
}

npx pulls @relay-org/relay-mcp from npm on first run and caches it. No global install needed.

Tool categories

26 tools across six areas of control.

The server covers the same operations available in the dashboard and CLI. Use them directly in agent chat or as callable tools from an AI workflow.

Projects and deploys

List all projects, browse deploy history, stream build logs, cancel an in-progress build, and roll back to the previous image.

list_projectslist_deploysget_deployget_deploy_logscancel_deployrollback

App control

Start, stop, or restart a running container without triggering a new build. Delete a lane and its associated state entirely.

start_appstop_apprestart_appdelete_lane

Config and secrets

Read or update lane config including access policy, hosts, and engine. List secret key names, write new values, and remove old ones.

get_app_configset_app_configlist_secretsadd_secretremove_secret

Promotions

List pending promotion requests with their approval state and approve a queued staging-to-production promotion without opening the dashboard.

list_promotionsapprove_promotion

Admin and audit

List all user accounts, read recent audit entries, and get or update server-level config including theme settings. Owner role required.

list_usersget_audit_logget_server_configset_server_config

Plugins, signed links, and companions

List or remove installed buildpack plugins, generate a time-bounded share URL for a signed-link lane, and restart companion services.

list_buildpack_pluginsremove_buildpack_pluginget_versioncreate_signed_linklist_companionsrestart_companion

Transport

Unix socket for local agents. HTTP + token for remote ones.

The server picks the transport from environment variables. Socket auth requires no token because local access is the permission. HTTP mode sends a Bearer header on every request.

Unix socket

Local agent on the same machine

Socket transport

{
  "mcpServers": {
    "relay": {
      "command": "npx",
      "args": ["-y", "@relay-org/relay-mcp"],
      "env": {
        "RELAY_SOCKET": "/path/to/relay.sock"
      }
    }
  }
}

RELAY_SOCKET takes priority over HTTP when both are set. Default socket path is ./data/relay.sock.

HTTP + token

Remote agent over the network

HTTP transport

{
  "mcpServers": {
    "relay": {
      "command": "npx",
      "args": ["-y", "@relay-org/relay-mcp"],
      "env": {
        "RELAY_URL": "http://your-server:8080",
        "RELAY_TOKEN": "your-token"
      }
    }
  }
}

RELAY_URL defaults to http://127.0.0.1:8080. Get your token from the dashboard Server tab or relay.sock auth.

RELAY_SOCKET

Path to relay.sock. Takes priority over HTTP if set.

RELAY_URL

Agent base URL. Defaults to http://127.0.0.1:8080.

RELAY_TOKEN

Bearer token for HTTP transport.

Client setup

Drop the config block into whichever client you use.

All three clients use the same JSON shape with minor key differences. The server binary is fetched by npx on first use — nothing to install globally.

Cursor

~/.cursor/mcp.json

Cursor

{
  "mcpServers": {
    "relay": {
      "command": "npx",
      "args": ["-y", "@relay-org/relay-mcp"],
      "env": {
        "RELAY_URL": "http://your-server:8080",
        "RELAY_TOKEN": "your-token"
      }
    }
  }
}

Claude Desktop

claude_desktop_config.json

Claude Desktop

{
  "mcpServers": {
    "relay": {
      "command": "npx",
      "args": ["-y", "@relay-org/relay-mcp"],
      "env": {
        "RELAY_URL": "http://your-server:8080",
        "RELAY_TOKEN": "your-token"
      }
    }
  }
}

VS Code Copilot

.vscode/mcp.json or settings.json

VS Code Copilot

{
  "servers": {
    "relay": {
      "command": "npx",
      "args": ["-y", "@relay-org/relay-mcp"],
      "env": {
        "RELAY_URL": "http://your-server:8080",
        "RELAY_TOKEN": "your-token"
      }
    }
  }
}

Tool reference

Full list of tools the server exposes.

Every tool maps directly to a relayd API endpoint. The server validates inputs and surfaces errors back to the AI client as structured tool results.

list_projectsAll projects and environments

list_deploysRecent deploys, filterable by app/env/branch

get_deploySingle deploy record by ID

get_deploy_logsBuild/deploy logs for a deploy ID

cancel_deployCancel an in-progress deploy

rollbackRoll back to the previous image

start_appStart a stopped container

stop_appStop a running container

restart_appRestart a container without a new build

delete_laneRemove a lane and its state

get_app_configLane config (access policy, hosts, engine)

set_app_configUpdate lane config

list_secretsSecret key names for an app lane

add_secretAdd or update a secret

remove_secretDelete a secret

list_promotionsPromotion requests with approval state

approve_promotionApprove a queued promotion

list_usersAll user accounts (owner only)

get_audit_logRecent audit entries (owner only)

get_server_configServer-level config and theme

set_server_configUpdate server config or theme

list_buildpack_pluginsInstalled buildpack plugins

remove_buildpack_pluginRemove a buildpack plugin

get_versionrelayd and Station version info

create_signed_linkTime-bounded share URL for signed-link lanes

list_companionsCompanion services for an app lane

restart_companionRestart a companion service

Install

Use npx or install globally. Both work the same way.

npx fetches and caches the package automatically. For teams that prefer a locked version, install with npm and pin the version in package.json.

npx (no install)

npx -y @relay-org/relay-mcp — resolves from npm and caches locally after first run. Add @latest to force a fresh version check.

Recommended for MCP client configs.

Global install

npm install -g @relay-org/relay-mcp — adds relay-mcp to PATH globally. Change the command in your MCP config to relay-mcp.

Use when you want a fixed binary version.

Local dependency

npm install @relay-org/relay-mcp in your project — reference the local binary with npx relay-mcp in your MCP config.

Useful when the agent is part of your repo.

npm registry

# use directly
npx -y @relay-org/relay-mcp

# or install globally
npm install -g @relay-org/relay-mcp

# package name
@relay-org/relay-mcp

Published to npm under the @relay-org scope. Source lives in relay-mcp/ in the main Relay repo.

Troubleshooting

Common install and publish issues.

These are the two issues teams run into most often: stale local npx cache and npm publish permission mismatches for maintainers.

npx is using an older relay-mcp version

npx caches packages after first run. If you want to force the latest package version, pin @latest in the MCP command args.

Force latest

"command": "npx",
"args": ["-y", "@relay-org/relay-mcp@latest"]

Keep this pin only if you want automatic updates every time clients refresh.

Maintainers: npm publish E404 for @relay-org/relay-mcp

This error usually means trusted publishing is configured on npm for a different workflow than the one running npm publish.

Expected trusted publisher values

Org/user: Relay-CI

Repository: Relay

Workflow: auto-release.yml

Environment: npm-publish

Trusted publishing is package-specific and currently one trusted publisher connection is allowed per package.