Installation & Setup

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

Requirements

Start with remote MCP (HTTP) if your editor supports it: RunWhen hosts beta at https://mcp.beta.runwhen.com/mcp — no Python install, no local process. Use local (stdio) when your client only supports spawning a command, or you deliberately run the server yourself.

Topic	Remote MCP (HTTP)	Local MCP (stdio)
RunWhen account	Required	Required
Auth	Bearer header or OAuth — Remote server (HTTP)	`RUNWHEN_TOKEN` + `RW_API_URL` — Quick start
MCP client	Streamable HTTP (remote URL)	stdio (local command)
Python	Not required	3.10+, `pip install …`, PATH or full path (venv notes)

Create Personal Access Tokens (or use other token flows) in Getting a token. Self-hosted remote MCP uses the same Remote column; optional server-side OAuth — GitHub README — OAuth for remote HTTP deployments.

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)

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

Remote (HTTP)

Add or merge a runwhen entry using url and headers.Authorization as in RunWhen-hosted MCP (beta).
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 — typically Authorization: Bearer …, or OAuth if the client supports it (OAuth sign-in (remote HTTP)).
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.

For remote MCP over HTTPS, you can authenticate in either of these ways:

Bearer token — Configure Authorization: Bearer … with a Personal Access Token or session JWT (same as above). Works with every client that supports remote MCP and custom headers.
OAuth (browser sign-in) — If your MCP client supports OAuth for remote servers, you can sign in with your RunWhen account in the browser instead of managing a long-lived token in config. RunWhen’s hosted MCP publishes OAuth metadata at https://mcp.<environment>.runwhen.com/.well-known/oauth-authorization-server (for example replace <environment> with beta). Your client uses that discovery document together with the MCP endpoint https://mcp.<environment>.runwhen.com/mcp.

OAuth is optional from your perspective: Bearer authentication remains fully supported. Availability depends on your editor or CLI — follow its docs for “OAuth”, “remote MCP”, or streamable HTTP with authorization-server discovery.

Self-hosted deployments can enable the same flow by setting server environment variables (MCP_BASE_URL, RunWhen OAuth client ID and secret) as described in the GitHub README — OAuth for remote HTTP deployments.

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, optional OAuth, and optional server-side DEFAULT_WORKSPACE).

Getting a token

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

Open the RunWhen UI at app.beta.runwhen.com
Go to Profile → Personal Tokens
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.

Environment variables

The MCP server reads configuration from environment variables. The most common ones for local (stdio) mode are shown in the Quick start config above. The full reference lives in the GitHub README — Environment variables; the most important ones are summarized here:

Connection

Variable	Required	Description
`RW_API_URL`	Yes	RunWhen API base URL (e.g. `https://papi.beta.runwhen.com`).
`RUNWHEN_TOKEN`	Yes	RunWhen API token (JWT or PAT).
`DEFAULT_WORKSPACE`	No	Default workspace so tools don’t need `workspace_name` every time.

Tool Builder & CodeCollection rendering

Variable	Required	Description
`MCP_GENERIC_CODECOLLECTION_REPO_URL`	No	Force a `rw-generic-codecollection` mirror URL for Tool Builder runbooks/SLIs (useful for airgap).
`MCP_GENERIC_CODECOLLECTION_REF`	No	Git ref for the generic codecollection mirror (default `main`).
`MCP_TOOL_BUILDER_RUNBOOK_REPO_URL` / `_REF` / `_PATH`	No	Override the Tool Builder runbook code bundle (repo URL, git ref, path to `.robot`).
`MCP_TOOL_BUILDER_SLI_REPO_URL` / `_REF` / `_PATH`	No	Override the Tool Builder SLI code bundle.
`RUNWHEN_SCRIPT_SOFT_MAX_BYTES`	No	Soft warning threshold for script payload size (default 10240 / 10 KB).
`RUNWHEN_SCRIPT_HARD_MAX_BYTES`	No	Hard cap — `commit_slx` / `run_script*` reject above this (default 65536 / 64 KB).

Registry & airgap

Variable	Required	Description
`RUNWHEN_REGISTRY_URL`	No	CodeBundle Registry URL (default `https://registry.runwhen.com`). Public, no auth.
`RUNWHEN_AIRGAP`	No	`true` for airgapped envs — `search_registry` / `get_registry_codebundle` return “registry disabled”.
`RUNWHEN_REGISTRY_TIMEOUT_S`	No	HTTP timeout in seconds for registry calls (default `10`).

HTTP transport (remote mode)

Variable	Required	Description
`MCP_TRANSPORT`	Yes (for HTTP)	`http` to enable remote mode (default `stdio`).
`MCP_HOST`	No	Bind address (default `0.0.0.0`).
`MCP_PORT`	No	Listen port (default `8000`).
`MCP_BASE_URL`	No	Public origin for OAuth redirects + discovery at `/.well-known/oauth-authorization-server`.

For the complete list (including polling intervals, artifact delays, OAuth client config, and Host/Origin guard settings), see the GitHub README.