Connect an AI agent

​

One-prompt setup

Set up Observer for me. Instructions: https://use.observer/llms.txt

​

What the agent does next

1. 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.
2. Creates the Observer Agent, if your checks need one. Metrics other than heartbeats and manual metrics run on an Observer Agent inside your network. The agent looks for an existing one by name first and reuses it. Otherwise it creates one with createAgent, which returns the agent key once, together with install commands that already contain it (docker run, Docker Compose, Kubernetes, systemd, and binary) and the environment variables. The agent shows you the command for your environment for you 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.
3. Waits for the Observer Agent to come online. It polls getAgent until the status changes from never_connected to online, which takes about a minute after the install starts.
4. Plans, then applies the configuration. It builds a config document whose metrics name the Observer Agent, runs applyConfig as a dry run, reads the diff, and then applies it. Apply rejects a metric that names an agent that does not exist.
5. Shares the result and checks it. It reads public_url from listPages and gives you the address of your status page. For a metric that has no data, it reads reason, reason_label, and reason_hint from getMetric, which usually point at an environment variable or a network setting to fix on the host where the Observer Agent runs.

​

What you approve

• 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 client the agent declared (Claude Code, Claude Desktop, Cursor, Codex, or AI agent).
• Request code: the code to compare with the one the agent shows. Only approve when they match.
• Access: the scopes the key receives (see below).
• Plan: your current plan, or the trial that approval starts.

​

Access preset

​

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

https://use.observer/connect?client=claude-code

claude mcp add --transport http observer https://mcp.use.observer/mcp \
  --header "Authorization: Bearer obs_pub_YOUR_KEY"

{
  "mcpServers": {
    "observer": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.use.observer/mcp", "--header", "Authorization: Bearer obs_pub_YOUR_KEY"]
    }
  }
}

{
  "mcpServers": {
    "observer": {
      "url": "https://mcp.use.observer/mcp",
      "headers": { "Authorization": "Bearer obs_pub_YOUR_KEY" }
    }
  }
}

[mcp_servers.observer]
url = "https://mcp.use.observer/mcp"
bearer_token = "obs_pub_YOUR_KEY"

​

Device flow API

​

Start a request

curl -X POST https://use.observer/api/connect/device \
  -H "Content-Type: application/json" \
  -d '{"client": "claude-code"}'

{
  "device_code": "obs_dc_...",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://use.observer/connect?code=WDJB-MJHT&client=claude-code",
  "verification_uri_complete": "https://use.observer/connect?code=WDJB-MJHT&client=claude-code",
  "expires_in": 600,
  "interval": 5
}

​

Poll for the key

curl -X POST https://use.observer/api/connect/device/token \
  -H "Content-Type: application/json" \
  -d '{"device_code": "obs_dc_..."}'

{
  "api_key": "obs_pub_...",
  "token_type": "Bearer",
  "org": "acme",
  "mcp_url": "https://mcp.use.observer/mcp",
  "scopes": ["read:config", "write:config", "read:agents", "write:agents", "read:services", "read:metrics", "read:slos", "read:incidents"]
}

​

Configure the MCP server

​

Example polling loop

START=$(curl -s -X POST https://use.observer/api/connect/device \
  -H "Content-Type: application/json" -d '{"client": "other"}')
DEVICE_CODE=$(echo "$START" | jq -r .device_code)
INTERVAL=$(echo "$START" | jq -r .interval)
echo "Open $(echo "$START" | jq -r .verification_uri_complete)"
echo "Code: $(echo "$START" | jq -r .user_code)"

while true; do
  sleep "$INTERVAL"
  RES=$(curl -s -X POST https://use.observer/api/connect/device/token \
    -H "Content-Type: application/json" -d "{\"device_code\": \"$DEVICE_CODE\"}")
  ERR=$(echo "$RES" | jq -r '.error // empty')
  case "$ERR" in
    "") echo "$RES" | jq -r .api_key; break ;;
    authorization_pending) ;;
    slow_down) INTERVAL=$(echo "$RES" | jq -r .interval) ;;
    *) echo "Stopped: $ERR"; exit 1 ;;
  esac
done

​

Revoke the 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 Settings > API keys. Keys created before the preset included read:agents and write:agents cannot 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.