Connecting AI assistants (MCP server)

CompleteStatus ships an MCP (Model Context Protocol) server, so AI assistants like Claude can query your monitors and their uptime, list and acknowledge incidents, read security grades, and mute alerts during a deploy — using your own words instead of curl.

Note: The MCP server requires the Business plan or above (the same tier as the REST API).

How it works

The server speaks JSON-RPC 2.0 over a single HTTP endpoint:

POST https://completestatus.com/api/mcp
Content-Type: application/json
Authorization: Bearer <api-key>

There is nothing to install on the CompleteStatus side — any MCP client that supports HTTP transport can connect.

1. Create an API key with the mcp scope

1. Go to /settings/api-keys (organization owner or admin).
2. Create a key and tick the mcp scope, plus the data scopes for the tools you want the assistant to use (see the table below — e.g. monitors:read and incidents:read for a read-only assistant).
3. Copy the token — it is shown only once.

Requests are rejected when the key lacks the mcp scope, has expired, or your plan doesn't include MCP. Each individual tool additionally requires its own data scope, so a key without incidents:write can list incidents but never acknowledge one. Everything is scoped to your organization.

2. Configure your MCP client

For Claude Code:

claude mcp add --transport http completestatus https://completestatus.com/api/mcp \
  --header "Authorization: Bearer wt_xxxxxxxx_..."

For clients configured via JSON, the equivalent is an HTTP server entry:

{
  "mcpServers": {
    "completestatus": {
      "type": "http",
      "url": "https://completestatus.com/api/mcp",
      "headers": { "Authorization": "Bearer wt_xxxxxxxx_..." }
    }
  }
}

The token may also be sent as an X-Api-Key header if your client can't set an Authorization header.

Available tools

Each tool wraps the same logic as the REST API, so results have the same JSON shapes and the same tenancy rules. get_security_grade returns the latest A+–F grade and score for your TLS-certificate and security-headers monitors — see Security-posture scans. get_uptime returns the same time-based uptime the REST API, your status pages and SLA reports show: without monitor_id it gives the figure across monitors plus each monitor's own. Like the API, it never reaches further back than the history your plan shows.

list_monitors and list_incidents are paginated. They accept an optional page (from 1) and per_page (1–100, default 100). When meta.current_page is less than meta.last_page, call the tool again with the next page to fetch the rest.

Example prompts

Once connected, just ask:

• "Check my monitors' status — is anything down right now?" → list_monitors with status: "down".
• "What open incidents do we have, and acknowledge the one on the API monitor." → list_incidents, then acknowledge_incident.
• "Post on the status page that we've identified the API issue and are rolling back, and email subscribers." → post_incident_update with notify: true.
• "What's the current security grade for the marketing site?" → get_security_grade.
• "What was the API's uptime over the last 7 days, day by day?" → get_uptime with days: 7 and daily: true.
• "I'm deploying project 1 for the next 15 minutes — mute its alerts. Reason: shipping v2." → create_maintenance_window with duration_min: 15.

Protocol details

For anyone building their own client: the endpoint implements the MCP protocol version 2024-11-05 (server info completestatus-mcp 1.0.0) with the methods initialize, ping, notifications/initialized, tools/list and tools/call.

List the tool catalogue by hand:

curl -s -X POST https://completestatus.com/api/mcp \
  -H "Authorization: Bearer $WT_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Call a tool:

curl -s -X POST https://completestatus.com/api/mcp \
  -H "Authorization: Bearer $WT_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"list_monitors","arguments":{"status":"down"}}}'

Protocol-level failures (unknown method, missing scope, invalid params) come back as JSON-RPC errors: -32700 parse, -32600 invalid request, -32601 method/tool not found, -32602 invalid params, -32603 internal, -32001 missing scope. Tool execution failures (e.g. an unknown monitor_id) follow the MCP convention instead: a successful result with isError: true and an explanatory text block, which assistants surface as a normal "that didn't work" answer. An unexpected internal failure returns a generic message with a support reference id (quote it to us) instead of the raw error.

The endpoint is rate-limited to 120 calls per minute per key. A JSON-RPC batch (an array of request objects) may hold at most 20 requests, and every item in it counts toward those 120 calls. An empty batch, or one with more than 20 requests, gets a single -32600 Invalid Request error and nothing in it runs. Batch items past the per-minute budget are not run: each gets its own JSON-RPC error -32000 "Rate limit exceeded".

Warning: An assistant with maintenance:write can silence your alerts, and one with incidents:write can acknowledge incidents and post public status-page updates (optionally emailing your subscribers). For a purely informational assistant, mint a key with only mcp, monitors:read and incidents:read.

Related guides

• The REST API — the underlying endpoints and key management.
• Teams and organizations — roles that may manage API keys.