OneUptime

OneUptime MCP Server

A Model Context Protocol (MCP) server that exposes OneUptime to AI agents. It lets MCP-compatible clients (Claude, VS Code with Copilot, Cursor, and others) manage incidents, alerts, monitors, status pages, on-call, and telemetry through about 290 tools.

How it works

• Transport: Streamable HTTP at /mcp. The server is stateless — no session IDs are issued or required, so it is safe behind load balancers and multi-replica deployments.
• Hosted endpoint: https://oneuptime.com/mcp
• Self-hosted endpoint: https:// /mcp (served by the App container behind Nginx)
• Auth: sign in with OneUptime (OAuth 2.1, per the MCP authorization specification), or a per-request API key via the x-api-key header or Authorization: Bearer (scheme is case-insensitive). There is no environment-variable API key — every request carries its own credential.

Connecting a client

By signing in

Give the client the URL and nothing else. The first call to a tool that needs an identity is answered 401 with a WWW-Authenticate challenge; the client discovers the authorization server from it, opens the consent screen in the user's browser, and gets tokens for the project the user picks.

claude mcp add --transport http oneuptime https://oneuptime.com/mcp

{ "servers": { "oneuptime": { "type": "http", "url": "https://oneuptime.com/mcp" } } }

The rest of this section configures the same clients with an API key instead, for agents that run unattended.

Claude Desktop

Add to claude_desktop_config.json:

{

"mcpServers": { "oneuptime": { "transport": "streamable-http", "url": "https://oneuptime.com/mcp", "headers": { "x-api-key": "your-api-key-here" } } } }

Claude Code

claude mcp add --transport http oneuptime https://oneuptime.com/mcp \

--header "x-api-key: your-api-key-here"

VS Code (GitHub Copilot)

.vscode/mcp.json or the user MCP configuration:

{

"servers": { "oneuptime": { "type": "http", "url": "https://oneuptime.com/mcp", "headers": { "x-api-key": "${input:oneuptime-api-key}" } } }, "inputs": [ { "type": "promptString", "id": "oneuptime-api-key", "description": "OneUptime API Key", "password": true } ] }

Cursor

.cursor/mcp.json:

{

"mcpServers": { "oneuptime": { "url": "https://oneuptime.com/mcp", "headers": { "x-api-key": "your-api-key-here" } } } }

For self-hosted instances, replace oneuptime.com with your OneUptime host in any of the above.

Authentication

API key

Create a project API key in OneUptime under Project Settings → Advanced → API Keys and grant it the least privilege the agent needs (read-only keys work for all get_/list_/count_ tools). The project is inferred from the key — create tools never need a projectId argument.

Warning — never give an AI agent a master key. A OneUptime *master* API key is also accepted on this header and grants instance-wide admin access. Always use a project-scoped API key with least privilege for AI agents.

Public status page tools and oneuptime_help / oneuptime_list_resources / oneuptime_describe_resource work without any credential.

OAuth sign-in

The code is in OAuth/; each file opens with the reasoning behind it. The shape of it:

• One issuer under `/mcp`. https:// /mcp is both the protected resource (RFC 9728) and the authorization server's issuer (RFC 8414). Every endpoint sits under /mcp/oauth, and every URL is built from HOST / HTTP_PROTOCOL, never from the request.
• Lazy, at the HTTP layer. OAuth/RequestGate runs before the MCP SDK sees a request. initialize, tools/list and the public tools pass with no credential; a call to a tool that needs an identity is refused 401 (or 403 insufficient_scope for a read-only grant calling a write tool) with a Bearer challenge. It cannot live in a tool handler: a refusal from inside the SDK is a 200, and a client only starts signing its user in on a real 401.
• Clients identify themselves. A Client ID Metadata Document (OAuth/ClientIdMetadataDocument, fetched through the egress guard with private addresses always blocked) or Dynamic Client Registration (OAuth/RegistrationEndpoint). Nobody registers a client by hand.
• Authorization code + PKCE (S256 only), resource indicators (RFC 8707), iss in the authorization response (RFC 9207), rotating refresh tokens with reuse detection, revocation (RFC 7009).
• Opaque tokens, stored as hashes. oumcp_ac_… / oumcp_at_… / oumcp_rt_…; only the SHA-256 is kept (McpOAuthToken). A grant (McpOAuthGrant) is one member letting one client act for them in one project; revoking is deleting the grant, which cascades to its tokens.
• Only an access token is a credential. x-api-key carries an API key and nothing else; Authorization carries an API key or an access token. Any other oumcp_ secret presented in either header — a refresh token, a code, a client secret, or an access token in x-api-key — is refused 401 invalid_token by OAuth/RequestGate and is never passed on to the API as an API key.
• Scopes mcp:read and mcp:write (write includes read). The consent screen can narrow what a client asked for, never widen it.
• The API never sees the client's token. Having accepted an access token, the MCP layer calls the REST API with a 60-second signed *delegation token* (Common/Server/Utils/Mcp/McpDelegationToken). Common/Server/Middleware/McpDelegationAuthorization turns that into a request authorized as the member — never as a master admin — in the grant's project, with their live permissions, and marked read-only when the grant is. A stolen access token is therefore worth exactly what the MCP tools can do with it.
• Checked on every use. Common/Server/Utils/Mcp/McpOAuthGrantAccess re-evaluates the grant per request and per token exchange: the member still exists, is not blocked, still belongs to the project, is not on a team that blocks AuthorizeMcpClient, and still satisfies the project's SSO requirement.
• Consent is the Accounts page /accounts/mcp-authorize; managing connected clients is Settings → MCP Server in the Dashboard.

