Reference14 min read

MCP catalog and limits

The MCP tools, operation catalog, approval workflows, protocol features and fixed limits.

The executable candidate catalog is derived from REST v2 operation IDs and schemas, not a separate OpenAPI document. Run npm run --silent mcp:coverage to generate a source-labelled JSON artifact outside the repository. CI fails when a live operation is missing, stale, re-scoped, re-shaped or lacks an explicit disposition/handler mapping. Review metadata lives in src/lib/mcp/catalog/review.json.

Coverage per area and how an assistant reaches each operation are in the permissions reference; every tool, with its inputs, is in the tool reference. Curated tools cover incident search/detail/context/timeline/create/acknowledge/assign/note/resolve, plus escalate, reopen and unsnooze; on-call lookup and schedules; service health and escalation explanation; effective automation, simulation and decision trace; runbook discovery/preview/execution lookup; saved reports and status pages. Tools require explicit grant scopes and current role authority. Listing a tool never authorizes access to a resource.

whoami is always available: it returns the caller's user id, display name, role, teams, effective scopes, whether changes and sensitive reads are on, and the enabled tools (never an email address). assigneeId: "me" means the caller in incident lists, and "me" is also accepted for assigneeId in incident_assign and incident_create and for userId in incident_watch (direct calls only; a reviewed change keeps exactly the arguments the reviewer saw). Discovery tools are search_capabilities, describe_operation, read_operation, call_operation and execute_plan. read_operation is annotated read-only and serves reads and enabled sensitive reads; a change returns MCP_NOT_A_READ. call_operation serves routine changes only; a read returns MCP_NOT_A_CHANGE. Search and describe say which tool to use (workflow) and mark operations the role allows but the connection was not granted as requiresAdditionalConsent. Plans accept literal, allowlisted, read-only steps with IDs and dependencies, perform at most two independent reads concurrently, and return step-level completion/failure/skipped outcomes. Plans accept no code; a step can take a value from an earlier step it depends on with {"$from": "<stepId>", "pointer": "/data/0/id"} (an RFC 6901 JSON Pointer into that step's result.data), and a reference that finds nothing fails only that step with MCP_PLAN_REFERENCE.

