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_incidentswith 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_idscontaining public service keys likesvc_K7M4Q9TZ2H, not internal UUIDs. runframe_get_servicenow looks up services by publicservice_key, not UUID.- Incident tools now follow the latest V1 contract: use incident numbers like
INC-2026-001in path parameters. - Incident update and list filters now use the latest public identifiers where V1 does: assignee/resolver email and
team_name. runframe_create_incidentaccepts an optionalidempotency_key, which is forwarded as theIdempotency-Keyheader for retry-safe creates.runframe_create_incidentdefaultsseveritytoSEV2when omitted, matching the V1 API.- Incident create now mirrors the V1 API limits:
titlemust be 1-200 chars,descriptionmaxes at 10000 chars, andservice_idsallows 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_servicesto discover validservice_keyvalues before creating incidents. runframe_page_someonenow uses the latest V1 delivery contract:email,channels, and optionalmessage.- Postmortem tools now follow the latest V1 contract: use
incident_numberand snake_case nested fields likeusers_affected,owner_email, andtime_to_acknowledge. - Use
runframe_find_userto resolve a person name to an email address before filtering incidents byassigned_toorresolved_by. - Set
include_inactive=trueonrunframe_find_userwhen you need to resolve former employees in historical incident queries. - Set
is_active=trueoris_active=falseonrunframe_find_userwhen you need an explicit V1 active-state filter. - Use
runframe_list_teamswithsearchto resolve the exactteam_namebefore 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_TOKENregularly. 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:
- Set
MCP_ACCESS_TOKEN=new_token,old_token - Update clients to
new_token - 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.
