@waroom.co/mcp

What it is

@waroom.co/mcp is a Model Context Protocol (MCP) server that proxies the Waroom tRPC incident-management API. It exposes Waroom's incident, insights, alarm, service, and team operations as MCP tools so that MCP-capable clients (Claude Desktop, Cursor, MCP Inspector, etc.) can drive your Waroom organization directly.

The server speaks Streamable HTTP only. It is not a stdio server and it does not implement OAuth. Clients connect over HTTP and authenticate with a long-lived Personal Access Token (PAT).

Quick start (via npx)

WAROOM_API_URL=https://your-waroom-api/trpc npx @waroom.co/mcp

This starts the server listening on :4100. Clients connect to POST http://localhost:4100/mcp.

A health check is available at GET /healthz, which returns:

{ "ok": true }

Auth

The server authenticates every request with a Waroom Personal Access Token (PAT) of the form wmcp_<selector>.<secret>.

1. Create a PAT in the Waroom web app at /settings/profile/mcp. The token is shown once with a copy-once UX — copy it immediately and store it securely.

2. Pass it to the MCP server as a bearer token:

   Authorization: Bearer wmcp_<selector>.<secret>

3. Revoke a PAT at the same page (/settings/profile/mcp) when it is no longer needed.

PATs are long-lived — they do not expire on their own and remain valid until revoked.

Environment

| Variable | Required? | Default | Description | | --------------- | --------- | --------- | ----------------------------------------------------------------- | | WAROOM_API_URL| Yes | (none) | The Waroom tRPC base URL, e.g. https://your-waroom-api/trpc. | | MCP_PORT | No | 4100 | Port the MCP server listens on. | | MCP_HOST | No | 0.0.0.0 | Host/interface the MCP server binds to. |

Connecting a client

The server uses the Streamable HTTP transport.

• URL: http://localhost:4100/mcp
• Method: POST (the transport is stateless; GET and DELETE on /mcp return 405).
• Auth header: Authorization: Bearer wmcp_<selector>.<secret>

This is NOT a stdio server and it does NOT use OAuth. Configure your client as a remote/HTTP MCP server with a bearer header.

MCP Inspector

1. Run the server: WAROOM_API_URL=https://your-waroom-api/trpc npx @waroom.co/mcp
2. Launch the Inspector: npx @modelcontextprotocol/inspector
3. Set Transport Type to Streamable HTTP.
4. Set the URL to http://localhost:4100/mcp.
5. Add a request header Authorization with value Bearer wmcp_<selector>.<secret>.
6. Connect and browse the tool catalog.

Claude Desktop / Cursor (remote MCP)

Add an entry pointing at the running server with the bearer header:

{
  "mcpServers": {
    "waroom": {
      "url": "http://localhost:4100/mcp",
      "headers": {
        "Authorization": "Bearer wmcp_<selector>.<secret>"
      }
    }
  }
}

Tool catalog

Tools are underscore-named and grouped by domain.

Incidents

• incident_list_types — List the incident types configured for the org.
• incident_declare — Declare (create) a new incident.
• incident_list — List incidents.
• incident_get — Get a single incident by ID.
• incident_update_summary — Update an incident's summary.
• incident_rename — Rename an incident.
• incident_transition_status — Move an incident to a new status.
• incident_update_custom_fields — Set custom-field values (sparse merge); use to fill fields required on a later status before transitioning.
• incident_change_severity — Change an incident's severity.
• incident_assign_role — Assign a user to an incident role.
• incident_post_status_update — Post a status update to an incident.

Insights

• insights_incident_metrics — Aggregate incident metrics.
• insights_incident_trend — Incident trend over time.
• insights_oncall — On-call insights. Requires the on-call plan feature.

Alarms

All alarm tools require the on-call plan feature.

• alarms_list — List alarms.
• alarms_get — Get a single alarm.
• alarms_ack — Acknowledge an alarm.
• alarms_resolve — Resolve an alarm.
• alarms_link_to_incident — Link an alarm to an incident.

Services

Mutations (create, update, delete) require org admin.

• services_list — List services.
• services_get — Get a single service.
• services_create — Create a service. (org admin)
• services_update — Update a service. (org admin)
• services_delete — Delete a service. (org admin)

Teams

Mutations require org admin or team lead (team-scoped tools allow org admin OR the team's lead).

• teams_list — List teams.
• teams_create — Create a team. (org admin or team lead)
• teams_update — Update a team. (org admin or team lead)
• teams_delete — Delete a team. (org admin or team lead)
• teams_list_members — List a team's members.
• teams_add_member — Add a member to a team. (org admin or team lead)
• teams_remove_member — Remove a member from a team. (org admin or team lead)
• teams_set_member_role — Set a member's role within a team. (org admin or team lead)
• teams_set_default_escalation_policy — Set a team's default escalation policy. (org admin or team lead)

Error codes

Errors are returned as JSON-RPC errors with the following codes:

| Code | Meaning | | -------- | ------------------- | | -32001 | Unauthorized | | -32002 | Forbidden | | -32602 | Invalid params | | -32600 | On-call not enabled | | -32000 | Other |

Rate limits

MCP traffic is rate-limited per organization, enforced server-side on the Waroom tRPC API. This budget is separate from the public /v1 REST API budget.

• Default: 120 requests per org per minute.
• When the cap is exceeded, the API returns a tRPC TOO_MANY_REQUESTS error and the MCP tool call fails. Retry after a short backoff.

The limit is configured via env vars on the Waroom API (not the MCP client):

| Variable | Default | Description | | ------------------------- | ------- | ---------------------------------------------------- | | MCP_RATE_LIMIT_MAX | 120 | Per-org, per-minute request cap. | | MCP_RATE_LIMIT_DISABLED | (unset) | Set to true to disable MCP rate limiting entirely. |

Local development

pnpm --filter @waroom.co/mcp dev      # run the server in watch mode
pnpm --filter @waroom.co/mcp test     # run the test suite
pnpm --filter @waroom.co/mcp inspect  # launch against the MCP Inspector

Security note

PATs are long-lived and do not expire on their own — treat them as secrets, scope their distribution carefully, and revoke them promptly at /settings/profile/mcp when no longer needed.

The underlying /trpc API is rate-limited per organization (see Rate limits). Still, avoid exposing the MCP server on untrusted networks and be mindful of high-volume tool usage.