> ## Documentation Index
> Fetch the complete documentation index at: https://docs.use.observer/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Observer runs a remote Model Context Protocol server at mcp.use.observer. Connect Claude, Cursor, VS Code, Codex, Gemini CLI or any MCP client and let an assistant set up status pages and Observer Agents, read your metrics, services, SLOs, incidents, and maintenance windows, and run operations. Sign in with OAuth or use an Observer API key.

Observer runs a remote **Model Context Protocol** server at `https://mcp.use.observer/mcp`.
It lets any MCP-compatible assistant (Claude, Cursor, VS Code, Codex, Gemini CLI, and other MCP
clients) work with your Observer data: read metrics, services, SLOs, status pages, incidents, and
maintenance windows, create the Observer Agents that collect your metrics, and run write
operations such as applying config or opening an incident.

Every tool maps one-to-one to a public API operation and is governed by the **same scopes and
the same plan entitlement** as the REST API. The server is stateless and holds no data: it
forwards each call to the API with the OAuth token or API key on the connection.

> [!NOTE]
>
> **Requirements**
>
> You need a plan that includes **public API access**, and either an MCP client that supports
> OAuth or an `obs_pub_` API key (create one under **Developers** > **API keys** in the console) with
> the scopes for the tools you intend to use.

## Connect

