runframe-mcp-server

**Runframe** is the complete incident lifecycle platform for engineering teams, covering incident response, on-call, and status pages. This MCP server lets you manage those workflows from your IDE or AI agent.

17 tools covering incidents, on-call, services, postmortems, teams, and people lookup. Requires Node.js 20+.

Why Use This

• Stay in your editor — acknowledge incidents, page responders, and write postmortems without switching to a browser
• Let agents handle the routine — AI agents can triage, escalate, and update incidents autonomously using scoped API keys
• Zero infrastructure — runs via `npx`, no server to deploy for local use

How It Works

Your IDE / Agent
    ↓ (stdio or HTTP)
MCP Server (this package)
    ↓ (HTTPS, scoped API key)
Runframe API

The server is stateless. It translates MCP tool calls into Runframe API requests, scoped by your API key permissions. No data is stored locally.

Examples

Ask your agent:

• *"Acknowledge incident INC-2026-001"* → calls `runframe_acknowledge_incident`
• *"Who is on call right now?"* → calls `runframe_get_current_oncall`
• *"Create a postmortem for the database outage"* → calls `runframe_create_postmortem`
• *"Page the backend team lead about the API latency spike"* → calls `runframe_page_someone`
• *"List all open SEV1 incidents"* → calls `runframe_list_incidents` with severity filter
• *"Find Alex so I can check their open incidents"* → calls `runframe_find_user`

Install

Get your API key from settings inside Runframe.io, then add to your agent:

Claude Code:

claude mcp add runframe -e RUNFRAME_API_KEY=rf_your_key_here -- npx -y @runframe/mcp-server

Cursor (`~/.cursor/mcp.json`) · VS Code (`.vscode/mcp.json`) · Claude Desktop (`claude_desktop_config.json`):

{
  "mcpServers": {
    "runframe": {
      "command": "npx",
      "args": ["-y", "@runframe/mcp-server"],
      "env": { "RUNFRAME_API_KEY": "rf_your_key_here" }
    }
  }
}

Other MCP clients: Add the JSON config above to your client's MCP config file.

Interactive setup wizard:

npx @runframe/mcp-server --setup

Environment Variables

Transports

stdio (default) — used by MCP clients like Claude Code and Cursor. No network exposure. This is what the install commands above configure.

Streamable HTTP — for containerized or remote deployments. Requires `MCP_ACCESS_TOKEN` for bearer auth:

RUNFRAME_API_KEY=rf_... \
  MCP_ACCESS_TOKEN=your_token \
  npx @runframe/mcp-server --transport http --port 3100 --host 127.0.0.1

Security Model

Responsibility is split across three boundaries:

• Runframe API handles authorization and scopes via `RUNFRAME_API_KEY`.
• This MCP server handles process isolation (stdio) and bearer-token validation (HTTP). It also enforces method filtering, Host/Origin checks on localhost, declared Content-Length validation (1 MB limit), 8 KB header limit, and 15s upstream timeout.
• Your reverse proxy handles TLS, rate limiting, and streamed-body enforcement if you expose HTTP mode to a network.

The server stores nothing. It is a pass-through to the Runframe API.

Tools

Incidents (9)

On-call (1)

Services (2)

Postmortems (2)

Teams (2)

Users (1)

Direct API alignment

This MCP server follows the public Runframe direct API contract.

• Incident create requires `service_ids` containing public service keys like `svc_K7M4Q9TZ2H`, not internal UUIDs.
• `runframe_get_service` now looks up services by public `service_key`, not UUID.
• Incident tools now follow the latest V1 contract: use incident numbers like `INC-2026-001` in path parameters.
• Incident update and list filters now use the latest public identifiers where V1 does: assignee/resolver email and `team_name`.
• `runframe_create_incident` accepts an optional `idempotency_key`, which is forwarded as the `Idempotency-Key` header for retry-safe creates.
• `runframe_create_incident` defaults `severity` to `SEV2` when omitted, matching the V1 API.
• Incident create now mirrors the V1 API limits: `title` must be 1-200 chars, `description` maxes at 10000 chars, and `service_ids` allows at most 50 items.
• Incident creation depends on valid SLA configuration for the requested severity. If acknowledge or closure deadlines are missing, the API rejects the create.
• Use `runframe_list_services` to discover valid `service_key` values before creating incidents.
• `runframe_page_someone` now uses the latest V1 delivery contract: `email`, `channels`, and optional `message`.
• Postmortem tools now follow the latest V1 contract: use `incident_number` and snake_case nested fields like `users_affected`, `owner_email`, and `time_to_acknowledge`.
• Use `runframe_find_user` to resolve a person name to an email address before filtering incidents by `assigned_to` or `resolved_by`.
• Set `include_inactive=true` on `runframe_find_user` when you need to resolve former employees in historical incident queries.
• Set `is_active=true` or `is_active=false` on `runframe_find_user` when you need an explicit V1 active-state filter.
• Use `runframe_list_teams` with `search` to resolve the exact `team_name` before filtering incidents.

Docker

The Docker image runs HTTP transport by default on port 3100:

docker build -t runframe-mcp-server .
docker run -e RUNFRAME_API_KEY=rf_... -e MCP_ACCESS_TOKEN=your_token -p 3100:3100 runframe-mcp-server

Deploying HTTP Mode

HTTP mode is meant for private networks. If you put it on the internet:

• Run behind TLS (nginx, Caddy, cloud LB). This server does not do TLS.
• Use a reverse proxy for rate limiting and request buffering.
• Prefer private subnets or VPNs over public exposure.
• Rotate `MCP_ACCESS_TOKEN` regularly. Pass old and new tokens comma-separated for zero-downtime swaps.

Rate limiting

The Runframe API enforces rate limits server-side. If you hit a limit, tools return a 429 error with a retry hint. For HTTP transport deployments, your reverse proxy can add additional request-level throttling.

Token rotation

`MCP_ACCESS_TOKEN` accepts comma-separated tokens:

1. Set `MCP_ACCESS_TOKEN=new_token,old_token`

2. Update clients to `new_token`

3. Drop the old one: `MCP_ACCESS_TOKEN=new_token`

Limitations

• Read-only for schedules — you can query on-call and escalation policies but not modify them via MCP
• Requires a Runframe account and API key

Contributing

Issues and PRs welcome at github.com/runframe/runframe-mcp-server.

License

MIT — Runframe · npm