Skip to main content
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.
RequirementsYou 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

Install in your client

Claude, Claude Code, Cursor, VS Code, Codex and Gemini CLI, with OAuth.

Connect with OAuth

How sign-in, scopes, tokens and revocation work.

Connect an AI agent

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 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:
MCP client config
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).
Scopes are the boundaryA 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 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). To watch internal services, databases or metrics, ask it to set up the Observer Agent 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: Toolset names: account, agents, audit, change-events, config, incidents, maintenances, metrics, pages, services, sla, slos. Each section of the 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:
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 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.

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.

Metrics

Toolset: metrics.

Services and SLOs

Toolsets: services, slos.

Status pages

Toolset: pages.

Observer Agents

Toolset: agents.

SLA statements

Toolset: sla.

Incidents

Toolset: incidents.

Audit log

Toolset: audit.

Maintenance

Toolset: maintenances.

Config as code

Toolset: config.

Change events

Toolset: change-events.

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.
  • draftIncidentUpdate never posts anything. Treat its output as a suggestion: show it to a person, and post it only after they approve the wording.