> [card] [Install in your client](https://docs.use.observer/docs/mcp/install.md)
>
> Claude, Claude Code, Cursor, VS Code, Codex and Gemini CLI, with OAuth.

> [card] [Connect with OAuth](https://docs.use.observer/docs/mcp/oauth.md)
>
> How sign-in, scopes, tokens and revocation work.

> [card] [Connect an AI agent](https://docs.use.observer/docs/mcp/connect-ai-agent.md)
>
> The agent requests its own scoped key; you approve one link.

Most clients only need the server URL: add `https://mcp.use.observer/mcp` with no header, and
the client opens Observer's sign-in page the first time. See
[Install in your client](https://docs.use.observer/docs/mcp/install.md) for the steps per client.

### With an API key

For a client without OAuth support, send an `obs_pub_` API key instead.

**1. Create an API key**

In the console, open **Developers** > **API keys**, create a key, and grant
only the scopes you need (see the catalog below). Copy the `obs_pub_…` value.

**2. Add the server to your MCP client**

The server speaks Streamable HTTP and reads your key
from the `Authorization` header. Most clients accept a remote server like this:

```json title="MCP client config" theme={null}
{
  "mcpServers": {
    "observer": {
      "url": "https://mcp.use.observer/mcp",
      "headers": { "Authorization": "Bearer obs_pub_your_key_here" }
    }
  }
}
```

Config shapes vary by client. Some expect a `"type": "http"` field alongside the `url`; check
your client's remote MCP documentation. The endpoint and the `Authorization: Bearer` header are
the same in every case. Keep the key out of files you commit.

**3. Confirm the connection**

Ask the assistant what it can do. It should call `getMe`, which needs no scope, and report the
key's scopes, your plan, quotas, and rate limits. If a later call fails with a scope message, add
the named scope to the key (or confirm your plan includes public API access).

> [!NOTE]
>
> **Scopes are the boundary**
>
> A tool only runs if the key carries its scope. Where the catalog lists several scopes (for
> example `write:metrics` or `write:config`), a key holding any one of them is enough. A call without the right scope returns an error
> naming the scope it needs. Give read-only keys for analysis, and scope write keys to just the
> operations you want an assistant to perform.

## First request

Once the server is connected, ask:

> Watch [https://your-site.com](https://your-site.com) and give me a status page.

Your coding agent creates a hosted check from Observer's own locations and replies with the
status page link. The first result arrives within about a minute and a half. Hosted checks are
an experimental feature and reach public addresses only (see
[Hosted checks](https://docs.use.observer/docs/guides/outside-in-checks.md)). To watch internal services, databases or
metrics, ask it to set up the [Observer Agent](https://docs.use.observer/agent/overview.md) instead.

## Endpoints

One server offers the full tool list and narrower views of it. Each view is a URL under
`https://mcp.use.observer/mcp`:

| URL | Tools |
| - | - |
| `/mcp` | Every tool. |
| `/mcp/readonly` | Tools that change nothing and need no write scope. |
| `/mcp/x/<toolsets>` | Tools in the listed toolsets, comma separated, for example `/mcp/x/incidents,metrics`. |
| `/mcp/x/<toolsets>/readonly` | Both filters: the read-only tools of the listed toolsets. |

Toolset names:

`account`, `agents`, `audit`, `change-events`, `config`, `incidents`, `maintenances`, `metrics`, `pages`, `services`, `sla`, `slos`. Each section of the [tool catalog](#tool-catalog) names its toolset.

An unknown toolset name returns `404` with the list of valid names.

Use a view to keep the tool list short, or to give an assistant a connection that cannot write.
A view filters the tools a client sees and can call; a tool outside the view answers
`Unknown tool`. The API still checks the scopes of the token or key on every call, so a view
narrows what an assistant is offered and is not a permission boundary on its own. For a
connection that must never write, combine `/mcp/readonly` with a token or key that holds only
`read:` scopes.

When a client signs in on `/mcp/readonly`, it asks for read scopes only. On a toolset view it
asks for the scopes that view's tools use.

### One token for every endpoint

Each endpoint publishes its own OAuth protected resource metadata, whose `resource` is that
endpoint's URL:

```text theme={null}
https://mcp.use.observer/.well-known/oauth-protected-resource/mcp
https://mcp.use.observer/.well-known/oauth-protected-resource/mcp/readonly
https://mcp.use.observer/.well-known/oauth-protected-resource/mcp/x/incidents,metrics
```

Observer's authorization server accepts any path under `/mcp` as the resource and binds every
grant to `https://mcp.use.observer/mcp`. A token issued for one endpoint therefore works on all
of them, and an `obs_pub_` API key works on every endpoint as well.

## How calls behave

### Server instructions

When a client connects, the server sends instructions with the working rules for its tools:
confirm with the person before a destructive call, show incident text before it reaches
subscribers, test a check before adding it, install and poll an Observer Agent. Tool
descriptions state facts only. The instructions mention only the tools the endpoint serves, so
a view never points the assistant at a tool it cannot call.

### Tool annotations

Every tool has a title and the standard MCP annotations, which clients use to decide when to
ask before a call:

* **Read-only** (`readOnlyHint`): the tool changes nothing.
* **Destructive** (`destructiveHint`): the call can remove or replace something, for example a
  delete, a key rotation, changing a page's settings, or applying a config document.
* **Idempotent** (`idempotentHint`): repeating the call with the same arguments has no further
  effect.
* **Open world** (`openWorldHint`): the call reaches people or systems outside Observer, such as
  status page subscribers and alert integrations, or a target outside Observer for `testProbe`.

Annotations are hints for the client. Scopes decide what a call may do.

### Arguments

* An argument the tool does not define is refused, and the error lists the valid argument
  names. A misspelled filter therefore fails instead of returning unfiltered data.
* A missing required argument is refused with the names of the missing arguments.
* Numbers and booleans sent as strings are converted where the argument is not a string, for
  example `"20"` to `20` and `"true"` to `true`. Objects and arrays are passed as they are.

### Paging

List tools return 20 items per page through the MCP server unless the call passes `limit`. The
HTTP API default is 50 (100 for the audit log). Pass `cursor` with the previous page's
`next_cursor` to read the next page.

### Result size

Results are compact JSON. A result is capped at 48,000 characters, which keeps it under the
limits common MCP clients apply to tool output. When a response is larger:

* Whole entries are dropped from the end of the list (the page's `items`, or the largest list
  in the response). A string is never cut in the middle, and the result stays valid JSON.
* A second text block says how many entries are shown, and which arguments of the tool narrow
  the request.
* On a page cut short, `next_cursor` is `null`, because the real cursor would skip the dropped
  entries. The note gives the `limit` that returns the same entries with a usable
  `next_cursor`.
* A text response, such as a YAML export, is cut at a line boundary.

To get a complete result, narrow the request: pass a smaller `limit` and page with `cursor`,
filter by the tool's arguments (state, service, time window), or read one object with its
`get` tool instead of listing all of them.

### Errors

When a call fails, the tool result carries the API's error with the details needed to fix the
request: the list of validation errors and warnings for a rejected config document, the
missing scope, and an upgrade link when a plan limit or a plan without API access is the
cause. A `403` says whether a scope, the plan, or a suspended item is the cause; only a missing
scope is fixed by reconnecting with more permissions.

## Agent skills

The public [skills repository](https://github.com/useobserver/skills) holds thirteen skills
that teach an assistant how to work with Observer: setup, checks, no data diagnosis, incidents,
maintenance, SLOs, SLA reports and more, with the safety rules a careful operator follows. For
Claude Code it installs as a plugin together with this server. See
[Agent skills](https://docs.use.observer/docs/mcp/skills.md).

## Tool catalog

The behaviour column shows each tool's annotations. A read-only tool marked as needing a write
scope is not offered on `/mcp/readonly`.

### Account

Toolset: `account`.

| Tool | Title | Scope | Behaviour | What it does |
| - | - | - | - | - |
| `getMe` | Get account, plan and scopes | none | Read-only | The calling key's organization, scopes, plan and trial end, quotas with usage, and rate limits. Call it first. |

### Metrics

Toolset: `metrics`.

| Tool | Title | Scope | Behaviour | What it does |
| - | - | - | - | - |
| `listMetrics` | List metrics | `read:metrics` | Read-only | List metric definitions. |
| `getMetric` | Get metric | `read:metrics` | Read-only | Get a metric by id: its value with `unit`, why it has no data (`reason`, `reason_label`, `reason_hint`), and a pending status change (`pending_status`, `pending_since`). `current_value` is `null` while the metric reports `no_data`. |
| `testProbe` | Test a probe | `write:metrics` or `write:config` | Writes, open world | Run a draft probe once on an agent (or, with no `agent_id`, from Observer for a public HTTP check) and return the value, its `unit`, the status given thresholds would produce, and a reason code. Stores nothing. Use it to check a source and pick thresholds before creating the metric. See [Test a check](https://docs.use.observer/agent/guides/test-a-check.md#test-through-the-api). |
| `getProbeTest` | Get probe test result | `write:metrics` or `write:config` | Read-only, needs a write scope | Get the result of a `testProbe` call that returned `202` while the agent was still running it. |
| `getMetricHistory` | Get metric history | `read:metrics` | Read-only | Aggregated metric values over a window (max 30 days). |
| `setManualMetricStatus` | Set manual metric status | `write:metrics` | Writes, open world | Set the status on a manually-managed metric. |
| `getMetricHeartbeat` | Get heartbeat status | `read:metrics` | Read-only | Heartbeat schedule, state, and recent pings for a heartbeat metric. |
| `rotateMetricHeartbeatUrl` | Rotate heartbeat ping URL | `write:metrics` | **Destructive** | Issue a new heartbeat ping URL. The old one stops working. |
| `deleteMetric` | Delete config-managed metric | `write:config` | **Destructive**, idempotent | Delete a config-managed metric by id or config key. |
| `createHostedCheck` | Watch a website (experimental) | `write:config` | Writes, idempotent | Watch a public website or API from Observer's own locations and put it on a public status page (experimental, nothing to install). |

### Services and SLOs

Toolsets: `services`, `slos`.

| Tool | Title | Scope | Behaviour | What it does |
| - | - | - | - | - |
| `listServices` | List services | `read:services` | Read-only | List services. |
| `getService` | Get service | `read:services` | Read-only | Get a service by id, with its metrics (`via: member` or `via: slo`). |
| `deleteService` | Delete config-managed service | `write:config` | **Destructive**, idempotent | Delete a config-managed service by id or config key. |
| `listSlos` | List SLOs | `read:slos` | Read-only | List SLOs. |
| `getSlo` | Get SLO | `read:slos` | Read-only | Get an SLO with its latest burn event. |
| `deleteSlo` | Delete config-managed SLO | `write:config` | **Destructive**, idempotent | Delete a config-managed SLO by id or config key. |

### Status pages

Toolset: `pages`.

| Tool | Title | Scope | Behaviour | What it does |
| - | - | - | - | - |
| `listPages` | List status pages | `read:config` | Read-only | List status pages with their public URL, access mode, and custom domain state. |
| `getPage` | Get status page | `read:config` | Read-only | Get a status page with its settings and its metrics in display order. |
| `updatePage` | Update status page settings | `write:config` | **Destructive**, idempotent | Change a status page's settings (title, layout, time zone, language, subscriptions, auto-refresh, branding, footer links, group order and summary, search engine settings, theme preset, or `access_mode: public`). Fields not sent keep their value. |
| `deletePage` | Delete config-managed page | `write:config` | **Destructive**, idempotent | Delete a config-managed status page by id or config key. |

### Observer Agents

Toolset: `agents`.

| Tool | Title | Scope | Behaviour | What it does |
| - | - | - | - | - |
| `listAgents` | List Observer Agents | `read:agents` | Read-only | List agents and whether each is online. Filter by exact name. `connected_ever` is `false` for an agent nothing has ever run with, which is safe to reuse. |
| `getAgent` | Get Observer Agent | `read:agents` | Read-only | Get an agent: status, `connected_ever`, first and last heartbeat, assigned metric count. Small by default; `target` adds the install command for one target, `include=install` all of them (without the key). |
| `createAgent` | Create Observer Agent | `write:agents` | Writes | Create an agent. Returns its key once, with the environment variables, and with the install command for `target` (`docker`, `compose`, `kubernetes`, `systemd`, `launchd` or `binary`). `delivery=claim` returns a single-use console link instead of the key. |
| `rotateAgentKey` | Rotate agent key | `write:agents` | **Destructive** | Issue a new agent key, returned once (or through a claim link with `delivery=claim`). The old key keeps working for 24 hours unless invalidated now. |
| `deleteAgent` | Delete Observer Agent | `write:agents` | **Destructive**, idempotent | Delete an agent. Its key stops working; its metrics are kept without an agent. |

### SLA statements

Toolset: `sla`.

| Tool | Title | Scope | Behaviour | What it does |
| - | - | - | - | - |
| `listSlaStatements` | List SLA statements | `read:sla` | Read-only | List SLA Ledger statements. |
| `getSlaStatement` | Get SLA statement | `read:sla` | Read-only | Get an SLA Ledger statement with its signed payload. |

### Incidents

Toolset: `incidents`.

| Tool | Title | Scope | Behaviour | What it does |
| - | - | - | - | - |
| `listIncidents` | List incidents | `read:incidents` | Read-only | List incidents. |
| `getIncident` | Get incident | `read:incidents` | Read-only | Get an incident. |
| `createIncident` | Create incident | `write:incidents` | Writes, open world | Create an incident (draft or published). |
| `patchIncident` | Edit incident | `write:incidents` | Writes, idempotent, open world | Edit title, severity, affected services, visibility. |
| `publishIncident` | Publish incident | `write:incidents` | Writes, idempotent, open world | Publish a draft incident. |
| `resolveIncident` | Resolve incident | `write:incidents` | Writes, idempotent, open world | Resolve an incident, with an optional final message. |
| `appendIncidentMessage` | Post incident update | `write:incidents` | Writes, open world | Append a timeline message (a Resolved message auto-resolves the parent). |
| `draftIncidentFromMetric` | Draft incident from metric | `write:incidents` | Writes, idempotent | Pre-fill a draft incident from a metric's current state (idempotent within 30 minutes). |
| `deleteIncident` | Delete incident | `write:incidents` | **Destructive**, idempotent, open world | Soft-delete an incident. |
| `getIncidentImpact` | Get incident impact | `read:incidents` | Read-only | The measured impact: impact window, affected services, checks and customers, SLO burn, changes recorded around the window (timing only), and the agents and locations that observed it. See [Incident evidence](https://docs.use.observer/docs/guides/incident-evidence.md). |
| `draftIncidentUpdate` | Draft incident update with AI | `write:incidents` | Read-only, needs a write scope | Draft the next customer update with AI, grounded in the measured impact. **Never publishes**: a person reviews the draft and posts it with `appendIncidentMessage`. |
| `addIncidentNote` | Add internal incident note | `write:incidents` | Writes | Attach an internal note with a `source` attribution (for example findings from another tool). Notes never appear on status pages, in emails or in webhooks. |
| `listIncidentNotes` | List incident notes | `read:incidents` | Read-only | List an incident's internal notes, oldest first. |
| `exportIncidentEvidence` | Export signed incident evidence | `read:incidents` | Read-only | Signed incident evidence export (JSON by default). Business plan and up. |

### Audit log

Toolset: `audit`.

| Tool | Title | Scope | Behaviour | What it does |
| - | - | - | - | - |
| `listAuditLog` | List audit log | `read:audit` | Read-only | The organization's audit log, newest first, paginated and filterable. Business plan and up. See [Export the audit log](https://docs.use.observer/docs/guides/audit-log-export.md). |

### Maintenance

Toolset: `maintenances`.

| Tool | Title | Scope | Behaviour | What it does |
| - | - | - | - | - |
| `listMaintenances` | List maintenances | `read:maintenances` | Read-only | List maintenance windows. |
| `getMaintenance` | Get maintenance | `read:maintenances` | Read-only | Get a maintenance window. |
| `createMaintenance` | Schedule maintenance | `write:maintenances` | Writes, open world | Schedule a maintenance window. |
| `patchMaintenance` | Edit maintenance | `write:maintenances` | Writes, idempotent | Edit a maintenance (only before it has started). |
| `startMaintenance` | Start maintenance | `write:maintenances` | Writes, idempotent, open world | Move a scheduled maintenance to in-progress. |
| `completeMaintenance` | Complete maintenance | `write:maintenances` | Writes, idempotent, open world | Move an in-progress maintenance to completed. |
| `cancelMaintenance` | Cancel maintenance | `write:maintenances` | Writes, idempotent, open world | Cancel a maintenance before completion. |

### Config as code

Toolset: `config`.

| Tool | Title | Scope | Behaviour | What it does |
| - | - | - | - | - |
| `exportConfig` | Export config document | `read:config` | Read-only | Export the org's configuration as a canonical apply document. |
| `applyConfig` | Apply config document | `write:config` | **Destructive**, idempotent | Apply a config-as-code document (idempotent upsert by config key). Can reference existing metrics, set service members and page settings. The tool asks for a compact diff (`verbose=false`) unless the assistant requests the full one. See [Command-line interface](https://docs.use.observer/cli/overview.md). |

### Change events

Toolset: `change-events`.

| Tool | Title | Scope | Behaviour | What it does |
| - | - | - | - | - |
| `createChangeEvent` | Record change event | `write:change_events` | Writes | Record a deploy, commit, or release event for status-transition correlation. |

## Notes

* The server is **stateless**: it opens a fresh session per request and keeps nothing. The OAuth
  token or API key is read from the connection header on each call and never stored.
* `createAgent` and `rotateAgentKey` return the agent key in the tool result, once. An assistant
  should hand the install command to you and not keep the key anywhere else. If you would rather
  the key never pass through the conversation, ask it to use `delivery=claim`: the result then
  holds only a single-use console link, valid for 15 minutes, where a signed-in member of the
  organization reveals the key and the install command once.
* `applyConfig` returns only the entries that change by default. `summary` still counts every
  object, and `referenced` lists existing metrics the document names without defining them.
* Tool inputs and outputs match the REST API one-to-one. For full field shapes, request/response
  bodies, and error codes, see the [API reference](https://docs.use.observer/api/overview.md).
* `draftIncidentUpdate` never posts anything. Treat its output as a suggestion: show it to a
  person, and post it only after they approve the wording.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.