relay-mcp

Model Context Protocol server for Relay. Lets any MCP-aware AI tool (Cursor, Claude Desktop, VS Code Copilot, etc.) inspect and control a Relay agent directly.

Setup

Add to your MCP config (~/.cursor/mcp.json, Claude Desktop config, etc.):

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

For a local agent on the same machine, use a Unix socket instead (no token needed):

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

Environment variables

| Variable | Description | |---|---| | RELAY_SOCKET | Path to relay.sock. Takes priority over HTTP if set. | | RELAY_URL | Agent base URL. Default: http://127.0.0.1:8080 | | RELAY_TOKEN | Bearer token for HTTP transport. |

Tools

| Tool | Description | |---|---| | list_projects | All projects and environments | | list_deploys | Recent deploys, filterable by app/env/branch | | get_deploy | Single deploy record by ID | | get_deploy_logs | Build/deploy logs for a deploy ID | | cancel_deploy | Cancel an in-progress deploy | | rollback | Roll back to the previous image | | start_app | Start a stopped container | | stop_app | Stop a running container | | restart_app | Restart a container without a new build | | delete_lane | Remove a lane and its state | | get_app_config | Lane config (access policy, hosts, engine) | | set_app_config | Update lane config | | list_secrets | Secret key names for an app lane | | add_secret | Add or update a secret | | remove_secret | Delete a secret | | list_promotions | Promotion requests with approval state | | approve_promotion | Approve a queued promotion | | list_users | All user accounts (owner only) | | get_audit_log | Recent audit entries (owner only) | | get_server_config | Server-level config and theme | | set_server_config | Update server config or theme | | list_buildpack_plugins | Installed buildpack plugins | | remove_buildpack_plugin | Remove a buildpack plugin | | get_version | relayd and Station version info | | create_signed_link | Time-bounded share URL for signed-link lanes | | list_companions | Companion services for an app lane | | restart_companion | Restart a companion service |

Publishing (maintainers)

@relay-org/relay-mcp is published from GitHub Actions using npm trusted publishing (OIDC).

If publish fails with npm ERR! code E404 on:

PUT https://registry.npmjs.org/@relay-org%2frelay-mcp

verify package-level trusted publisher settings on npmjs.com for @relay-org/relay-mcp:

• Organization/user: Relay-CI
• Repository: Relay
• Workflow filename: auto-release.yml (must match exactly)
• Environment: npm-publish (must match exactly if configured in workflow)

Important:

• Trusted publishing is configured per package, not per scope.
• npm currently allows one trusted publisher connection per package.
• If another workflow publishes this package, either:
  • switch the trusted publisher to that workflow, or
  • use a granular npm token in that alternate workflow.