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

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | RUNFRAME_API_KEY | Yes | — | API key (starts with rf_) | | RUNFRAME_API_URL | No | https://runframe.io | API base URL | | MCP_ACCESS_TOKEN | HTTP only | — | Bearer token for HTTP transport. Comma-separated for rotation (new_token,old_token). |

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)

| Tool | Scopes | Description | |------|--------|-------------| | runframe_list_incidents | incidents:read | List incidents with filters and pagination | | runframe_get_incident | incidents:read | Get incident by ID or number | | runframe_create_incident | incidents:write | Create an incident | | runframe_update_incident | incidents:write | Update title, description, severity, or assignment | | runframe_change_incident_status | incidents:write | Move to a new status (new, investigating, fixing, monitoring, resolved, closed) | | runframe_acknowledge_incident | incidents:write | Acknowledge (auto-assigns, tracks SLA) | | runframe_add_incident_event | incidents:write | Add a timeline entry | | runframe_escalate_incident | incidents:write | Escalate to the next policy level | | runframe_page_someone | incidents:write | Page a responder via Slack or email |

On-call (1)

| Tool | Scopes | Description | |------|--------|-------------| | runframe_get_current_oncall | oncall:read | Who is on call right now |

Services (2)

| Tool | Scopes | Description | |------|--------|-------------| | runframe_list_services | services:read | List services | | runframe_get_service | services:read | Get service details |

Postmortems (2)

| Tool | Scopes | Description | |------|--------|-------------| | runframe_create_postmortem | postmortems:write | Create a postmortem | | runframe_get_postmortem | postmortems:read | Get postmortem for an incident |

Teams (2)

| Tool | Scopes | Description | |------|--------|-------------| | runframe_list_teams | teams:read | List teams | | runframe_get_escalation_policy | oncall:read | Get escalation policy for a severity level |

Users (1)

| Tool | Scopes | Description | |------|--------|-------------| | runframe_find_user | users:read | Search users by name or email, with optional inactive-user support for historical lookups |

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