Installation & Setup

For full installation instructions, client-specific configuration, and troubleshooting, see the runwhen-platform-mcp GitHub repository.

Requirements

Requirement	Local MCP (stdio)	Remote MCP (HTTP)
RunWhen account and API token (Getting a token)	Required	Required
MCP client that supports stdio transport	Required	—
MCP client that supports remote / streamable HTTP MCP	—	Required
Python 3.10+ and pip install runwhen-platform-mcp	Required (server runs on your machine)	Not required
runwhen-platform-mcp on your PATH (or full path in config)	Required so the client can launch the process	—

• Set RW_API_URL, RUNWHEN_TOKEN, and optionally DEFAULT_WORKSPACE for local mode (see Quick start).
• For venv or source installs, use the full path to the executable in command (see the GitHub README — MCP client configuration).

Quick start

pip install runwhen-platform-mcp

Then add it to your MCP client (Cursor, VS Code, Claude Desktop, etc.):

{
  "mcpServers": {
    "runwhen": {
      "command": "runwhen-platform-mcp",
      "env": {
        "RW_API_URL": "https://papi.beta.runwhen.com",
        "RUNWHEN_TOKEN": "your-token-here",
        "DEFAULT_WORKSPACE": "your-workspace"
      }
    }
  }
}

Replace your-token-here with a RunWhen API token and your-workspace with your workspace name.

Use the same mcpServers object shape everywhere below; only the config file location and restart behavior differ by client. The GitHub README also covers source installs, Windows paths, and troubleshooting.

Claude Desktop

Claude Desktop reads a single JSON file. Put your RunWhen server under the top-level mcpServers key (merge with any servers you already have — do not replace the whole file unless it only contains mcpServers).

Config file location

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/claude/claude_desktop_config.json

Local (stdio)

1. Complete Quick start so runwhen-platform-mcp is installed and your token works.
2. Open or create the config file above.
3. Add or merge a runwhen entry using the command + env JSON from Quick start.
4. Fully quit Claude Desktop (not only close the window) and start it again so it reloads MCP.

Remote (HTTP)

1. Add or merge a runwhen entry using url and headers.Authorization as in RunWhen-hosted MCP (beta).
2. Fully quit and restart Claude Desktop.

If tools do not appear, confirm the JSON is valid, the file path matches your OS, and you restarted the app after saving.

CLI and terminal-based clients

Terminal clients (Claude Code, OpenAI Codex CLI, Google Gemini CLI, Continue in the terminal, and similar) use the same RunWhen server as desktop apps: either local stdio (command + env) or remote HTTP (url + headers).

Requirements for CLI use

• Same RunWhen credentials as in Getting a token.
• Local mode: Python 3.10+, a working runwhen-platform-mcp executable (on PATH or configured with a full path), and a CLI that can spawn subprocesses for MCP stdio.
• Remote mode: No local Python install; the CLI must support MCP over streamable HTTP with a Bearer token (or your client’s equivalent of url + Authorization header).
• If the CLI only supports one transport, pick the matching Quick start or Remote server (HTTP) configuration.

Claude Code (Anthropic)

Configure MCP through Claude Code using Anthropic’s current workflow — for example the claude mcp add command (stdio or HTTP transport, env vars, headers) or project-level MCP config as described in Connect Claude Code to tools via MCP. Point stdio mode at runwhen-platform-mcp with the same env as in Quick start, or add the hosted URL https://mcp.beta.runwhen.com/mcp with Authorization: Bearer <token> for remote mode.

Other CLIs

Follow your vendor’s documentation for where to register MCP servers (often a JSON file or CLI flags). Use the same mcpServers.runwhen shapes as in this page and the GitHub README.

Remote server (HTTP)

If your editor supports remote MCP (streamable HTTP), you can skip the local Python install and connect over HTTPS.

RunWhen-hosted MCP (beta)

RunWhen operates the Platform MCP server for the beta environment. Use this URL (note /mcp with no trailing slash — some clients break on redirects):

https://mcp.beta.runwhen.com/mcp

Authenticate with the same Personal Access Token or session JWT you use for app.beta.runwhen.com — send it in the Authorization header:

{
  "mcpServers": {
    "runwhen": {
      "url": "https://mcp.beta.runwhen.com/mcp",
      "headers": {
        "Authorization": "Bearer your-runwhen-token"
      }
    }
  }
}

The service validates each request against your RunWhen account. Pass workspace_name on tools that accept it when you need a specific workspace (or set a default in your client’s instructions). For Cursor, VS Code, Claude Desktop, and CLI clients, see Claude Desktop, CLI and terminal-based clients, and the GitHub README — Remote (HTTP) access.

Self-hosted MCP

You can also run the same server yourself (Docker, Kubernetes, etc.) and point url at your own hostname. See the GitHub README — Remote (HTTP) access for deployment options (MCP_TRANSPORT=http, scaling, and optional server-side DEFAULT_WORKSPACE).

Getting a token

Personal Access Token (recommended — valid up to 180 days):

1. Open the RunWhen UI at app.beta.runwhen.com
2. Go to Profile → Personal Tokens
3. Create a token and copy it — use it as RUNWHEN_TOKEN or as the Bearer token for remote MCP

See the GitHub README for alternative methods (email/password, browser).

Access control

Your MCP server session inherits the permissions of your RunWhen account:

Role	Workspace chat	View issues/SLXs	Run scripts (Tool Builder)	Commit SLXs
readonly	No	Yes	No	No
readandrun	No	Yes	No	No
readandrunwithassistant	Yes (with persona)	Yes	No	No
readwrite	Yes	Yes	No	Yes
admin	Yes	Yes	Yes	Yes

• Workspace chat uses the persona_name parameter to select which AI Assistant to use.
• Tool Builder script execution (run_script, run_script_and_wait) requires admin access.
• Committing SLXs requires admin or readwrite.