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.

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 where to paste this JSON in Cursor, VS Code with Copilot, or Claude Desktop, see 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.