From 49c689e483bed703468fcd6cbc427597eb320e92 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 20 Jul 2026 19:03:47 +0000 Subject: [PATCH] Document the MCP server Adds a guide page covering how to enable the MCP server, authenticate with API keys, connect agents over streamable HTTP, and the full list of tools with their required permissions. Also documents the new "MCP Server Settings" section on the settings page. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LaKcQwMrtgwQwKgsXr3cqJ --- docs.json | 1 + v3.x/configuration/cachet.mdx | 16 +++ v3.x/guide/mcp.mdx | 196 ++++++++++++++++++++++++++++++++++ 3 files changed, 213 insertions(+) create mode 100644 v3.x/guide/mcp.mdx diff --git a/docs.json b/docs.json index 32d6874..8d15f7d 100644 --- a/docs.json +++ b/docs.json @@ -37,6 +37,7 @@ "v3.x/guide/metrics", "v3.x/guide/subscribers", "v3.x/guide/webhooks", + "v3.x/guide/mcp", "v3.x/guide/users", "v3.x/guide/dashboard" ] diff --git a/v3.x/configuration/cachet.mdx b/v3.x/configuration/cachet.mdx index ebe5a1e..d18c988 100644 --- a/v3.x/configuration/cachet.mdx +++ b/v3.x/configuration/cachet.mdx @@ -62,6 +62,22 @@ When the "Require Authentication" setting is enabled, read-only API endpoints al [API key](/v3.x/configuration/api-keys). By default, read-only endpoints are public and only write endpoints require authentication. +## MCP server + +Two settings control [Cachet's MCP server](/v3.x/guide/mcp), which lets AI agents manage your status page over the +Model Context Protocol: + +### Enable MCP server + +The "Enable MCP Server" setting controls whether the MCP server is available at all. When disabled, every MCP request +responds with a 404. The MCP server is disabled by default. + +### Require authentication + +When the "Require Authentication" setting is enabled, every MCP connection requires an +[API key](/v3.x/configuration/api-keys). When disabled, read-only tools are public and write tools still require an +API key with the matching permission. Authentication is required by default. + ## Other settings Cachet also provides additional settings to customize your status page. diff --git a/v3.x/guide/mcp.mdx b/v3.x/guide/mcp.mdx new file mode 100644 index 0000000..63d8417 --- /dev/null +++ b/v3.x/guide/mcp.mdx @@ -0,0 +1,196 @@ +--- +title: 'MCP server' +description: 'Connect AI agents to Cachet using the Model Context Protocol.' +icon: 'robot' +--- + +Cachet includes a built-in [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets AI agents, +such as Claude Code, Claude Desktop, and Cursor, operate your status page. Agents connected over MCP can manage +[components](/v3.x/guide/components), [incidents](/v3.x/guide/incidents), incident templates, +[schedules](/v3.x/guide/schedules), [metrics](/v3.x/guide/metrics), and [subscribers](/v3.x/guide/subscribers) — the +same capabilities as the Cachet dashboard. + +## Enabling the MCP server + +The MCP server is disabled by default. To enable it, go to the "Settings" section of your Cachet dashboard and turn on +the "Enable MCP Server" setting in the "MCP Server Settings" section. While the server is disabled, every MCP request +responds with a 404. + +Once enabled, the MCP server is available over the streamable HTTP transport at the `/mcp` path of your Cachet +installation: + +```text +https://status.example.com/mcp +``` + + + Whenever the "Enable MCP Server" setting is changed, the "Require Authentication" setting is switched back on, so + the server is never exposed publicly by accident. + + +## Authentication + +The MCP server uses the same [API keys](/v3.x/configuration/api-keys) as the Cachet API. Send the token as a bearer +token in the `Authorization` header: + +```text +Authorization: Bearer YOUR_KEY_HERE +``` + +The "Require Authentication" setting controls who may connect: + +- **Enabled (default)**: Every MCP connection requires an API key. Requests without a valid token receive a 401 response. +- **Disabled**: Read-only tools are public, matching the status page and the API. Write tools always require an API key + with the matching permission. + +The permissions on an API key determine which tools an agent can use. Write tools are only advertised to sessions +whose token holds the matching permission, so an agent connecting with a read-only key is only offered read-only tools. + +Unauthenticated sessions see exactly what a status page guest sees: components in hidden groups, disabled components, +and invisible incidents and schedules are excluded from results. Authenticated sessions can see all resources, +matching the Cachet API. + + + Create a dedicated API key for each agent with only the permissions it needs. For example, an incident response + agent may only need the "Manage Incidents" and "Manage Incident Updates" permissions. + + +## Connecting an agent + +### Claude Code + +```shell +claude mcp add --transport http cachet https://status.example.com/mcp --header "Authorization: Bearer YOUR_KEY_HERE" +``` + +### Other MCP clients + +Any MCP client that supports the streamable HTTP transport can connect with a configuration similar to: + +```json +{ + "mcpServers": { + "cachet": { + "type": "http", + "url": "https://status.example.com/mcp", + "headers": { + "Authorization": "Bearer YOUR_KEY_HERE" + } + } + } +} +``` + +## Available tools + +Read-only tools require no permission. Write tools require an API key holding the permission listed next to them. + +### Status + +| Tool | Required permission | +| ---- | ------------------- | +| `get_status` | None | + +### Components + +| Tool | Required permission | +| ---- | ------------------- | +| `list_components` | None | +| `get_component` | None | +| `create_component` | `components.manage` | +| `update_component` | `components.manage` | +| `delete_component` | `components.delete` | + +### Component groups + +| Tool | Required permission | +| ---- | ------------------- | +| `list_component_groups` | None | +| `create_component_group` | `component-groups.manage` | +| `update_component_group` | `component-groups.manage` | +| `delete_component_group` | `component-groups.delete` | + +### Incidents + +| Tool | Required permission | +| ---- | ------------------- | +| `list_incidents` | None | +| `get_incident` | None | +| `create_incident` | `incidents.manage` | +| `update_incident` | `incidents.manage` | +| `delete_incident` | `incidents.delete` | + +### Incident updates + +| Tool | Required permission | +| ---- | ------------------- | +| `record_incident_update` | `incident-updates.manage` | +| `edit_incident_update` | `incident-updates.manage` | +| `delete_incident_update` | `incident-updates.delete` | + +### Incident templates + +| Tool | Required permission | +| ---- | ------------------- | +| `list_incident_templates` | None | +| `create_incident_template` | `incident-templates.manage` | +| `update_incident_template` | `incident-templates.manage` | +| `delete_incident_template` | `incident-templates.delete` | + +### Schedules + +| Tool | Required permission | +| ---- | ------------------- | +| `list_schedules` | None | +| `get_schedule` | None | +| `create_schedule` | `schedules.manage` | +| `update_schedule` | `schedules.manage` | +| `delete_schedule` | `schedules.delete` | + +### Schedule updates + +| Tool | Required permission | +| ---- | ------------------- | +| `record_schedule_update` | `schedule-updates.manage` | +| `edit_schedule_update` | `schedule-updates.manage` | +| `delete_schedule_update` | `schedule-updates.delete` | + +### Metrics + +| Tool | Required permission | +| ---- | ------------------- | +| `list_metrics` | None | +| `get_metric` | None | +| `create_metric` | `metrics.manage` | +| `update_metric` | `metrics.manage` | +| `delete_metric` | `metrics.delete` | + +### Metric points + +| Tool | Required permission | +| ---- | ------------------- | +| `add_metric_point` | `metric-points.manage` | +| `delete_metric_point` | `metric-points.delete` | + +### Subscribers + +| Tool | Required permission | +| ---- | ------------------- | +| `list_subscribers` | `subscribers.manage` | +| `create_subscriber` | `subscribers.manage` | +| `update_subscriber` | `subscribers.manage` | +| `unsubscribe_subscriber` | `subscribers.delete` | + + + Every subscriber tool requires a permission, including `list_subscribers`, because subscriber data contains email + addresses. + + +## Rate limiting + +Cachet rate-limits the MCP server to 300 requests per minute per API key, or per IP address for unauthenticated +sessions. + + + You can override the default rate limit by setting the `CACHET_MCP_RATE_LIMIT` environment variable. +