On-call actions run directly, like acknowledge and resolve, under the same role, team and per-incident checks: incident_escalate pages the next escalation step now (only an OPEN incident escalates; the result says who was paged, or requested: false with the reason), incident_reopen, incident_unsnooze, and incident_acknowledge_many, which acknowledges up to 8 incidents one at a time, each through its own check and idempotency receipt (the per-incident key is derived from the caller's), with a completed or failed result per id. Snooze and unacknowledge stay approval-gated, because they silence paging or re-trigger escalation to others.

Composite reads answer the common questions in one call. incident_get_context returns the incident (with escalation and SLA state), a bounded timeline, related incidents and the recent responder notes; a part that cannot be read is returned as { ok: false, error } while the rest still answers. oncall_for_service returns a service's escalation policy step by step with the people on call now for each schedule, when each shift ends and who is next (at most 4 schedules per call). incident_search takes status as one value, a comma-separated list, or ACTIVE for every unresolved status, plus createdAfter and createdBefore. List results carry one evidence.webUrlTemplate and up to 10 "Open in OpsKnight" links; rows keep the REST shape. Composite tools charge the request quota for each operation they run before they start.

search and fetch follow the shape ChatGPT company knowledge and deep research call. search looks through the incidents, postmortems, runbooks and services this connection can read (up to 10 per kind) and returns { results: [{ id, title, url }] } with ids such as incident:<id>. fetch takes one of those ids and returns { id, title, text, url, metadata }, with text as markdown built from the redacted result. Access is checked again for every fetched id; having appeared in a search grants nothing. Both are on by default and can be turned off under exposed capabilities.

One separate sensitive workflow is available through runbook_prepare_execution and runbook_execute_approved. It requires writes enabled, native execution authority, and runbooks:execute runbooks:read incidents:read services:read. Preparation accepts the canonical native execution body without expectedPlanDigest, plus runbookId and idempotencyKey; it returns a frozen preview handle, digest, expiry and native review URL without starting work. Anyone with runbook approve and runbook read permission who can see the target (Responders and Administrators by default) approves that snapshot natively; normally a second person, though an administrator may approve their own request after an explicit confirmation. runbook_get_approval reports PENDING, APPROVED, REJECTED (with the reviewer's reason, labelled untrusted), EXPIRED or CONSUMED. Execution accepts only the handle and idempotency key, revalidates the plan and both principals, and creates one canonical durable execution. No MCP tool can approve. Direct generic executeRunbook and write plans remain blocked. These tools do not increase the generic operation candidate count; durable MCP Tasks apply only to runbook_execute_approved.

Sensitive configuration (R2) uses a second generic workflow: operation_prepare, a native review and operation_commit_approved, with operation_get_approval for durable status. These tools appear only when writes are enabled and the principal could perform at least one gated operation.

  • Prepare validates the canonical arguments (without idempotencyKey; revision-bound operations require ifMatch). It freezes them under a SHA-256 digest that also binds the reviewed contract and route versions, and stores the encrypted envelope in PostgreSQL for the policy's review window (Time to review, default 240 minutes, 15 to 1440). Eligible administrators get an in-app notification linking to the review page; there is no email.
  • Review happens only on the native page /settings/integrations/mcp/approvals/operations/{id}, by an active administrator who holds every permission the change needs. Normally a second person reviews the exact, frozen request; an administrator may approve their own request only after explicitly confirming it, and the approval is recorded as self-approved. Anyone else needs a second person. The assistant can never approve: no MCP, REST or tool path can. Approval opens a commit window (Time to apply after approval, default 30 minutes, never later than 24 hours after the request). A rejection may carry a reason of up to 500 characters.
  • Poll with operation_get_approval until the status is APPROVED.
  • Commit accepts only the approval ID and requires the same grant. It rechecks requester and reviewer authority, plan digest, expiry and policy, then invokes the existing REST command. The approval is marked COMMITTED, and its commit audit written, inside the same database transaction as the effect, through the route's mutation guard. Retries therefore find either the effect together with its committed approval, or neither. Operations with a durable receipt (required or supported idempotency) replay the stored result. Receipt-less (natural) writes qualify only when their route runs the guard inside its transaction. If a route commits but then reports an error, only that attempt is reverted.
  • Failure handling: a stale If-Match revision ends the approval as FAILED. Ambiguous outcomes stay retryable for one hour.

The coverage artifact's byDisposition group APPROVAL_REQUIRED lists the 105 gated operations: 85 sensitive (R2) and 20 destructive (R3). They span teams and response policies, Service Automation, runbook rules and runbook lifecycle, incidents, settings and custom fields, reports and dashboards, postmortems, schedules, services, status pages and integrations. Each family has its own suite under tests/integration/mcp-approval-*.test.ts, built on the shared harness. The review page shows target IDs, the bound revision, query parameters and the changed body fields. Approval-gated operations are never callable through call_operation or execute_plan.

Destructive (R3) operations add four safeguards:

  • An impact preview: the reviewed read of the exact target, whose scopes the operation must also hold. The reviewer sees it; the agent receives only a placeholder.
  • Recent sign-in: the reviewer must have authenticated within the last two hours.
  • A commit-time re-read: a fresh commit refuses with MCP_APPROVAL_PLAN_CHANGED if the target's id, revision or updatedAt no longer matches what was reviewed.
  • A recorded postcondition (VERIFIED, NOT_VERIFIED or UNKNOWN). A resumed delete whose target is already absent is reconciled as committed, not failed.

Every destructive preview is an item-level read of the exact target. Sub-resource deletes (team members, schedule participants and overrides, postmortem action items, incident watchers and status-page assets) use dedicated REST item reads (getTeamMember, getScheduleParticipant, getScheduleOverride, getPostmortemActionItem, getIncidentWatcher, getStatusPageAsset) that mirror their collection's authorization and projection; a paginated or capped collection is never used as a preview.

Sensitive reads (R2 configuration and history reads) are generic, read-only and redacted. They are visible and callable only while the administrator enables sensitive reads in the MCP policy (off by default), and are never allowed in execute_plan. A non-GET operation can be a sensitive read only when its review records sideEffectFree and its mutation contract is receipt-less, unfenced and concurrency-free. The coverage gate enforces this. Such reads take no idempotency key or revision precondition, and their certification checks that they write no audit entry, receipt or job. Every sensitive read passes the shared certification:

  • a redacted, bounded projection;
  • refusal while the opt-in is off;
  • never more permissive than REST, for each role;
  • exclusion from plans.

Exclusions count as reviewed only when review.json carries an exclusion record (named reviewer, date, rationale, safe equivalent). None exist yet, and automated tooling must not author them. See the exclusion review packet.

Protocol features beyond tools:

  • Resource subscriptions (subscriptions/listen) accept only resource URIs the principal can currently read. They allow at most 5 URIs per stream, 2 streams per grant and 32 per process, and each stream lives at most 10 minutes. Change detection polls PostgreSQL every 5 seconds per replica, with no new infrastructure, and never holds a transaction open while streaming.
  • Completions return at most 10 ids, drawn from one authorized, permission-filtered list page. Typed text matches an id prefix or a case-insensitive name or title substring (passed as the list's search when it has one); any failure yields no suggestions, so completion is not an existence oracle.
  • Resource links: a single-entity result includes an opsknight:// link when that resource template is registered, plus a web page link for people (incidents, services, schedules and runbooks).
  • The Tasks extension (io.modelcontextprotocol/tasks) is advertised, but a request receives a task handle only when it declares the extension. tasks/get, tasks/update and tasks/cancel re-authorize the grant on every call. The only task-capable tool is runbook_execute_approved, whose durable state is the native runbook execution (24-hour handle retention). Tasks do not make any other operation asynchronous, and they promise no exactly-once guarantee beyond what the underlying runbook execution provides.
  • MCP Apps are not implemented.

Resource templates are opsknight://incidents/{id}, opsknight://services/{id}, opsknight://schedules/{id}, opsknight://runbooks/{id} , opsknight://reports/{id} and opsknight://postmortems/{id}. There is no unfiltered resource enumeration. Prompts are investigate_incident, summarize_shift, explain_escalation, prepare_postmortem, review_automation_rule, preview_remediation, catch_up, find_precedent, draft_status_update, request_shift_cover and getting_started (11); each is listed only when every tool it relies on is available to the connection.

Default workload policy: four in-flight admitted MCP requests per process (further requests wait up to 750 ms in a bounded queue, and one person may hold at most half the slots, rounded up, across all their connections, before MCP_BUSY), eight operations per request and 60 weighted operations per minute per grant. Fixed safety bounds are 64 KiB request body, depth 24, 256 KiB result budget, default page size set by each list operation (20 when it advertises none; many advertise 25), 50-item maximum page and ten-second cooperative request deadline. These are limits, not measured service capacity. Catalog/resource responses are private with zero TTL. Metrics expose bounded outcome labels and total request duration without user, credential or resource identifiers.

Errors distinguish authentication failure (401), policy/resource denial (403/404), quota (429, with the real Retry-After), workload shedding/disabled service (503), deadline/cancellation (408), invalid arguments and oversized inputs. An oversized result is a tool error with a hint, not a transport failure. Tool errors carry structured content: code, a domainCode only when it is in the application error registry, failing fields (name and rule only), retryable, retryAfterSeconds, hint and requestId. Problem titles, details and stacks are never forwarded. Every code is listed in troubleshooting. Partial-plan successes may be retained even when a later step fails. Routine writes are independently atomic and idempotent; composed workflows are not transactions.

The artifact's parity section groups operations by domain, risk, HTTP method and disposition. It accounts separately for the native approved-runbook equivalent. Remaining unsupported operations are implementation gaps; existing deny reasons remain pending exclusion review, rather than counting as completed parity. This snapshot has 72 unresolved operations. The artifact's byNextStep section triages them:

  • 31 destructive writes need either a reviewed workflow (impact preview, recent sign-in, postcondition) or a named exclusion.
  • 28 private reads and 7 other reads need a projection review or a named exclusion.
  • 3 operations lack a single transaction, a durable receipt or a safe response (updateStatusPage withdraws the public page before its transaction by design; uploadStatusPageAsset exceeds the request bound; previewRunbookExecutionRerun returns an execution authorization token).
  • 3 writes are blocked by a recorded reason (cancelReportExport, createReportExport and createServiceIntegration).

The exclusion review packet proposes a disposition for each. npm run --silent mcp:coverage -- --require-full-parity emits the report and exits nonzero while implementation gaps remain. Ordinary coverage checks classification and contract consistency; final independent review and release certification are separate gates. See full-parity delivery.

postmortem_get_context reads the stored postmortem, action items, contributors and one recent version snapshot in four sequential authorized operations. It is available with postmortems:read and incidents:read (postmortem visibility follows the parent incident, so every postmortem operation declares both) and native read authority while writes are disabled. Each source carries observation time, revision/ETag where provided, and redaction evidence. Reads are not one transactional snapshot; compare revisions before drafting. Authored root-cause text remains an unverified assertion. Follow nextBeforeRevision through listPostmortemVersions for older history (maximum 50 per request). listPostmortemContributors returns the native bounded collaborator projection. The tool does not save drafts, update action items, publish or delete; those eight postmortem mutations remain gaps.

OAuth client identification supports registered clients and Client ID Metadata Documents (client_id is an HTTPS URL). Metadata documents are accepted while Automatic connections is on, under the same scope ceiling as self-registering clients; quick setup turns it on. The optional trusted-hosts list narrows them: empty allows any public HTTPS host, otherwise the host must be listed exactly. The authorization-server metadata advertises client_id_metadata_document_supported only while they are accepted. The URL must be canonical (DNS name, default port, a path, no credentials/query/fragment, at most 256 characters). The document is fetched at authorization time over HTTPS from a pinned public address with no redirects, a 3-second timeout and a 5 KiB cap; every resolved address must be public (private, loopback, link-local, metadata, multicast and transition-embedded ranges are refused). Only redirect_uris (HTTPS, loopback HTTP or a native app scheme, matched as described below) and a display name are used; secret-bearing metadata is refused, and the client's scopes are the administrator's ceiling, never the document's. A metadata client stops working at the next request when its host is removed or the feature is disabled, and revocation is sticky. The scope ceiling is applied to the current policy on every grant resolution, token issue and refresh, so lowering it takes effect immediately for existing access tokens, and a refresh is narrowed to what is still permitted. DNS resolution has its own 3-second budget in addition to the request timeout. Authorization responses carry the RFC 9207 iss parameter. Redirect URIs match exactly, with one exception: a registered loopback redirect (http://localhost, http://127.0.0.1, http://[::1]) also matches the same host, path and query on any port, with no credentials or fragment allowed (RFC 8252 §7.3). This rule applies to registered, self-registered and metadata-document clients alike, so native clients that bind a fresh port at each sign-in work without pre-registering ports. Real-client interoperability for this path has not been certified.

Last updated for v2.2.0

Edit this page on GitHub