Open-source status page, incident response and uptime monitoring
TypeScript alertingincident-managementmcpmcp-servermonitoringmonitoring-as-codeobservabilityon-callopen-sourcesrestatus-pagestatuspagesynthetic-monitoringterraformtinybirdtursouptimeuptime-checkeruptime-monitor
chore: mcp claude content (#2143)
Maximilian Kaskee8307ca9baf6
diff --git a/apps/docs/astro.config.mjs b/apps/docs/astro.config.mjsindex 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.mdxindex 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 Cursordiff --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.mdxnew file mode 100644index 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.++<Aside type="tip">Start with a read-only key while you get familiar with the tools. You can issue a write key later — scopes are immutable on a given key, so you'll create a new one rather than upgrading.</Aside>++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+```++<Aside>Every mutation tool requires an explicit `notify: true | false`. Claude Code will ask whether to notify subscribers — answer before approving the tool call.</Aside>++## 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 loopdiff --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.mdxnew file mode 100644index 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.++<ButtonLink href="https://app.openstatus.dev">Try openstatus free</ButtonLink>++---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.mdxnew file mode 100644index 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.++<ButtonLink href="https://app.openstatus.dev">Try openstatus free</ButtonLink>++---