---
title: "Connect Openstatus to opencode (MCP Setup Guide)"
url: "https://www.openstatus.dev/guides/connect-openstatus-to-opencode"
date: "2026-09-08"
updated: "2026-09-08"
author: "openstatus"
description: "Wire the openstatus MCP server into opencode so the agent can list status pages, draft incidents, and schedule maintenance from your terminal — sign in with OAuth, no key to paste, with audit-logged mutations and explicit notify semantics."
category: "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](https://opencode.ai) is an open-source coding agent for the terminal, model-agnostic and configured from a single JSON file. 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 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](/guides/connect-openstatus-to-claude-code), [Claude Desktop](/guides/connect-openstatus-to-claude-desktop), [Codex](/guides/connect-openstatus-to-codex), [ChatGPT](/guides/connect-openstatus-to-chatgpt), Cursor, and any other MCP-compatible client.

## Prerequisites

- An [openstatus account](https://www.openstatus.dev) 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:

```json
{
  "$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:

```bash
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:

```bash
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 > General > API Keys** (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:

```json
{
  "$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](#headless-setups-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](/docs/reference/mcp-server)** — full tool schema, error codes, OAuth endpoints, and scope mechanics.
- **[Connect to Claude Code](/guides/connect-openstatus-to-claude-code)** — the same setup for Anthropic's terminal agent.
- **[Connect to Codex](/guides/connect-openstatus-to-codex)** — the same setup for OpenAI's terminal agent.
- **[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.

## Frequently asked questions

<details>
  <summary>Does opencode support remote MCP servers like openstatus?</summary>
  Yes. opencode supports local (stdio) and remote MCP servers. The openstatus MCP server is a stateless Streamable HTTP endpoint, added as an entry with `"type": "remote"` and `"url": "https://api.openstatus.dev/mcp"` under the `mcp` key of your opencode config.
</details>

<details>
  <summary>What can opencode do once the openstatus MCP server is connected?</summary>
  opencode can list status pages, status reports, monitors, 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 you picked when you approved the connection.
</details>

<details>
  <summary>Do I need an API key to connect opencode?</summary>
  No. The openstatus MCP server is an OAuth 2.1 authorization server. opencode starts the flow when the server answers `401`, or on demand with `opencode mcp auth openstatus`; you pick a workspace and an access level on the consent screen, and tokens are issued and refreshed automatically. An API key in the `x-openstatus-key` header still works for CI and headless agents.
</details>

<details>
  <summary>Where does opencode store the OAuth tokens?</summary>
  In `~/.local/share/opencode/mcp-auth.json`, outside your project. Nothing sensitive lands in `opencode.json`, so the config file is safe to commit and share with your team — each teammate signs in with their own account on first use.
</details>

<details>
  <summary>Can opencode accidentally notify subscribers when creating an incident?</summary>
  No. Every publishing tool (`create_status_report`, `add_status_report_update`, `resolve_status_report`, `create_maintenance`) requires an explicit `notify: true | false` field. opencode must show the notify choice before firing the tool, so an LLM cannot quietly fan out an alert by omitting the flag. `update_status_report` is metadata-only and has no notify path at all.
</details>

<details>
  <summary>How do I give opencode read-only access to my workspace?</summary>
  Pick **Read-only** on the consent screen. The MCP server filters write tools out of the `tools/list` response for read-only connections, so opencode sees only the read tools — status pages and page components, status reports, maintenances, monitors, response logs, notifications, private locations, and audit logs. None of the `create_*`, `update_*`, or `resolve_*` tools are registered for that session.
</details>

<details>
  <summary>How do I disconnect opencode from my workspace?</summary>
  Open **Settings > Integrations > Connected apps** in the openstatus dashboard and revoke the connection. 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. To drop the local credential without touching the dashboard, run `opencode mcp logout openstatus`.
</details>

<details>
  <summary>Where do MCP-driven changes appear in the audit log?</summary>
  Every mutation routed through the MCP server lands in the audit log under `actor_type = 'mcp'`, with `actor_id` set to the connection (`oat_<id>` for OAuth, the key id for an API key) and `actor_user_id` set to the user who approved the connection or created the key. This separates AI-driven actions from CLI, dashboard, and direct API mutations.
</details>

<details>
  <summary>Can I turn the server off without deleting the config?</summary>
  Yes. Set `"enabled": false` on the `openstatus` entry and opencode skips it at startup. Flip it back to `true` when you need the tools again; the stored credential survives.
</details>

---

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

[Try openstatus free](https://app.openstatus.dev)