MCP server

unhandled runs a Model Context Protocol server. Connect an AI assistant to it and the assistant can read your issues, traces, logs, metrics, monitors and alerts, and, if you grant it, change some of them. You sign in through OAuth in the browser, so there is no API key to copy into a config file.

Connect a client

Every client below uses the same server URL, /mcp on your Unhandled domain. Replace https://unhandled.example.com with yours.

Endpoint

GET /mcp and DELETE /mcp return 405 with an allow: POST header, since the server keeps no sessions.

A request with an Origin header must come from the Unhandled app URL, a loopback address, or an origin listed in the MCP_ALLOWED_ORIGINS environment variable (comma-separated). Any other origin gets 403. Requests without an Origin header, which is how most MCP clients connect, are not affected.

Limits

When a tool fails for a reason the caller cannot fix, the result says the tool failed unexpectedly and the server logs the details. It never returns the database error. Calling a tool that does not exist returns the JSON-RPC error -32602.

OAuth endpoints

Unhandled is its own OAuth 2.1 authorization server. MCP clients discover and call these endpoints on their own. You only need them when you write a client yourself.

Clients are public: they get no client secret and must use PKCE.

A refresh token works once. If a client sends any refresh token the grant has already rotated away from, Unhandled revokes the whole grant and the client has to ask for consent again. An authorization code also works once; redeeming it a second time revokes the tokens the first exchange issued.

Scopes and access

A connection belongs to you, not to one organization. Every app registers itself, so the consent page marks it Unverified app, notes that the app chose its own name, and shows the address it sends you back to and the day it registered. On the consent page you pick two things:

• What it can do. Check scopes one by one, or start from the Read only, Triage or Full preset. Only read scopes start ticked, even when the client asks for more; you tick each write scope yourself. You can drop scopes the client asked for, but you cannot add any. Triage is every read scope plus issues:write and alerts:write. It leaves out status:write, which posts on your public status page and emails subscribers.
• Where. Either All organizations, including ones I join later, or only the organizations you tick. The page starts with only the organization you are working in ticked (your first one if you have not opened one yet). With no organization, nothing is ticked, so reaching the ones you create or join later is a choice you make.

The consent page only offers scopes that some tool uses. Clients that still request the old scopes get the scopes of the tools those covered. mcp:read becomes org:read, projects:read, telemetry:read, issues:read, alerts:read, uptime:read, status:read, dashboards:read and deployments:read. mcp:write becomes issues:write, alerts:write, status:write and dashboards:write, so it no longer reaches setup_service. A client that requests no scope is offered every scope, with Read only ticked.

Every call has to pass three checks. A call runs only when all three allow it:

1. The connection was granted the tool's scope.
2. The organization's MCP policy allows that scope. Admins set it in Settings, MCP: MCP access on or off, and optionally a list of the most an app may do there. Changes apply to the next call. The account:* scopes are yours, so a policy's list of scopes does not cover them, but turning MCP off for an organization also stops the inbox and notification preference tools there.
3. Your role allows the action. Each tool uses the same permission check as the page it mirrors, so a member can triage issues, preview alerts and create dashboards, while creating alerts, projects or services needs an admin.

A refused call returns an error result that names the reason, for example Organization "acme" does not allow the issues:write scope over MCP. While an organization is suspended, every tool that changes something returns an error there.

Tools that act inside an organization take an organization argument (its slug). It is required only when the connection reaches more than one organization; whoami lists them. whoami and list_apps cover every organization the connection reaches. Leave an organization and the connection stops reaching it on the next call. An admin can also cut a connection off from their organization; editing the connection or leaving and rejoining does not undo that.

A connection that covers only the organizations you ticked never grows by itself. create_organization adds the organization it creates. accept_invitation does not. After joining, a connection for all organizations reaches the new one, and any other needs you to add it under Connected apps.

Changes made through MCP appear under your user, for example in an issue's activity. They notify people the same way the app does, so assignees get the usual emails.

Calling tools

Most tools accept these optional arguments:

Every response repeats the project, environment, service and window it used, so the assistant knows exactly what it looked at. Results come back as JSON in a single text block. When the caller can fix the problem, such as an unknown project or service, the error names the valid choices.

A result is at most 256 KiB. A list page that would pass the limit returns fewer items, truncated: true and a nextCursor for the rest. Other results that are too large have their long strings cut to 2,048 characters, then 256, and carry a truncationNotice. If the result still does not fit, the tool asks the caller to narrow the request.

Human approval for sensitive actions

Each organization has the setting Require human approval for sensitive agent actions under Settings, MCP. It is on by default, only admins can change it, and every change appears in the organization's MCP Activity list.

