Connect Openstatus to opencode (MCP Setup Guide)

Sep 08, 2026 | by openstatus | [education]

TL;DR — Add six lines to opencode.json, run opencode mcp auth openstatus, and opencode can drive your status pages: list incidents, draft updates, and schedule maintenance from your terminal. No key to paste. Every mutation is audit-logged under actor_type = 'mcp' and notifications never fire unless you explicitly approve.

opencode is an open-source coding agent for the terminal, model-agnostic and configured from a single JSON file. The Model Context Protocol (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 two-minute setup.

Why connect Openstatus to opencode?

Status page work usually lands while you're already debugging in a terminal. Connecting openstatus to opencode 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 opencode session you used to ship the change.
• Read-only audits — a teammate connects with read-only access; their opencode can summarize page health and monitor status with zero mutation risk.

The same server works with Claude Code, Claude Desktop, Codex, ChatGPT, Cursor, and any other MCP-compatible client.

Prerequisites

• An openstatus account with at least one status page.
• opencode installed (opencode --version should print a version).

Step 1: Add the MCP server

opencode has no mcp add command — remote servers are declared in the config file. Add an openstatus entry under the mcp key of opencode.json at your project root, or ~/.config/opencode/opencode.json to make it available in every project:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "openstatus": {
      "type": "remote",
      "url": "https://api.openstatus.dev/mcp",
      "enabled": true
    }
  }
}

"type": "remote" tells opencode this is an HTTP endpoint rather than a local process to spawn. "enabled": false is the switch to park the server without deleting the entry.

The project file is safe to commit: it holds no secret. Tokens live in ~/.local/share/opencode/mcp-auth.json on each machine, so every teammate signs in with their own openstatus account the first time they use it.

Step 2: Sign in

Run:

opencode mcp auth openstatus

opencode also starts this flow on its own the first time the server answers 401, so you can skip straight to a prompt and authenticate when asked.

Your browser opens the openstatus consent screen:

• Workspace — the workspace this connection can reach. If you belong to several, pick one; authenticate again to switch.
• Access — Read-only lets opencode list status pages, reports, monitors, and maintenance windows. Read & write also lets it create reports, append updates, resolve incidents, and schedule maintenance.

Click Approve. opencode stores the token and refreshes it in the background; you won't be asked again unless the connection is revoked.

Step 3: Verify the connection

Run:

opencode mcp list

openstatus should be listed as connected and authenticated. With read-only access the session exposes list_status_pages, list_status_reports, list_maintenances, list_monitors, and the other read tools. With read & write you also get 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 connections, so a misconfigured client cannot call them.

If something looks wrong, opencode mcp debug openstatus prints the connection and OAuth diagnostics.

Step 4: Run your first prompt

Try a read tool first:

> list my openstatus status pages

opencode calls list_status_pages, asks for your approval, and returns the slugs and ids in your workspace.

With write access, draft an incident — opencode 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.

Headless setups: use an API key

OAuth needs a browser on the same machine. In CI, on a remote box, or inside a container, pass an API key instead. Create one in Settings > API Tokens (scopes are immutable on a key) and add it as a header. opencode substitutes {env:VAR} in config values, so the secret stays out of the file:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "openstatus": {
      "type": "remote",
      "url": "https://api.openstatus.dev/mcp",
      "enabled": true,
      "headers": {
        "x-openstatus-key": "{env:OPENSTATUS_API_KEY}"
      },
      "oauth": false
    }
  }
}

Export OPENSTATUS_API_KEY in the environment and opencode resolves it at connection time. "oauth": false stops opencode from trying to open a browser when a call is rejected.

Built-in safeguards

Four properties make this safe enough for a real incident:

• Workspace-scoped consent — the token only reaches the workspace you approved, with the access level you chose. You can downgrade a client that asks for write access to read-only on the consent screen.
• 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 (the connection) and actor_user_id (the user who approved it), so AI-driven actions are traceable as a separate slice. Connecting and revoking are audited too.

Disconnecting

Open Settings > Integrations > Connected apps in the dashboard. Each connection shows the client, its access, who connected it, and when it was last used. Revoke it and opencode's next call fails with 401; run opencode mcp auth openstatus to reconnect. Members revoke their own connections; owners and admins can revoke any. Removing a member from the workspace revokes their connections automatically.

To drop the credential on your side without touching the dashboard, run opencode mcp logout openstatus. To remove the server entirely, delete the openstatus entry from your config.

Troubleshooting

• opencode mcp list shows openstatus as unauthenticated. Run opencode mcp auth openstatus again. Sanity-check reachability with curl -i -H "Accept: text/event-stream" https://api.openstatus.dev/mcp — a 401 with a WWW-Authenticate header means the server is up and waiting for a sign-in.
• The browser never opens. opencode prints the authorization URL; open it in a browser on the same machine, since the callback lands on a loopback port opencode listens on. For remote sessions, use an API key.
• "Tool not available" when creating an incident. Your connection is read-only. Authenticate again and pick Read & write.
• Tools don't appear after editing the config. opencode reads the config at startup; start a new session. Check "enabled" is true and that the JSON parses.
• The server times out while listing tools. Raise "timeout" on the entry; it defaults to 5000 milliseconds.

What's next?

• MCP Server Reference — full tool schema, error codes, OAuth endpoints, and scope mechanics.
• Connect to Claude Code — the same setup for Anthropic's terminal agent.
• Connect to Codex — the same setup for OpenAI's terminal agent.
• Openstatus CLI — for terminal workflows that don't need an LLM in the loop.
• Slack Agent — for teams that live in Slack.

Frequently asked questions

Start free. No credit card required. Configure opencode to drive your status pages in under 5 minutes.