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.
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 anobs_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 Config shapes vary by client. Some expect a
Authorization header. Most clients accept a remote server like this:MCP client config
"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 underhttps://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, whoseresource is that
endpoint’s URL:
/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 fortestProbe.
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"to20and"true"totrue. Objects and arrays are passed as they are.
Paging
List tools return 20 items per page through the MCP server unless the call passeslimit. 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_cursorisnull, because the real cursor would skip the dropped entries. The note gives thelimitthat returns the same entries with a usablenext_cursor. - A text response, such as a YAML export, is cut at a line boundary.
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. A403 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.
createAgentandrotateAgentKeyreturn 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 usedelivery=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.applyConfigreturns only the entries that change by default.summarystill counts every object, andreferencedlists 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.
draftIncidentUpdatenever posts anything. Treat its output as a suggestion: show it to a person, and post it only after they approve the wording.

