Skip to content
openstatus openstatus
Get started

Connect openstatus to Claude Code

What you’ll learn

Section titled “What you’ll learn”
Time~3 minutes
LevelBeginner
Prerequisitesopenstatus account, Claude Code 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

Section titled “Prerequisites”
  • An openstatus account (openstatus.dev)
  • Claude Code installed and signed in (claude --version)

What you’ll get

Section titled “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

Section titled “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

Section titled “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:

Terminal window
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

Section titled “Project-scoped alternative”

If you’d rather commit the configuration to your repo, create a .mcp.json at the project root:

{
  "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

Section titled “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 below.

4. Try your first prompt

Section titled “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

Section titled “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

Section titled “Troubleshooting”

/mcp shows openstatus as disconnected

Section titled “/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

Section titled “”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

Section titled “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?

Section titled “What’s next?”