obs_pub_ key that you can
revoke at any time.
One-prompt setup
Paste this into Claude Code, Cursor, Codex, or any agent that can make HTTP requests:llms.txt and then:
1
Starts a connect request
The agent calls
POST https://use.observer/api/connect/device and shows you a
short code such as WDJB-MJHT and a link to https://use.observer/connect.2
You approve in the browser
Open the link. If you have no account, you sign up first; if you have no
organization, one is created for you (from your company email domain, or from
a name you confirm). Check that the request code on the page matches the code
the agent showed you, tick This matches the code my agent shows, then
select Approve.
3
The agent receives its key
The agent, which has been waiting in the background, receives the API key and
adds the Observer MCP server to its configuration. You can return to the agent
and tell it what to set up.
What the agent does next
Once connected, the agent sets Observer up in this order:- Checks what the key allows. It calls
getMe, which returns the key’s scopes, your plan (and when a Starter trial ends), how many agents, metrics, services, SLOs, and status pages the plan allows and how many are used, and the API rate limits. - Creates the Observer Agent, if your metrics need one. Metrics other than
heartbeats and manual metrics run on an Observer Agent
inside your network. The agent asks where it will run (Docker, Docker
Compose, Kubernetes, systemd on Linux, launchd on macOS, or the binary in
the foreground). It looks for an existing Observer Agent by name first and
reuses one only if nothing has ever connected with it (
connected_everisfalse). Otherwise it creates one withcreateAgent, which returns the agent key once, the environment variables, and the install command for your target with the key already in it. The agent shows you the command to run. Observer stores only a hash of the key, so if the command is lost, the agent rotates the key to get a new one. If you prefer that the key never appear in the conversation, ask for a claim link (delivery=claim): you open it in the console within 15 minutes and reveal the key and command there, once. - Waits for the Observer Agent to come online. It polls
getAgentevery 15 to 30 seconds until the status changes fromnever_connectedtoonline, which takes about a minute after the install starts. - Plans, then applies the configuration. It builds a config document
whose metrics name the Observer Agent (intervals in minutes), runs
applyConfigas a dry run, reads the diff, and then applies it. Apply rejects a metric that names an agent that does not exist. - Shares the result and checks it. It reads
public_urlfromlistPagesand gives you the address of your status page. For a metric that has no data, it readsreason,reason_label, andreason_hintfromgetMetric, which usually point at an environment variable or a network setting to fix on the host where the Observer Agent runs.
deleteMetric, deleteService, deleteSlo, or deletePage).
What you approve
The approval page shows:- Organization: the organization the key belongs to. If you are a member of several, you choose one first, and you can change it before approving.
- Requested by: the name the agent gave itself (Claude Code, Claude Desktop, Cursor or Codex). Any program can claim any name, so the page shows it as a claim, for example “An agent that says it is Claude Code”, or “An AI agent that did not name itself”.
- Request: when the request was made, the IP address and country it came from, and the program that made it (its User-Agent). If you did not start this agent yourself, or the details don’t match where you are, decline.
- Request code: the code to compare with the one the agent shows. Approve stays disabled until you tick This matches the code my agent shows.
- Access: the scopes the key receives (see below).
- Plan: your current plan, or the trial that approval starts.
Access preset
Every key created through this flow has the same fixed set of scopes, labelled Set up and manage your status pages:write:agents lets the agent create Observer Agent keys. An agent key lets a
host send data for your organization, so the agent hands it to you in the
install command and does not keep it.
The preset does not include incident or maintenance writes, manual metric
status writes, change events, or SLA statements. Those act on your public
page or your customers, so they are left out on purpose. If you want an
agent to open incidents or schedule maintenance, create a separate key with
those scopes under Developers > API keys. See
Authentication for the full scope list.
The key is named after the client, for example Claude Code (agent connect),
so you can find it later in the key list.
Starter trial
The MCP server runs on the public API, which is included from the Starter plan. When an organization on Free approves an agent connection, approval starts a 14-day Starter trial:- One trial per organization, ever.
- No card is needed.
- When the trial ends, the organization is back on Free. Nothing is deleted: your pages, metrics, and settings stay. API keys stop working until you upgrade, and new resources over the Free limits cannot be created.
Manual setup
If your agent cannot make HTTP requests, or you prefer to paste the key yourself, open/connect directly with your client in the query string:
client values are claude-code, claude-desktop, cursor,
codex, and other. Sign in, choose the organization, and approve. The page
shows the key once, together with a ready-made MCP configuration for that
client:
- Claude Code
- Claude Desktop
- Cursor
- Codex
--scope user keeps the key in your own Claude Code settings, outside any
repository. To share the server with a team through a checked-in .mcp.json,
reference the key from an environment variable instead of pasting it:Device flow API
This section is for authors of agents and tools that want to implement the connect flow. It follows the shape of the OAuth 2.0 Device Authorization Grant (RFC 8628), without client registration. Neither endpoint needs authentication.Start a request
client is one of claude-code, claude-desktop,
cursor, codex, or other; any other value is treated as other. It sets
the client name shown on the approval page and the MCP configuration offered
there.
Starting requests is rate limited per IP address (10 per 10 minutes). Over the
limit, the endpoint answers
429 with a Retry-After header.
Poll for the key
Show the personuser_code and verification_uri_complete (or open the link
in their browser), then poll the token endpoint every interval seconds:
application/x-www-form-urlencoded with a
device_code field.
While the request is not finished, the answer is HTTP 400 with an error
and an error_description:
When the person approves, the next poll returns HTTP
200:
device_code returns expired_token.
Store the key before doing anything else.
Polling is also rate limited per IP address (120 per minute), which leaves
room for several agents behind one address.
Configure the MCP server
Add the server atmcp_url with the header
Authorization: Bearer <api_key>. The configurations under
Manual setup show the shape for each client. Then confirm
the connection by calling getMe (GET /api/v1/me), which needs no scope
and returns the key’s scopes, plan, quotas, and rate limits.
Follow the order in What the agent does next.
The public skills repository
describes the same setup loop in more detail. See
Agent skills.
Example polling loop
Revoke the key
Open Developers > API keys in the console, find the key named after the client (for exampleClaude Code (agent connect)), and revoke it. The agent’s
next call through the MCP server fails, and the key cannot be restored. To
connect again, run the connect flow again; it creates a new key.
Troubleshooting
- “This request has expired”: the link is older than 10 minutes or was already used. Ask the agent to start again.
- “Ask an owner to connect”: you are a member but not an owner of the organization. Send the link to an owner, or ask an owner to create a key for you.
- “API access needs Starter”: the organization is on Free and has already used its trial. Upgrade the plan to connect.
- A tool call fails with a scope message: the tool needs a scope outside
the preset. Create a key with that scope under Developers > API keys.
Keys created before the preset included
read:agentsandwrite:agentscannot manage Observer Agents; run the connect flow again for a new key. - Creating an Observer Agent fails with a plan limit: the organization already has as many agents as the plan allows. Reuse an existing agent, delete one you no longer need, or upgrade. The error carries the upgrade link.
- The Observer Agent stays
never_connected: the install command has not run, or the host cannot reach Observer over HTTPS. Read the agent’s logs with the command shown next to the install snippet.

