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 + +---