While it is on, a sensitive call does not run, even with confirm: true. It returns a result like this instead:

{
  "status": "approval_required",
  "approvalId": "6f0c…",
  "approvalUrl": "https://unhandled.net/mcp/approvals/6f0c…",
  "expiresAt": "2026-10-24T15:15:00.000Z",
  "action": { "tool": "create_invitation", "organization": "acme", "description": "grants [email protected] admin access" },
  "next": "Nothing ran. Ask the user to open … then call create_invitation again with exactly the same arguments plus approvalId."
}

The person who connected the app, or anyone in the organization with at least their role, opens the link while signed in. The page shows the tool, the app, the requester and the exact arguments, with secret values hidden: channel and monitor URLs show only their origin, and custom header values show as (hidden). Approving needs a sign-in from the last 15 minutes or the account password; denying does not. The agent then repeats the call with the same arguments plus approvalId. The approval is bound to the connection, the user, the organization, the tool and a keyed hash of the full arguments, hidden values included, expires after two hours (on a self-hosted server, MCP_APPROVAL_TTL_MINUTES sets another length), and runs once. It is used up only when the call succeeds: a call that fails leaves it ready for a retry, and parallel calls with one approval run the action once. A call with any other argument, from another connection, or after it was used, denied or expired is refused. Stored arguments are redacted and encrypted with the app key. Admins see every approval under Settings, MCP, Approvals until an hour after it expires; the hourly mcp.prune job then deletes it.

These calls are sensitive:

• create_invitation with role admin, update_member promoting to admin, remove_member;
• update_monitor moving a monitor that sends custom headers to another origin, or leaving it with no channel;
• create_notification_channel, update_notification_channel with a new URL, delete_notification_channel, reveal_notification_channel_secret, rotate_notification_channel_secret;
• silencing alerting: pause_monitor, delete_monitor, pause_alert, snooze_alert, delete_alert, update_alert leaving an alert with no destination or changing the condition of a firing alert, create_exception_rule with muteKind;
• delete_organization, delete_project, delete_service, delete_team, delete_status_page, disconnect_integration, remove_ingest_domain;
• issuing or revoking credentials: setup_service, create_deploy_key, get_heartbeat_url, rotate_service_key, revoke_service_key, revoke_deploy_key;
• update_retention_settings lowering any category;
• every call that publishes text outside the organization: create_status_page with public: true, update_status_page publishing a page or changing the text of a public one, create_status_incident or update_status_incident writing to a public incident on a public page or with notifySubscribers: true, create_monitor or update_monitor changing a monitor shown on a public page, and link_issue with your own team, title or body;
• accept_invitation and create_organization. These belong to no organization, so they wait for approval unless every organization you belong to turned the setting off.

When the setting is off, these calls need confirm: true as before.

Untrusted text in results

Much of what a result carries was written by someone other than Unhandled or you: exception messages, log lines, span attributes, AI conversations and analytics events reported by your apps and their users, plus names, comments and descriptions written by members. Anyone with a public DSN can put text there, so an assistant must never follow it as an instruction.

A result is always one JSON text block. When it holds such text, the result's _meta lists those fields under unhandled.net/untrustedFields. Each entry is a path into the JSON, with [] for every item of a list, such as items[].message. A path that ends at an object, such as items[].attributes, covers everything inside it. Only text the server formats itself, such as timestamps, cursors and truncation notices, is left off the list. The server's instructions and every tool description repeat that this text is data, never instructions.

{
  "content": [{ "type": "text", "text": "{\"project\":\"default\",\"items\":[{\"id\":\"1f0…\",\"name\":\"api-health\"}],\"nextCursor\":null}" }],
  "_meta": { "unhandled.net/untrustedFields": ["items[].id", "items[].name", "project"] }
}

Values keep exactly what was stored, so an agent can pass them back unchanged. Characters that hide or reorder text for a person reading along arrive as \u escapes inside the JSON instead of raw: bidirectional controls, zero-width spaces, word joiners, line and paragraph separators, byte order marks, C1 controls and Unicode tag characters. Decoding the JSON gives back the original value. Zero-width joiners stay raw, since emoji and many scripts need them.

Safe retries

The tools that create something accept an optional requestKey of 1 to 200 characters: create_organization, create_project, create_alert, create_dashboard, add_widget, add_issue_comment, create_status_incident, update_status_incident, add_ingest_domain, create_invitation, create_team, create_feedback_thread, reply_feedback_thread and submit_doc_feedback. Repeat a call with the same key within 24 hours and the server returns the first result instead of acting twice. Reusing a key for a different call returns an error. setup_service, rotate_service_key and create_deploy_key take no key, because a replay would have to store the secret they issued, so each call issues a new one. A replay goes through every check again first, so a call your connection may no longer make is refused rather than answered from the earlier result. Secrets in a result, such as a heartbeat URL from create_monitor, are never stored; a replay returns a note to fetch them with get_heartbeat_url.