Two settings: DISABLE_MCP_OAUTH=true switches the whole thing off (the routes answer 404 and an unauthenticated tool call gets the in-band "API key is required" result it always got), and DISABLE_MCP_OAUTH_CLIENT_ID_METADATA_DOCUMENTS=true is for instances that cannot make outbound requests.

Tool catalog

Database resources — full CRUD

Each of these 27 models gets six tools: create_, get_, list_, update_, delete_, count_ (e.g. create_incident, get_incident, list_incidents, update_incident, delete_incident, count_incidents):

Incident, Alert, Incident Alert, Monitor, Status Page, Scheduled Maintenance Event, Team, Monitor Status, On-Call Policy, Incident State, Incident Severity, Alert State, Alert Severity, Incident State Timeline, Alert State Timeline, Incident Public Note, Incident Internal Note, Alert Internal Note, Status Page Announcement, Scheduled Maintenance State, Scheduled Maintenance State Timeline, Label, Monitor Status Event, Security Case, Security Case Note, Security Detection, Security Playbook.

Telemetry resources — read-only

Log, Metric, Span, Exception Instance, Monitor Log, Security Event, Change Event, Kubernetes Cost Allocation, and Threat Intel Indicator get list_ and count_ tools only (e.g. list_logs, count_spans, list_exception_instances). There are no create tools for telemetry — ingestion happens via OpenTelemetry.

Workflow tools

Purpose-built shortcuts for incident/alert response (packages/App/FeatureSet/MCP/Tools/WorkflowTools.ts):

• acknowledge_incident, resolve_incident
• acknowledge_alert, resolve_alert
• add_incident_note (with visibility: "internal" | "public" — public notes post to the status page)
• add_alert_note
• get_data_table_freshness — whether a table Data Observability watches is fresh: fresh or late by its own rhythm, when it last changed, its open alerts, and its writers' latest runs (read-only)
• oneuptime_whoami — returns the project (ID and name) the credential belongs to; for an OAuth sign-in, also who is signed in, through which client, and whether the connection is read-only

Helper and public tools

• oneuptime_help, oneuptime_list_resources
• oneuptime_describe_resource — one resource's fields: what each means, the filter operators its type takes, and whether it can be sorted or must be selected. Accepts the resource's name or any of its tool names (Incident, list_incidents).
• No credential needed: get_public_status_page_overview, get_public_status_page_incidents, get_public_status_page_scheduled_maintenance, get_public_status_page_announcements

Annotations and results

Every tool has a title and states all three MCP hints, set in Tools/ToolAnnotations.ts, so clients can auto-approve safe calls and confirm the rest:

• readOnlyHint: true on the tools that change nothing: get_, list_, count_, oneuptime_whoami, the helper tools and the public status page tools.
• destructiveHint: true on every tool that changes something: create, update and delete tools, acknowledging and resolving, and adding notes. Most writes overwrite or delete a record, change an incident's or alert's state, page someone on call or post to a status page, and the directories allow false only for a write that adds and sends nothing.
• openWorldHint: true only on the public status page tools, which read any public status page on the instance. Every other tool stays inside the caller's project.

MCP directories require them: the Claude Connectors Directory flags any tool without a title or a readOnlyHint/destructiveHint, and ChatGPT's requires all three hints as booleans. Tests/ToolAnnotationsForDirectories.test.ts fails on a tool that lacks one, or that breaks the rules above. On the server itself, MCP_ALLOW_DESTRUCTIVE=false removes the delete tools only, and MCP_READ_ONLY=true removes every tool that is not read-only (Tests/WritePolicy.test.ts). Tool results include structuredContent alongside the JSON text. Errors come back as in-band tool results (isError: true) with statusCode, details, and a suggestion — not as protocol errors.

The size of tools/list

Many clients load every tool definition before the first question, so tools/list is paid for on every connection. On 2026-11-02 oneuptime.com answered it with 283 tools in 1,202,028 bytes (about 300,000 tokens at four characters a token), more than many models hold: each list_ and count_ tool listed every field of its model with its operators and an example. On the code that changed this, the answer went from 289 tools in 1,228,155 bytes to 290 tools in 237,400 bytes (about 59,000 tokens):

• list_ and count_ tools take any field in query and sort and say how a filter is written; oneuptime_describe_resource gives the fields on demand, one resource at a time.
• Generated schemas carry no examples. A typed value such as a date ({"_type": "DateTime", "value": ...}) or a color keeps its shape as schema, since its example was the only place that stated it.
• create_ tools explain only the fields a call cannot leave out, and update_ tools name and type their fields without explaining them. Every field is still listed and typed, so a client that validates a call still can.
• Tool names, titles and annotations are unchanged.

Tests/ToolListBudget.test.ts reads tools/list through the SDK's client and fails above 250,000 bytes, or for any tool above 5,000 bytes. A new model adds about 4 KB. When a change goes over, make the t