MCP Server

The RunWhen Platform MCP Server connects AI coding agents to the RunWhen platform over the Model Context Protocol (MCP). It works with Cursor, VS Code (GitHub Copilot), Claude Desktop, Claude Code, Continue, OpenAI Codex, Google Gemini CLI, and any other MCP-compatible client.

What it does

The MCP server gives your coding agent direct access to three categories of RunWhen functionality:

Category	What you can do
Workspace intelligence	Ask the RunWhen AI assistant about infrastructure, search issues, browse SLXs, review run sessions, and explore resource relationships.
Chat rules and commands	Create and manage chat rules and slash-commands that customize how your AI Assistants behave.
Task authoring (Tool Builder)	Write bash or Python scripts, validate them against the RunWhen contract, test against live infrastructure, and commit them as SLXs — all from your IDE.

Why use it

Without the MCP server, interacting with RunWhen means switching between your IDE and the RunWhen web UI. With it, your coding agent can:

Investigate infrastructure issues by asking the RunWhen AI assistant directly from your editor
Build and test automation tasks without leaving your coding workflow
Commit production-ready SLXs that run on a schedule or on-demand
Search and triage across workspaces, issues, tasks, and run sessions using natural language

How it works

You can connect in two ways:

Local (stdio) — A lightweight Python process runs on your machine next to your IDE. Your MCP client launches runwhen-platform-mcp and talks to it over the standard MCP stdio transport. You set RUNWHEN_TOKEN and RW_API_URL in the client config (or environment).

Remote (HTTP) — For beta, RunWhen hosts the MCP server at https://mcp.beta.runwhen.com/mcp: your IDE uses that URL and sends your RunWhen token in the Authorization header — no local Python install. You can also run the same server yourself if you need a private deployment.

IDE (Cursor, VS Code, Claude Desktop)
  │
  ├── Option A: MCP (stdio) ──▶ runwhen-platform-mcp (local)
  │         or
  │     Option B: MCP (HTTP) ──▶ runwhen-platform-mcp (hosted) ──┐
  │                                                               │
  │                                ┌──────────────────────────────┘
  │                                ▼
  │                    RunWhen platform APIs — issues, SLXs, runners,
  │                    workspace chat, rules, commands, Tool Builder
  │
  └── You see results inline in your editor

Whether local or remote, the session uses your RunWhen account permissions. All actions respect workspace RBAC.

Supported clients

The server works with any client that supports MCP over stdio (local command) or HTTP (remote URL), depending on what your editor implements:

Cursor — .cursor/mcp.json or MCP settings (local command or remote URL)
VS Code (GitHub Copilot) — .vscode/mcp.json or user mcp.servers (local or remote where supported)
Claude Desktop — claude_desktop_config.json per OS; local or remote URL (setup)
Claude Code — Anthropic’s CLI; stdio or HTTP MCP (CLI requirements)
Continue, Codex, Gemini CLI, and other terminal or IDE clients that implement MCP

See Installation & Setup for quick start, tokens, remote URL configuration, and the full requirements table.

Requirements

RunWhen account with an API token (how to get a token)
An MCP-compatible client (stdio and/or HTTP, depending on how you connect)
Local (stdio) mode: Python 3.10+, pip install runwhen-platform-mcp, and runwhen-platform-mcp on your PATH or configured with a full path — see Requirements
Remote (HTTP) mode: A client that supports streamable HTTP MCP and Bearer auth; no local Python install — see Remote server (HTTP)
Claude Desktop: correct claude_desktop_config.json path and a full app restart after edits — see Claude Desktop
CLI clients: same credentials as above; follow each tool’s MCP registration (for example Claude Code MCP) — see CLI and terminal-based clients

Next steps

Page	Description
Installation & Setup	Install the server and configure your MCP client
Tool Reference	Complete list of available tools and what they do
Tool Builder	End-to-end workflow for building and committing automation tasks