> ## 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, 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, using your 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, and other MCP clients) work with your
Observer data: read metrics, services, SLOs, status pages, incidents, and maintenance windows,
create the Observer Agents that run your checks, 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 API key,
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 key you supply on the connection.

<Info>
  **Requirements**

  You need an `obs_pub_` API key (create one under **Settings** > **API keys** in the console) with
  the scopes for the tools you intend to use, on a plan that includes **public API access**.
</Info>

## Connect

<Info>
  **Let the agent connect itself**

  An agent can request its own key: you approve one link and it receives a scoped key and
  configures this server. See [Connect an AI agent](/docs/mcp/connect-ai-agent). The steps below
  are the manual path.
</Info>

<Steps>
  <Step title="Create an API key">
    In the console, open **Settings** > **API keys**, create a key, and grant
    only the scopes you need (see the catalog below). Copy the `obs_pub_…` value.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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).
  </Step>
</Steps>

<Info>
  **Scopes are the boundary**

  A tool only runs if the key carries its scope. 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.
</Info>

## Agent skills

Ready-made skills that teach an assistant the working model (scope
discipline, the export/apply loop, the incident lifecycle) live in the
public [skills repository](https://github.com/useobserver/skills).
Copy a skill folder into your agent's skills directory, or let the
assistant read it directly.

## Tool catalog

### Account

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

### Metrics

| Tool | Scope | What it does |
| - | - | - |
| `listMetrics` | `read:metrics` | List metric definitions. |
| `getMetric` | `read:metrics` | Get a metric by id, including why it has no data (`reason`, `reason_label`, `reason_hint`). |
| `getMetricHistory` | `read:metrics` | Aggregated metric values over a window (max 30 days). |
| `setManualMetricStatus` | `write:metrics` | Set the status on a manually-managed metric. |
| `getMetricHeartbeat` | `read:metrics` | Heartbeat schedule, state, and recent pings for a heartbeat metric. |
| `rotateMetricHeartbeatUrl` | `write:metrics` | Issue a new heartbeat ping URL. The old one stops working. |
| `deleteMetric` | `write:config` | Delete a config-managed metric by id or config key. |

### Services and SLOs

| Tool | Scope | What it does |
| - | - | - |
| `listServices` | `read:services` | List services. |
| `getService` | `read:services` | Get a service by id. |
| `deleteService` | `write:config` | Delete a config-managed service by id or config key. |
| `listSlos` | `read:slos` | List SLOs. |
| `getSlo` | `read:slos` | Get an SLO with its latest burn event. |
| `deleteSlo` | `write:config` | Delete a config-managed SLO by id or config key. |

### Status pages

| Tool | Scope | What it does |
| - | - | - |
| `listPages` | `read:config` | List status pages with their public URL, access mode, and custom domain state. |
| `getPage` | `read:config` | Get a status page with its metrics in display order. |
| `deletePage` | `write:config` | Delete a config-managed status page by id or config key. |

### Observer Agents

| Tool | Scope | What it does |
| - | - | - |
| `listAgents` | `read:agents` | List agents and whether each is online. Filter by exact name to reuse an existing agent. |
| `getAgent` | `read:agents` | Get an agent: status, first and last heartbeat, assigned metric count. |
| `createAgent` | `write:agents` | Create an agent. Returns its key once, with install commands and environment variables. |
| `rotateAgentKey` | `write:agents` | Issue a new agent key, returned once. The old key keeps working for 24 hours unless invalidated now. |
| `deleteAgent` | `write:agents` | Delete an agent. Its key stops working; its metrics are kept without an agent. |

### SLA statements

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

### Incidents

| Tool | Scope | What it does |
| - | - | - |
| `listIncidents` | `read:incidents` | List incidents. |
| `getIncident` | `read:incidents` | Get an incident. |
| `createIncident` | `write:incidents` | Create an incident (draft or published). |
| `patchIncident` | `write:incidents` | Edit title, severity, affected services, visibility. |
| `publishIncident` | `write:incidents` | Publish a draft incident. |
| `resolveIncident` | `write:incidents` | Resolve an incident, with an optional final message. |
| `appendIncidentMessage` | `write:incidents` | Append a timeline message (a Resolved message auto-resolves the parent). |
| `draftIncidentFromMetric` | `write:incidents` | Pre-fill a draft incident from a metric's current state (idempotent within 30 minutes). |
| `deleteIncident` | `write:incidents` | Soft-delete an incident. |

### Maintenance

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

### Config as code

| Tool | Scope | What it does |
| - | - | - |
| `exportConfig` | `read:config` | Export the org's configuration as a canonical apply document. |
| `applyConfig` | `write:config` | Apply a config-as-code document (idempotent upsert by config key). |

### Change events

| Tool | Scope | What it does |
| - | - | - |
| `createChangeEvent` | `write:change_events` | 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. Your key
  is read from the connection header on each call and never stored.
* 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, and an
  upgrade link when a plan limit or a plan without API access is the cause.
* `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.
* 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](/api/overview).
* For safe exploration, connect a key with only `read:*` scopes. Add `write:*` scopes when you
  want an assistant to open incidents, schedule maintenance, or apply config.


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