Every tool in tools/list carries the MCP annotations readOnlyHint, destructiveHint, idempotentHint and openWorldHint, so clients can decide which calls to confirm with you. Tools that delete, revoke, disconnect or stop something, such as delete_project, revoke_service_key or pause_alert, are marked destructive and run only when the call passes confirm: true. Some tools need confirm: true only for certain arguments, and say so in the error when it is missing: rotate_service_key with grace none, update_member demoting an admin, update_team or update_project removing entries from a list, bulk_update_issues on more than 25 issues, update_issue_settings lowering autoResolveDays, update_retention_settings lowering any category, update_exception_settings turning scrubbing off or weakening it, rotate_notification_channel_secret, and create_status_incident or update_status_incident writing to a public incident on a public page or with notifySubscribers true. create_invitation with role admin and update_member promoting to admin need it, and both email the organization's other admins. Calls that silence or reroute notifications need it too: update_alert leaving an alert with no destination or changing the condition of a firing alert, create_exception_rule with muteKind, update_monitor closing an ongoing outage or leaving a monitor with no channel, and create_notification_channel or update_notification_channel with a URL no channel of the organization uses yet. So do calls that change what anyone can read: create_status_page or update_status_page publishing a page or changing the slug, title, description or logo of a public one, create_monitor or update_monitor changing a monitor shown on a public page, link_issue with your own team, title or body, and add_issue_comment when members of the issue's project cannot see some projects you can. test_monitor, create_monitor and update_monitor need it for a host none of the organization's monitors checks yet, and test_notification_channel for a URL no saved channel uses. For 10 minutes after a connection receives a secret, such as a key from setup_service or a signing secret, those calls to a new destination, and every call that publishes text outside the organization, are refused even with confirm: true. pause_monitor and accept_invitation always need it.

update_monitor never carries saved custom header values to another origin. Changing the URL of a monitor with saved headers requires customHeaders in the same call: pass them again, or [] to drop them. test_monitor reports the outcome, status code, timings, error type, response header names and response size, never the response body or header values. Joining an organization with accept_invitation never extends the connection that accepted it, even one approved for all organizations; reconnect the app to work there. delete_project also needs the project's exact name as confirmation, as the app asks you to type it. link_issue is marked open world, since it can create a ticket in Linear or GitHub.

Trace and log searches use the query grammar of the Traces and Logs pages, for example duration>=500ms status:error http.route^/api service:billing-api. Issue tools accept an issue ID, a pasted issue URL or a canonical fingerprint.

Tools

The server registers over 200 tools, listed below by area. tools/list shows only the tools your connection's scopes allow.

Workspace

Projects, services and keys

These tools need an organization admin, except list_services, which any member who can see the project may call.

Issues and exceptions

Traces and logs

Every tool that takes a time window also accepts services (several service names), interval (1m to 1d) and compare (previous, 1d or 1w).

Performance

Metrics

Deployments

Uptime and status pages

Alerts

Analytics and end users

The analytics tools need the analytics:read scope; the end-user tools need telemetry:read.

AI agents and MCP monitoring

These need the ai:read scope.

Dashboards

As in the app, anyone who can see a project may create and duplicate dashboards, while editing, deleting and restoring one needs its creator or an organization admin.

Integrations

Connecting GitHub or Linear stays in the app, since it needs you to approve it with the provider.

Billing

These need the billing:read scope.

Organization, members and teams

Changing the organization, its members and its teams needs an organization admin, as in the app.

Account and inbox

No tool changes your email address, password or passkeys, or deletes your account. Do those in the app.

Feedback

Revoking access

Open Settings, choose Profile under Account, then the Connected apps tab. It lists every app you allowed, with its organizations, scopes and when it was last used.

• Edit changes the scopes and organizations. The change applies to the app's next call.
• Revoke stops its token right away. You can also post the token to POST /oauth/revoke.

Organization admins see every app that reaches their organization in Settings, MCP. Revoke there cuts that app off from the organization only; it keeps working in the member's other organizations. Reconnecting the same app does not bring it back: it stays under Revoked apps until an admin chooses Allow again. The Activity list on the same page shows the latest changes apps made in the organization: the tool, the app, the member, what it acted on and the names of the fields it set, never their values. Tokens also stop working when they expire.

An app can never change its own access: editing connections and the organization MCP policy is only possible in the browser.

FAQ

Related