StatOSS

MCP and agents

Model Context Protocol endpoints: a read-only one next to every page and keyed ones over the account.

Next to every page

https://<page>/mcp (and statoss.com/s/<address>/mcp) is a read-only MCP server with no key: get_status, list_incidents and get_error_budget. On a password-protected or private page it takes the page's key as ?key=.

Over the account

https://statoss.com/api/v1/mcp with an API key as a bearer token. Read keys get list_pages, get_status, list_monitors, list_incidents and get_page_access; write keys add:

  • Pages: create_page, update_page (name, address, words, how it looks) and delete_page.
  • Own domain: set_custom_domain, check_custom_domain and remove_custom_domain. The answer says which DNS record to add.
  • Who can open a page: update_page_access.
  • Monitors: create_monitor, update_monitor, delete_monitor, check_monitor and reorder_monitors (the page's order, by monitor or by group). update_monitor with archived archives a monitor or restores it.
  • Incidents: open_incident, schedule_maintenance, post_update (status completed ends a maintenance window), update_incident and delete_incident.
  • Deploys: record_deploy.

The incident tools take what the REST API takes: a state per monitor, a start in the past, an incident that is already over, a window's reminders and repeat, and notify: false to leave subscribers out. Every tool answers with the same resources the REST API sends, and a key that reaches one page only sees that page and has no create_page. delete_page is for keys made by the team's owner or an admin, and deletes only when confirm is the page's address; without it the answer says what would go. A logo or favicon is an image, and MCP carries JSON, so those two are set over REST only. With on-call, read keys also get list_alerts, get_alert and get_on_call, write keys acknowledge_alert, resolve_alert and snooze_alert, and open_incident takes internal.

https://statoss.com/api/v1/mcp/read takes any key and lists only the tools that read. Teams that have errors or logs also get their tools at both addresses, such as list_issues and search_logs. https://statoss.com/api/v1/mcp/apps/<app> lists one app's tools, the app by id or slug.

Each address takes an API key or a person's sign-in, below.

Setting up an account

Write keys also finish an account's setup, with the calls described under Setting up an account. Read keys get the first tool of each pair that only reads.

  • Alert destinations: list_alert_destinations, add_alert_destination, update_alert_destination, remove_alert_destination, resend_destination_link and test_alert_destination. An email address is not used until it is confirmed.
  • A page's alerts: get_alert_settings, update_alert_settings and test_page_alerts.
  • Subscribers: list_subscribers, add_subscriber and remove_subscriber. An email address gets the confirmation mail and is not subscribed until it opens the link.
  • The team: get_team, invite_member, cancel_invitation, change_member_role and remove_member. For the owner's and admins' keys; the owner is never changed or removed.
  • API keys: list_api_keys, create_api_key and revoke_api_key. A key makes keys no broader than itself, and the new key is in the answer once. A key made through a connected app is deleted when the app is disconnected or its access revoked.

Billing, passwords, two-factor sign-in, single sign-on and deleting the account stay in the dashboard.

Connecting a client

The endpoints speak the Streamable HTTP transport, stateless: JSON-RPC by POST, JSON back, no session and no event stream. Claude Code, Cursor, Claude Desktop and most other clients take a remote server as a URL plus headers.

claude mcp add statoss https://statoss.com/api/v1/mcp \
  --transport http \
  --header "Authorization: Bearer sk_..."

Or, as a JSON entry for a client that reads one:

{
  "mcpServers": {
    "statoss": {
      "url": "https://statoss.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer sk_..." }
    }
  }
}

Signing in

A client added without a key signs its person in with OAuth 2.1. The first call is answered 401 with where to sign in, and the client opens StatOSS in a browser.

claude mcp add statoss https://statoss.com/api/v1/mcp --transport http

In Claude Code, /mcp then starts the sign-in. The Connect page names the client and where it sends the person back, and asks for:

  • the team;
  • Read, or Read and write when the client asks to write, which is for owners and admins;
  • every app, or only one.

After Allow, the client acts as that person with what they chose. A read grant lists only the tools that read, and a grant held to one app sees that app alone. The client renews its access every hour; one unused for 30 days signs in again.

Clients that register themselves and clients with a client ID metadata document both work. The metadata is at /.well-known/oauth-authorization-server, with PKCE (S256) and the scopes read and write.

Agent registration

An agent can set StatOSS up before its person has an account. It follows /auth.md (the auth.md profile, v0.6): it registers with a short proof of work and builds a draft of up to 3 status pages with their monitors and components, 25 in all, and 3 apps for errors and logs. A draft is not public, is not checked and sends no mail. Unclaimed, it is deleted after 24 hours.

To claim it, the agent gives its person a link and a 6-digit code. The link opens a page on StatOSS that asks them to sign in or sign up; only the address the agent named can claim it, once confirmed. The page shows the name the agent gave itself, when it registered, what the draft holds, the team to put it in and what that team's plan leaves out. The code works for 15 minutes and 5 wrong tries. Confirm makes the draft on the team, as the person, with the same address rules and plan limits as the dashboard. The person is mailed, and the team's owner when that is someone else.

After the claim the agent acts for the person on that team through the API and MCP: status pages, monitors, incidents, and apps with their DSN keys. It never sees or makes API keys, never changes the team's people and never touches billing. It signs in again after 30 days, and Connected apps disconnects it at once.

Confirm makes the draft the page showed: if the agent changed it since, the page asks to be reloaded first. An agent that lost the answer with its token can collect it again for 10 minutes, until it first uses it; each collect ends the token before.

Set up with an agent

Pasted into Claude Code, Codex or Cursor in a project's folder, this has the agent do the above for that project. Help in the dashboard has it with your address and team filled in.

Set up StatOSS for this project.

1. Read https://statoss.com/auth.md and follow it: register as an anonymous agent, solve the proof of work, and exchange the assertion for a token.
2. Look through the project for what to watch: the public URLs it serves (the site, the API, health endpoints), the scheduled jobs that should check in, and whether it writes logs.
3. PUT a draft to https://statoss.com/api/v1/agent/draft: one status page named after the project, an http monitor for each URL, a heartbeat monitor with periodMinutes for each scheduled job, and one app for the project's errors with its platform. Ask me only what the project cannot tell you.
4. Ask me for my email address and start the claim with it. Give me the claim link and the 6-digit code in one message, and say that the code goes into the page, not back to you. Poll the claim grant at the interval it names until I have confirmed.
5. After the claim, for the app draft_result made: read its dsn with GET https://statoss.com/api/v1/apps/{appId}, install the SDK for the project's language as https://statoss.com/docs/send-errors describes, keep the DSN in the project's configuration rather than in its code, and send one test error. If the project writes logs, send them to the same app as https://statoss.com/docs/send-logs describes. For each heartbeat monitor it made, read its pingUrl with GET https://statoss.com/api/v1/pages/{pageId}/monitors/{monitorId} and add the ping to the job.
6. Tell me what you set up, with the dashboardUrl draft_result gives for each page and app, and what draft_result.leftOut says the plan left out.

Connected apps

Settings, Connected apps lists each client the person allowed, with its address, the team, read only or read and write, every app or one, and when it was last used. Revoke stops it at once, with all its tokens. A claimed agent is listed there too, with Disconnect.

llms.txt

https://<page>/llms.txt is a short text file that says what the page is, lists its monitors, and points at status.json, the feeds and the MCP endpoint, with a note on how to read status.json. It is what a language model should be handed instead of the HTML. The site's own llms.txt describes StatOSS itself.