From e8307ca9baf65eb460640f7024305d0bb432c2fc Mon Sep 17 00:00:00 2001
From: Maximilian Kaske <56969857+mxkaske@users.noreply.github.com>
Date: Fri, 8 May 2026 22:30:51 +0200
Subject: [PATCH] chore: mcp claude content (#2143)
---
apps/docs/astro.config.mjs | 4 +
.../src/content/docs/reference/mcp-server.mdx | 19 ++-
...w-to-connect-openstatus-to-claude-code.mdx | 139 +++++++++++++++
.../connect-openstatus-to-claude-code.mdx | 159 ++++++++++++++++++
.../connect-openstatus-to-claude-desktop.mdx | 151 +++++++++++++++++
5 files changed, 467 insertions(+), 5 deletions(-)
create mode 100644 apps/docs/src/content/docs/tutorial/how-to-connect-openstatus-to-claude-code.mdx
create mode 100644 apps/web/src/content/pages/guides/connect-openstatus-to-claude-code.mdx
create mode 100644 apps/web/src/content/pages/guides/connect-openstatus-to-claude-desktop.mdx
diff --git a/apps/docs/astro.config.mjs b/apps/docs/astro.config.mjs
index 563f3f7fc..bec616166 100644
--- a/apps/docs/astro.config.mjs
+++ b/apps/docs/astro.config.mjs
@@ -117,6 +117,10 @@ export default defineConfig({
label: "How to set up the Slack Agent",
slug: "tutorial/how-to-setup-slack-agent",
},
+ {
+ label: "Connect openstatus to Claude Code",
+ slug: "tutorial/how-to-connect-openstatus-to-claude-code",
+ },
{
label: "Manage Your Stack with Terraform and CLI",
slug: "tutorial/how-to-manage-openstatus-with-terraform-cli",
diff --git a/apps/docs/src/content/docs/reference/mcp-server.mdx b/apps/docs/src/content/docs/reference/mcp-server.mdx
index 498b6320d..001799e14 100644
--- a/apps/docs/src/content/docs/reference/mcp-server.mdx
+++ b/apps/docs/src/content/docs/reference/mcp-server.mdx
@@ -84,23 +84,32 @@ The tool's response includes a `notified: boolean` field so the assistant can co
## Configure Claude Desktop
+Claude Desktop launches MCP servers as local stdio processes, so the remote HTTP server is bridged through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) — a small open-source proxy that translates Claude Desktop's stdio calls into HTTP requests against `https://api.openstatus.dev/mcp`. You'll need Node.js 18+ on your PATH so Claude Desktop can run `npx`.
+
Add the server to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"openstatus": {
- "type": "http",
- "url": "https://api.openstatus.dev/mcp",
- "headers": {
- "x-openstatus-key": "os_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+ "command": "npx",
+ "args": [
+ "mcp-remote",
+ "https://api.openstatus.dev/mcp",
+ "--header",
+ "x-openstatus-key: ${API_KEY}"
+ ],
+ "env": {
+ "API_KEY": "os_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
}
}
```
-Restart Claude Desktop. The 8 openstatus tools appear in the tool picker.
+The API key is held in `env` and referenced via `${API_KEY}` in the `--header` value because `mcp-remote` parses header args before shell expansion — inlining the key after the colon breaks parsing.
+
+Fully quit and relaunch Claude Desktop (`Cmd+Q` on macOS, **File → Quit** on Windows). The openstatus tools appear in the tool picker after restart.
## Configure Cursor
diff --git a/apps/docs/src/content/docs/tutorial/how-to-connect-openstatus-to-claude-code.mdx b/apps/docs/src/content/docs/tutorial/how-to-connect-openstatus-to-claude-code.mdx
new file mode 100644
index 000000000..44fa7c812
--- /dev/null
+++ b/apps/docs/src/content/docs/tutorial/how-to-connect-openstatus-to-claude-code.mdx
@@ -0,0 +1,139 @@
+---
+title: Connect openstatus to Claude Code
+description: "Step-by-step tutorial to add the openstatus MCP server to Claude Code so the agent can read and manage your status pages from the terminal"
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+## What you'll learn
+
+| | |
+|---|---|
+| **Time** | ~3 minutes |
+| **Level** | Beginner |
+| **Prerequisites** | openstatus account, [Claude Code](https://docs.claude.com/en/docs/claude-code/overview) installed |
+
+In this tutorial, you'll connect the openstatus MCP server to Claude Code so the agent can list your status pages, draft incidents, and schedule maintenance windows directly from your terminal.
+
+### Prerequisites
+
+- An openstatus account ([openstatus.dev](https://www.openstatus.dev))
+- Claude Code installed and signed in (`claude --version`)
+
+### What you'll get
+
+By the end of this tutorial, you'll have:
+- An openstatus API key dedicated to Claude Code
+- The openstatus MCP server registered as a Claude Code tool
+- A working first prompt that lists your status pages
+
+## 1. Create an API key
+
+Open the openstatus dashboard, go to **Settings → API Tokens**, and click **Create Token**.
+
+Pick a scope:
+
+- **Read-only** — Claude Code can list status pages, reports, and maintenance windows but cannot create or modify anything. Best for exploration and on-call summaries.
+- **Read & write** — Claude Code can also create status reports, append updates, resolve incidents, and schedule maintenance.
+
+
+
+Copy the key (it starts with `os_`). You'll only see it once.
+
+## 2. Add the MCP server to Claude Code
+
+Claude Code talks to the openstatus MCP server over Streamable HTTP. Register it with the `claude mcp add` command:
+
+```bash
+claude mcp add \
+ --transport http \
+ --scope user \
+ --header "x-openstatus-key: os_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
+ openstatus \
+ https://api.openstatus.dev/mcp
+```
+
+The flags:
+
+- `--transport http` — the openstatus MCP server is a stateless HTTP endpoint, not a local stdio process.
+- `--scope user` — registers the server for every Claude Code session on your machine. Use `--scope project` if you want to commit a project-local `.mcp.json` so your team picks it up automatically (omit the header from the committed file and rely on `${OPENSTATUS_API_KEY}` expansion).
+- `--header "x-openstatus-key: …"` — the same API key the openstatus CLI, REST API, and Terraform provider use.
+
+### Project-scoped alternative
+
+If you'd rather commit the configuration to your repo, create a `.mcp.json` at the project root:
+
+```json
+{
+ "mcpServers": {
+ "openstatus": {
+ "type": "http",
+ "url": "https://api.openstatus.dev/mcp",
+ "headers": {
+ "x-openstatus-key": "${OPENSTATUS_API_KEY}"
+ }
+ }
+ }
+}
+```
+
+Then export `OPENSTATUS_API_KEY` in your shell. Claude Code expands the variable at connection time, so the key never lands in version control.
+
+## 3. Verify the connection
+
+Open Claude Code and run:
+
+```
+/mcp
+```
+
+You should see `openstatus` listed as **connected**, with the registered tools (`list_status_pages`, `list_status_reports`, `list_maintenances`, and — if your key has write scope — `create_status_report`, `add_status_report_update`, `update_status_report`, `resolve_status_report`, `create_maintenance`).
+
+If the server shows as disconnected, see [Troubleshooting](#troubleshooting) below.
+
+## 4. Try your first prompt
+
+Ask Claude Code something that exercises a read tool:
+
+```
+> list my openstatus status pages
+```
+
+Claude Code will call `list_status_pages`, prompt you to approve the call, and return the page slugs and ids in your workspace.
+
+If you have a write-scoped key, try drafting an incident — Claude Code will show you the title, status, message, and notify choice **before** firing the tool, so nothing reaches subscribers without an explicit approval:
+
+```
+> draft a status report on my "api" page: investigating elevated latency on the payment endpoint
+```
+
+
+
+## What you've accomplished
+
+- ✅ Created an openstatus API key scoped for Claude Code
+- ✅ Registered the openstatus MCP server with `claude mcp add`
+- ✅ Verified the connection with `/mcp`
+- ✅ Ran your first read and (optionally) write tool calls
+
+## Troubleshooting
+
+### `/mcp` shows openstatus as disconnected
+
+1. **Re-check the header:** run `claude mcp list` and confirm the `x-openstatus-key` value matches a key visible in **Settings → API Tokens**. Whitespace and trailing newlines are common copy-paste failures.
+2. **Reachability:** `curl -i -H "x-openstatus-key: os_..." https://api.openstatus.dev/mcp` should return a `200` with a `mcp-session-id` header. A `401` means the key is wrong or revoked; a network error means a proxy or firewall is blocking the connection.
+3. **Re-add the server:** `claude mcp remove openstatus` then re-run the `claude mcp add` command from step 2.
+
+### "Tool not available" when asking Claude Code to create an incident
+
+Your API key is read-only. Claude Code only sees the `list_*` tools — the server filters mutation tools out of `tools/list` for read-only keys. Issue a new key with **Read & write** scope and re-add the server.
+
+### Audit log shows `actor_type = 'mcp'` for changes I made manually
+
+That's expected — every mutation routed through Claude Code (or any other MCP client) is attributed to `mcp` in the audit log, with `actor_id` set to the API key id and `actor_user_id` set to the user who created the key. This is how openstatus separates AI-driven actions from CLI, dashboard, and API mutations.
+
+## What's next?
+
+- **[MCP Server Reference](/reference/mcp-server)** — full tool schema, error codes, and the contract behind the required `notify` flag
+- **[Connect to other MCP clients](/reference/mcp-server#configure-claude-desktop)** — the same API key works for Claude Desktop, Cursor, and any other MCP-compatible client
+- **[Get started with the openstatus CLI](/tutorial/get-started-with-openstatus-cli)** — for terminal workflows that don't need an LLM in the loop
diff --git a/apps/web/src/content/pages/guides/connect-openstatus-to-claude-code.mdx b/apps/web/src/content/pages/guides/connect-openstatus-to-claude-code.mdx
new file mode 100644
index 000000000..dde92b8ac
--- /dev/null
+++ b/apps/web/src/content/pages/guides/connect-openstatus-to-claude-code.mdx
@@ -0,0 +1,159 @@
+---
+title: "Connect Openstatus to Claude Code (MCP Setup Guide)"
+author: "openstatus"
+description: "Wire the openstatus MCP server into Claude Code so the agent can list status pages, draft incidents, and schedule maintenance from your terminal — with audit-logged mutations and explicit notify semantics."
+publishedAt: "2026-05-08"
+category: "education"
+howto:
+ totalTime: "PT3M"
+ steps:
+ - name: "Create an openstatus API key"
+ text: "Open Settings → API Tokens in the openstatus dashboard, click Create Token, and pick read-only or read & write scope."
+ url: "#step-1-create-an-api-key"
+ - name: "Register the MCP server with Claude Code"
+ text: "Run `claude mcp add --transport http --scope user --header \"x-openstatus-key: os_…\" openstatus https://api.openstatus.dev/mcp` to attach the openstatus tools to every Claude Code session."
+ url: "#step-2-register-the-mcp-server"
+ - name: "Verify the connection"
+ text: "In Claude Code, run /mcp and confirm openstatus is listed as connected with the expected tools (list_status_pages, list_status_reports, …)."
+ url: "#step-3-verify-the-connection"
+ - name: "Run your first prompt"
+ text: "Ask Claude Code to list your status pages or draft an incident. The agent will request approval before each tool call."
+ url: "#step-4-run-your-first-prompt"
+faq:
+ - question: "Does Claude Code support remote MCP servers like openstatus?"
+ answer: "Yes. Claude Code supports stdio, HTTP, and SSE transports. The openstatus MCP server is a stateless Streamable HTTP endpoint, registered with `claude mcp add --transport http`."
+ - question: "What can Claude Code do once the openstatus MCP server is connected?"
+ answer: "Claude Code can list status pages, status reports, and maintenance windows; create new status reports; append updates to existing reports; resolve reports; edit metadata; and schedule maintenance windows — all scoped to the workspace tied to your API key."
+ - question: "Do I need a separate MCP credential for Claude Code?"
+ answer: "No. Authentication is the standard `x-openstatus-key` header — the same API key the openstatus CLI, REST API, and Terraform provider use. There is no MCP-specific OAuth flow."
+ - question: "Can Claude Code accidentally notify subscribers when creating an incident?"
+ answer: "No. Every mutation tool requires an explicit `notify: true | false` field. Claude Code must show the notify choice before firing the tool, so an LLM cannot quietly fan out an alert by omitting the flag."
+ - question: "How do I give Claude Code read-only access to my workspace?"
+ answer: "Create an API key with `read` scope. The MCP server filters mutation tools out of the `tools/list` response for read-only keys, so Claude Code only sees `list_status_pages`, `list_status_reports`, and `list_maintenances`."
+ - question: "Where do MCP-driven changes appear in the audit log?"
+ answer: "Every mutation routed through the MCP server lands in the audit log under `actor_type = 'mcp'`, with `actor_id` set to the API key id and `actor_user_id` set to the user who created the key. This separates AI-driven actions from CLI, dashboard, and direct API mutations."
+ - question: "Can I commit the MCP configuration to my repository?"
+ answer: "Yes. Create a project-scoped `.mcp.json` at the repo root with the MCP server definition, and use `${OPENSTATUS_API_KEY}` for the header value so the secret stays out of source control."
+---
+
+**TL;DR** — Run one `claude mcp add` command with your openstatus API key and Claude Code can drive your status pages: list incidents, draft updates, and schedule maintenance from your terminal. Every mutation is audit-logged under `actor_type = 'mcp'` and notifications never fire unless you explicitly approve.
+
+---
+
+[Claude Code](https://docs.claude.com/en/docs/claude-code/overview) is an agent that lives in your terminal. The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) lets it reach out to remote services like openstatus — with the agent's host responsible for approval and audit. This guide walks through the three-minute setup.
+
+## Why connect Openstatus to Claude Code?
+
+Status page work usually lands while you're already debugging in a terminal. Connecting openstatus to Claude Code keeps the writing side of the workflow there too:
+
+- **During an incident** — draft an investigating-status update for the right page and approve it without opening the dashboard.
+- **At deploy time** — schedule a maintenance window from the same Claude Code session you used to ship the change.
+- **Read-only audits** — hand a teammate a read-scoped key so their Claude Code can summarize page health with zero mutation risk.
+
+The same key works with [Claude Desktop](/guides/connect-openstatus-to-claude-desktop), Cursor, ChatGPT, and any other MCP-compatible client.
+
+## Prerequisites
+
+- An [openstatus account](https://www.openstatus.dev) with at least one status page.
+- Claude Code installed (`claude --version` should print a version).
+
+## Step 1: Create an API key
+
+In the openstatus dashboard, go to **Settings → API Tokens** → **Create Token**. Pick a scope:
+
+- **Read-only** — Claude Code can only list status pages, reports, and maintenance windows.
+- **Read & write** — Claude Code can also create reports, append updates, resolve incidents, and schedule maintenance.
+
+Scopes are immutable on a key. Copy the value (starts with `os_`); you'll only see it once.
+
+## Step 2: Register the MCP server
+
+Claude Code talks to the openstatus MCP server over Streamable HTTP. Register it with `claude mcp add`:
+
+```bash
+claude mcp add \
+ --transport http \
+ --scope user \
+ --header "x-openstatus-key: os_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
+ openstatus \
+ https://api.openstatus.dev/mcp
+```
+
+- `--transport http` — required; the openstatus MCP server is a stateless HTTP endpoint, not a stdio process.
+- `--scope user` — registers the server for every Claude Code session. Use `--scope project` to ship the configuration with a specific repo.
+
+### Project-scoped alternative (`.mcp.json`)
+
+To commit the configuration to a repo so your team picks it up automatically, create `.mcp.json` at the project root:
+
+```json
+{
+ "mcpServers": {
+ "openstatus": {
+ "type": "http",
+ "url": "https://api.openstatus.dev/mcp",
+ "headers": {
+ "x-openstatus-key": "${OPENSTATUS_API_KEY}"
+ }
+ }
+ }
+}
+```
+
+Export `OPENSTATUS_API_KEY` in your shell — Claude Code expands it at connection time, so the key never lands in source control.
+
+## Step 3: Verify the connection
+
+In Claude Code, run:
+
+```
+/mcp
+```
+
+`openstatus` should be listed as **connected**. With a read-only key you'll see `list_status_pages`, `list_status_reports`, `list_maintenances`. With a read & write key you'll also see `create_status_report`, `add_status_report_update`, `update_status_report`, `resolve_status_report`, and `create_maintenance`. The server filters mutation tools out for read-only keys, so a misconfigured client cannot call them.
+
+## Step 4: Run your first prompt
+
+Try a read tool first:
+
+```
+> list my openstatus status pages
+```
+
+Claude Code calls `list_status_pages`, asks for your approval, and returns the slugs and ids in your workspace.
+
+With a write-scoped key, draft an incident — Claude Code shows you the title, status, message, and notify choice **before** firing:
+
+```
+> draft a status report on my "api" page: investigating elevated latency on the payment endpoint, do not notify subscribers yet
+```
+
+The agent resolves the page id via `list_status_pages`, presents the draft, and only calls `create_status_report` once you confirm.
+
+## Built-in safeguards
+
+Three properties make this safe enough for a real incident:
+
+- **Required `notify: boolean`** on every mutation tool — the schema rejects calls that omit it, so the LLM has to ask before firing. `notify: false` is a hard guarantee that no subscriber alert goes out.
+- **Lookup-before-mutate** — `create_status_report` and `create_maintenance` require a `pageId` resolved via `list_status_pages` rather than guessed.
+- **Audit log attribution** — every mutation lands in the audit log under `actor_type = 'mcp'`, with `actor_id` (key) and `actor_user_id` (the user who created the key), so AI-driven actions are traceable as a separate slice.
+
+## Troubleshooting
+
+- **`/mcp` shows openstatus as disconnected.** Run `claude mcp list` and verify the `x-openstatus-key` value matches a key in **Settings → API Tokens** (whitespace from copy-paste is the usual culprit). Sanity-check with `curl -i -H "x-openstatus-key: os_..." https://api.openstatus.dev/mcp` — a `200` plus `mcp-session-id` header means the key is good.
+- **"Tool not available" when creating an incident.** Your key is read-only. Issue a new **Read & write** key and re-run `claude mcp add`.
+
+## What's next?
+
+- **[MCP Server Reference](https://docs.openstatus.dev/reference/mcp-server)** — full tool schema, error codes, and scope mechanics.
+- **[Connect to Claude Desktop](/guides/connect-openstatus-to-claude-desktop)** — chat-shaped variant of this guide.
+- **[Openstatus CLI](/tooling/cli)** — for terminal workflows that don't need an LLM in the loop.
+- **[Slack Agent](/status-page#slack-agent)** — for teams that live in Slack.
+
+---
+
+Start free. No credit card required. Configure Claude Code to drive your status pages in under 5 minutes.
+
+Try openstatus free
+
+---
diff --git a/apps/web/src/content/pages/guides/connect-openstatus-to-claude-desktop.mdx b/apps/web/src/content/pages/guides/connect-openstatus-to-claude-desktop.mdx
new file mode 100644
index 000000000..1919e9b21
--- /dev/null
+++ b/apps/web/src/content/pages/guides/connect-openstatus-to-claude-desktop.mdx
@@ -0,0 +1,151 @@
+---
+title: "Connect Openstatus to Claude Desktop (MCP Setup Guide)"
+author: "openstatus"
+description: "Add the openstatus MCP server to Claude Desktop so the assistant can list status pages, draft incidents, and schedule maintenance from chat — with audit-logged mutations and explicit notify semantics."
+publishedAt: "2026-05-08"
+category: "education"
+howto:
+ totalTime: "PT3M"
+ steps:
+ - name: "Create an openstatus API key"
+ text: "Open Settings → API Tokens in the openstatus dashboard, click Create Token, and pick read-only or read & write scope."
+ url: "#step-1-create-an-api-key"
+ - name: "Edit claude_desktop_config.json"
+ text: "Add the openstatus MCP server under `mcpServers` in `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows). Claude Desktop launches MCP servers as local processes, so the remote HTTP server is bridged through `npx mcp-remote`."
+ url: "#step-2-edit-claude-desktop-config"
+ - name: "Restart Claude Desktop"
+ text: "Quit Claude Desktop fully and relaunch it so the new MCP server is registered. Reloading the window is not enough."
+ url: "#step-3-restart-claude-desktop"
+ - name: "Verify and run your first prompt"
+ text: "Open the tool picker, confirm the openstatus tools are listed, then ask Claude to list your status pages or draft an incident."
+ url: "#step-4-verify-and-run-your-first-prompt"
+faq:
+ - question: "Does Claude Desktop support remote MCP servers like openstatus?"
+ answer: "Yes, but indirectly. Claude Desktop launches MCP servers as local stdio processes, so a remote HTTP server like openstatus has to be bridged through `npx mcp-remote` — a small open-source proxy that translates Claude Desktop's stdio calls into HTTP requests. You configure `mcp-remote` once in `claude_desktop_config.json` and Claude Desktop treats openstatus like any other local server."
+ - question: "Where is claude_desktop_config.json on macOS and Windows?"
+ answer: "On macOS, the file lives at `~/Library/Application Support/Claude/claude_desktop_config.json`. On Windows, it lives at `%APPDATA%\\Claude\\claude_desktop_config.json`. Create the file if it does not exist."
+ - question: "Do I need a separate MCP credential for Claude Desktop?"
+ answer: "No. Authentication is the standard `x-openstatus-key` header — the same API key the openstatus CLI, REST API, and Terraform provider use. There is no MCP-specific OAuth flow."
+ - question: "Why don't I see the openstatus tools after editing the config?"
+ answer: "The two most common causes are not fully quitting Claude Desktop (it only loads MCP servers at launch — close the window is not enough, you have to Cmd+Q on macOS or File → Quit on Windows) and `npx` not being on the PATH that Claude Desktop sees. Install Node.js 18+ from nodejs.org if `node --version` is missing in your shell."
+ - question: "Can Claude Desktop accidentally notify subscribers when posting an incident?"
+ answer: "No. Every mutation tool requires an explicit `notify: true | false` field. Claude must show the notify choice before firing the tool, so an LLM cannot quietly fan out an alert by omitting the flag."
+ - question: "How do I give Claude Desktop read-only access to my workspace?"
+ answer: "Create an API key with `read` scope. The MCP server filters mutation tools out of the `tools/list` response for read-only keys, so Claude Desktop only sees `list_status_pages`, `list_status_reports`, and `list_maintenances`."
+ - question: "Where do MCP-driven changes appear in the audit log?"
+ answer: "Every mutation routed through Claude Desktop lands in the audit log under `actor_type = 'mcp'`, with `actor_id` set to the API key id and `actor_user_id` set to the user who created the key. This separates AI-driven actions from CLI, dashboard, and direct API mutations."
+---
+
+**TL;DR** — Drop a small `mcp-remote` block into `claude_desktop_config.json`, restart Claude Desktop, and the assistant can drive your status pages: list incidents, draft updates, and schedule maintenance from the chat window. Every mutation is audit-logged under `actor_type = 'mcp'` and notifications never fire unless you explicitly approve.
+
+---
+
+[Claude Desktop](https://claude.com/download) speaks the [Model Context Protocol](https://modelcontextprotocol.io) (MCP) — the open standard for letting AI assistants reach external services with explicit approval on every call. This guide wires the [openstatus MCP server](/tooling/mcp-server) into Claude Desktop so you can list status pages, post incident updates, resolve reports, and schedule maintenance windows without leaving the chat window.
+
+## Why connect Openstatus to Claude Desktop?
+
+If your incident workflow already runs through chat, Claude Desktop is the right drafting surface. Concrete scenarios:
+
+- **Drafting customer-facing copy** — turn engineer shorthand ("payment-api spiking p99 to 6s") into the calm, structured update your subscribers expect, then approve and post it without leaving the chat.
+- **On-call summaries** — "Summarize the last 7 days of incidents on my API page" in seconds, useful for weekly reviews and handoffs.
+- **Read-only audits** — issue a read-scoped key to a teammate; their Claude Desktop sees only the `list_*` tools and cannot mutate anything.
+
+The same key works with [Claude Code](/guides/connect-openstatus-to-claude-code), Cursor, ChatGPT, and any other MCP-compatible client.
+
+## Prerequisites
+
+- An [openstatus account](https://www.openstatus.dev) with at least one status page.
+- [Claude Desktop](https://claude.com/download) installed and signed in.
+- **Node.js 18+** on your PATH — Claude Desktop uses `npx` to launch the `mcp-remote` bridge. Confirm with `node --version`; install from [nodejs.org](https://nodejs.org) if missing.
+
+## Step 1: Create an API key
+
+In the openstatus dashboard, go to **Settings → API Tokens** → **Create Token**. Pick a scope:
+
+- **Read-only** — Claude Desktop can only list status pages, reports, and maintenance windows.
+- **Read & write** — Claude Desktop can also create reports, append updates, resolve incidents, and schedule maintenance.
+
+Scopes are immutable on a key. Copy the value (starts with `os_`); you'll only see it once.
+
+## Step 2: Edit `claude_desktop_config.json`
+
+Claude Desktop reads its MCP servers from a single JSON file:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+The fastest way to open it is from inside Claude Desktop: **Settings → Developer → Edit Config**. Create the file if it doesn't exist.
+
+Add the openstatus server under `mcpServers`:
+
+```json
+{
+ "mcpServers": {
+ "openstatus": {
+ "command": "npx",
+ "args": [
+ "mcp-remote",
+ "https://api.openstatus.dev/mcp",
+ "--header",
+ "x-openstatus-key: ${API_KEY}"
+ ],
+ "env": {
+ "API_KEY": "os_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+ }
+ }
+ }
+}
+```
+
+Two things worth knowing:
+
+- **Claude Desktop launches MCP servers as local processes**, so it can't talk to a remote HTTP endpoint directly. [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) is an open-source proxy that exposes a local stdio MCP server and forwards calls to the remote URL. `npx` runs it on demand — no global install.
+- **The API key lives in `env`, not inlined in `args`.** `mcp-remote` parses `--header` arguments before shell expansion, so a literal key after the colon breaks parsing. Holding it in `env.API_KEY` and referencing `${API_KEY}` in the header value is the documented workaround.
+
+## Step 3: Restart Claude Desktop
+
+Claude Desktop only loads MCP servers at launch. Quit fully (`Cmd+Q` on macOS, **File → Quit** on Windows) and reopen — reloading the window is not enough.
+
+## Step 4: Verify and run your first prompt
+
+Open a new chat and click the tool picker. With a read-only key you'll see `list_status_pages`, `list_status_reports`, `list_maintenances`. With a read & write key you'll also see `create_status_report`, `add_status_report_update`, `update_status_report`, `resolve_status_report`, and `create_maintenance`.
+
+Try a read tool first:
+
+```
+List my openstatus status pages
+```
+
+Claude calls `list_status_pages`, asks for approval, and returns the slugs and ids in your workspace. With a write-scoped key, draft an incident — Claude shows you the title, status, message, and notify choice **before** firing:
+
+```
+Draft a status report on my "api" page: investigating elevated latency on the payment endpoint, do not notify subscribers yet
+```
+
+## Built-in safeguards
+
+Three properties make this safe enough for a real incident:
+
+- **Required `notify: boolean`** on every mutation tool — the schema rejects calls that omit it, so the LLM has to ask before firing. `notify: false` is a hard guarantee that no subscriber alert goes out.
+- **Lookup-before-mutate** — `create_status_report` and `create_maintenance` require a `pageId` resolved via `list_status_pages` rather than guessed.
+- **Audit log attribution** — every mutation lands in the audit log under `actor_type = 'mcp'`, with `actor_id` (key) and `actor_user_id` (the user who created the key), so AI-driven actions are traceable as a separate slice.
+
+## Troubleshooting
+
+- **Tools don't appear after restart.** Validate the JSON (a trailing comma silently disables the whole `mcpServers` block) and confirm `npx` is on the PATH that Claude Desktop sees — `nvm`-managed Node sometimes isn't. Use the official nodejs.org installer if `node --version` is missing in your shell. Check **Settings → Developer → Open Logs Folder** for `mcp-remote` stderr.
+- **401 errors when calling a tool.** Verify the `x-openstatus-key` value matches a key in **Settings → API Tokens**. Sanity-check with `curl -i -H "x-openstatus-key: os_..." https://api.openstatus.dev/mcp`.
+
+## What's next?
+
+- **[MCP Server Reference](https://docs.openstatus.dev/reference/mcp-server)** — full tool schema, error codes, and scope mechanics.
+- **[Connect to Claude Code](/guides/connect-openstatus-to-claude-code)** — terminal-shaped variant of this guide.
+- **[Openstatus CLI](/tooling/cli)** — for terminal workflows that don't need an LLM in the loop.
+- **[Slack Agent](/status-page#slack-agent)** — for teams that live in Slack.
+
+---
+
+Start free. No credit card required. Configure Claude Desktop to drive your status pages in under 5 minutes.
+
+Try openstatus free
+
+---
--
knotmirror 0.0.1