Runwhen Platform Mcp

RunWhen Platform MCP

RunWhen Platform MCP lets your coding agent (such as Cursor, Claude, Continue, or Copilot) talk to the RunWhen platform — workspace chat, issues, SLXs, run sessions, and the Tool Builder — over the Model Context Protocol (MCP).

[](https://pypi.org/project/runwhen-platform-mcp/) [](https://pypi.org/project/runwhen-platform-mcp/) [](https://opensource.org/licenses/Apache-2.0) [](https://modelcontextprotocol.io)

GitHub · PyPI · Tools (below)

---

Table of contents

• [Key features](#key-features)
• [Requirements](#requirements)
• [Getting started](#getting-started)
• [MCP client configuration](#mcp-client-configuration)
• [Cursor](#cursor)
• [VS Code (GitHub Copilot)](#vs-code-github-copilot)
• [Claude Desktop](#claude-desktop)
• [Other MCP clients](#other-mcp-clients)
• [Remote (HTTP) access](#remote-http-access)
• [OAuth for remote HTTP deployments](#oauth-for-remote-http-deployments)
• [Multiple environments](#multiple-environments)
• [Your first prompt](#your-first-prompt)
• [Tools](#tools)
• [Configuration](#configuration)
• [Environment variables](#environment-variables)
• [Getting a token](#getting-a-token)
• [Access control and "Run with Assistant"](#access-control-and-run-with-assistant)
• [Concepts](#concepts)
• [How it works](#how-it-works)
• [Infrastructure context (RUNWHEN.md)](#infrastructure-context-runwhenmd)
• [What's in this repo](#whats-in-this-repo)
• [Development and testing](#development-and-testing)
• [PyPI and container images](#pypi-and-container-images)
• [License](#license)

---

Key features

• Workspace chat: Ask the RunWhen AI assistant about your infrastructure. It has access to issue search, task/SLX search, run sessions, resource discovery, knowledge base, graphing, and Mermaid diagrams. Supports selecting an assistant (persona) via persona_name.
• Task authoring (Tool Builder): Write bash or Python scripts locally, validate them against the RunWhen contract, run them against live infrastructure, and commit them as SLXs. Use get_workspace_context to load RUNWHEN.md conventions before writing.
• Direct data access: List workspaces, issues, SLXs, run sessions; get runbooks and config index; search tasks and resources. Plus create and update chat rules and commands.

Requirements

• Python 3.10 or newer
• RunWhen account and API token (see [Getting a token](#getting-a-token))
• Any MCP client (Cursor, Claude Desktop, Continue, etc.)

Getting started

1. Install the server:

``bash pip install runwhen-platform-mcp ``

Or from source (use a venv and then point your MCP client at the venv’s runwhen-platform-mcp):

``bash git clone https://github.com/runwhen-contrib/runwhen-platform-mcp.git cd runwhen-platform-mcp python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -e . ``

1. Set environment variables (see [Configuration](#configuration)): RW_API_URL, RUNWHEN_TOKEN, and optionally DEFAULT_WORKSPACE.

1. Add the server to your MCP client using the config below. Replace your-jwt-token and your-workspace with your RunWhen token and workspace name.

Add the following to your MCP client config:

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

If you installed from source into a venv, use the full path to the venv’s runwhen-platform-mcp as command (e.g. /path/to/runwhen-platform-mcp/.venv/bin/runwhen-platform-mcp). Find it with which runwhen-platform-mcp after activating the venv.

---

MCP client configuration

Configure the RunWhen MCP server in your client as shown below. Use the JSON block from [Getting started](#getting-started); only the location of the config differs by client.

Cursor

Go to Cursor Settings → MCP → New MCP Server (or edit .cursor/mcp.json). Paste the config from [Getting started](#getting-started). If you use a venv, set command to the full path to .venv/bin/runwhen-platform-mcp.

VS Code (GitHub Copilot)

VS Code supports MCP servers through GitHub Copilot. Add the config to your workspace or user settings:

• Workspace: .vscode/mcp.json in your project root
• User: settings.json → "mcp.servers" key

Windows with venv

git clone https://github.com/runwhen-contrib/runwhen-platform-mcp.git
cd runwhen-platform-mcp
python -m venv .venv
.venv\Scripts\activate
pip install -e .

Then add to .vscode/mcp.json:

{
  "mcpServers": {
    "runwhen": {
      "command": "C:\\path\\to\\runwhen-platform-mcp\\.venv\\Scripts\\runwhen-platform-mcp.exe",
      "env": {
        "RW_API_URL": "https://papi.beta.runwhen.com",
        "RUNWHEN_TOKEN": "your-jwt-token",
        "DEFAULT_WORKSPACE": "your-workspace"
      }
    }
  }
}

Replace C:\\path\\to\\ with the actual path where you cloned the repo. To find the exact path, run where runwhen-platform-mcp in a terminal with the venv activated.

> Tip: On Windows, pip installs console scripts as .exe files in .venv\Scripts\. Always use the full absolute path with backslashes in the MCP config.

macOS / Linux with venv

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

Claude Desktop

Add the config to:

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

Use the same mcpServers.runwhen block as in [Getting started](#getting-started).

Other MCP clients

Any client that supports MCP over stdio can use this server. Register a local MCP server with:

• Command: runwhen-platform-mcp (or full path to the venv’s runwhen-platform-mcp if you installed from source)
• Env: RW_API_URL, RUNWHEN_TOKEN, and optionally DEFAULT_WORKSPACE

See your client’s docs for where to add MCP servers (e.g. Continue, Codex, Gemini CLI, etc.).

Remote (HTTP) access

The MCP server supports streamable HTTP so your editor can connect over HTTPS without a local Python install.

RunWhen-hosted MCP (beta)

RunWhen operates a shared endpoint for the beta environment:

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

Use your RunWhen beta JWT or Personal Access Token (same as local mode) in the Authorization header. Official docs: RunWhen MCP Server — Remote server (HTTP).

Example mcpServers block (all remote clients below use this shape):

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

> Important: Use /mcp with no trailing slash. The server redirects /mcp/ → /mcp, which can break some MCP clients.

> Workspace: Pass workspace_name on tools that support it when you need a specific workspace. RunWhen’s hosted service is configured for the beta API; self-hosted deployments often set DEFAULT_WORKSPACE in server environment variables.

Self-hosted remote MCP

To run the server yourself (Docker, Kubernetes, etc.), set url to your own hostname (for example https://mcp.your-domain.com/mcp) and the same Bearer token pattern. See Running the server in HTTP mode yourself below.

Cursor (remote)

1. Open Cursor Settings → MCP → New MCP Server, or edit .cursor/mcp.json in your project (or user config, depending on how you scope MCP).
2. Add the mcpServers.runwhen block above (https://mcp.beta.runwhen.com/mcp for hosted beta, or your self-hosted URL) and Bearer token.
3. Reload MCP / restart Cursor if the client does not pick up changes immediately.

Remote MCP support depends on your Cursor version; if url + headers are not accepted, use the local command install instead.

VS Code (GitHub Copilot) (remote)

1. Add the same mcpServers entry to .vscode/mcp.json (workspace) or to user settings.json under the key your VS Code build uses for MCP servers (for example mcp.servers — check VS Code MCP documentation for the current schema).
2. Use url and headers as in the JSON block above.

Availability of remote MCP in VS Code evolves with Copilot; confirm in release notes if url-based servers are enabled for your version.

Claude Desktop (remote)

1. Edit the Claude Desktop config file:

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

1. Merge the mcpServers.runwhen object from the JSON block above (hosted or self-hosted URL) into the top-level mcpServers map (alongside any other servers you already have).
2. Fully quit and restart Claude Desktop.

Other MCP clients

Any client that supports remote or HTTP MCP (streamable HTTP) can use the same url + headers pattern. For a local-only client, use the stdio command + env setup in [Getting started](#getting-started).

Running the server in HTTP mode yourself:

Using Docker:

docker run -p 8000:8000 \
  -e RW_API_URL=https://papi.beta.runwhen.com \
  ghcr.io/runwhen-contrib/runwhen-platform-mcp:latest

Or locally:

export MCP_TRANSPORT=http
export MCP_HOST=0.0.0.0
export MCP_PORT=8000
export FASTMCP_STATELESS_HTTP=true
export RW_API_URL=https://papi.beta.runwhen.com
runwhen-platform-mcp

The server exposes:

• /mcp/ — Streamable HTTP MCP endpoint (POST for tool calls, GET for SSE)
• /health — Health check (200 OK with version info)
• /livez — Kubernetes liveness probe

Authentication in HTTP mode: Each client sends credentials with the request — typically Authorization: Bearer (JWT or Personal Access Token). The server validates tokens against the RunWhen API. No RUNWHEN_TOKEN env var is required on the server when clients supply Bearer tokens; each user authenticates with their own token.

OAuth (browser sign-in) — When the server is configured with MCP_BASE_URL plus RunWhen OAuth client credentials (see [OAuth for remote HTTP deployments](#oauth-for-remote-http-deployments) below), MCP clients that support remote OAuth can complete sign-in in the browser instead of embedding a long-lived token. Bearer authentication remains supported for clients that do not use OAuth. Hosted beta exposes discovery at https://mcp.beta.runwhen.com/.well-known/oauth-authorization-server.

| Variable | Required | Description | |----------|----------|-------------| | MCP_TRANSPORT | Yes | Set to http to enable remote mode (default: stdio). | | MCP_HOST | No | Bind address (default: 0.0.0.0). | | MCP_PORT | No | Listen port (default: 8000). | | FASTMCP_STATELESS_HTTP | No | Set to true for horizontal scaling behind a load balancer. | | MCP_ALLOWED_HOSTS | No | Comma-separated Host allowlist for FastMCP's HostOriginGuardMiddleware. Only needed when the public hostname differs from MCP_BASE_URL's hostname (which is auto-added). Without a match, external requests are rejected with 421 Misdirected Request. | | MCP_HOST_ORIGIN_PROTECTION | No | Set to false to disable the Host/Origin guard middleware (defer to the ingress). Defaults to enabled. | | RW_API_URL | Yes | RunWhen API base URL. Used for token verification and API calls. |

> Note — 421 Misdirected Request troubleshooting. FastMCP 3.4+ ships a Host/Origin guard middleware whose default allow-list is loopback-only (127.0.0.1, localhost, ::1). Any request whose Host header doesn't match returns 421 Misdirected Request — including OAuth handshakes, which surfaces in Cursor as [Shared MCP process] Streamable HTTP error: Error POSTing to endpoint: Misdirected Request. This server automatically appends the MCP_BASE_URL hostname to the allow-list, so the OAuth-configured install works out of the box. If the public hostname on your ingress differs from MCP_BASE_URL (rare), set MCP_ALLOWED_HOSTS explicitly.

OAuth for remote HTTP deployments

Enable interactive OAuth alongside Bearer tokens by registering a confidential OAuth client with your RunWhen environment and pointing the MCP server at it.

1. MCP_BASE_URL — Public origin of this MCP server (no path), e.g. https://mcp.beta.runwhen.com. Required for OAuth redirects and discovery (/.well-known/oauth-authorization-server is served from this base).
2. RunWhen OAuth client — Create a confidential client whose authorization server matches your RW_API_URL (OpenID configuration at {RW_API_URL}/.well-known/openid-configuration). Register the redirect URI:

• {MCP_BASE_URL}/auth/callback

Example: https://mcp.beta.runwhen.com/auth/callback

1. Token endpoint auth — Use client secret post (client_secret_post), matching the server’s OIDC proxy configuration.
2. Set on the MCP server:

• MCP_PAPI_OAUTH_CLIENT_ID — client ID from step 2
• MCP_PAPI_OAUTH_CLIENT_SECRET — client secret from step 2

If these are unset, the server runs in JWKS + PAT/JWT verification only mode (Bearer tokens still work; no browser OAuth).

Legacy Auth0 path — Older deployments may set MCP_AUTH0_CONFIG_URL, MCP_AUTH0_CLIENT_ID, MCP_AUTH0_CLIENT_SECRET, and MCP_AUTH0_AUDIENCE instead of the RunWhen-native client variables above. Prefer RunWhen OAuth when available.

The consent screen shown during OAuth uses RunWhen branding (runwhen_platform_mcp/consent_ui.py).

Multiple environments

If you work across multiple RunWhen environments (e.g. beta and production, or separate workspaces), you can register multiple MCP servers. Important: only enable one at a time unless you specifically need cross-environment workflows — multiple active servers with identical tool names confuse LLM agents.

Use MCP_SERVER_LABEL to give each server a clear identity:

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

The server includes its label, environment, and workspace in its name and instructions so agents can route tool calls to the correct instance. See mcp-multi-env.json for a full example.

---

Your first prompt

After the server is connected, try:

What workspaces do I have access to?

or:

Summarize the current issues in my workspace.

Your client should call list_workspaces or get_workspace_issues and show the result. For the full chat experience, try:

Using workspace chat, what tasks are watching my production namespace?

---

Tools

The server exposes these tools, grouped by use case.

• Workspace intelligence (10 tools)
• `workspace

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: runwhen-contrib
• Source: runwhen-contrib/runwhen-platform-mcp
• License: Apache-2.0
• Homepage: https://www.runwhen.com

Install and usage instructions live in the source repository linked above.