Installation & Setup

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

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. The GitHub README covers where each client stores this config, source installs, Windows setup, and more.

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 Settings → Access Tokens → Create Token
3. Copy the token and use it as RUNWHEN_TOKEN

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 Engineering Assistant to use.
• Tool Builder script execution (run_script, run_script_and_wait) requires admin access.
• Committing SLXs requires admin or readwrite.