# Runwhen Platform Mcp

> RunWhen Platform MCP Server

- **Type:** MCP server
- **Install:** `agentstack add mcp-runwhen-contrib-runwhen-platform-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [runwhen-contrib](https://agentstack.voostack.com/s/runwhen-contrib)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [runwhen-contrib](https://github.com/runwhen-contrib)
- **Source:** https://github.com/runwhen-contrib/runwhen-platform-mcp
- **Website:** https://www.runwhen.com

## Install

```sh
agentstack add mcp-runwhen-contrib-runwhen-platform-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://modelcontextprotocol.io) (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](https://github.com/runwhen-contrib/runwhen-platform-mcp) · [PyPI](https://pypi.org/project/runwhen-platform-mcp/) · **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 .
   ```

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

3. **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:

```json
{
  "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

```powershell
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`:

```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

```json
{
  "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)](https://docs.runwhen.com/docs/use/mcp-server/installation/#remote-server-http).

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

```json
{
  "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](https://code.visualstudio.com/) 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`
2. 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).
3. 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:

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

Or locally:

```bash
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`
3. **Token endpoint auth** — Use **client secret post** (`client_secret_post`), matching the server’s OIDC proxy configuration.
4. 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:

```json
{
  "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](https://github.com/runwhen-contrib)
- **Source:** [runwhen-contrib/runwhen-platform-mcp](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-runwhen-contrib-runwhen-platform-mcp
- Seller: https://agentstack.voostack.com/s/runwhen-contrib
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.