MCP operation reference

Named tools, request bodies, permissions and asynchronous results.

Reference · Updated 2026-10-27 · Describes release 0.1.164

Open Settings · Data in → Connect your agent and use the Use your own agent card. The generated configuration binds your client to the current workspace. Start with get_workspace_context; it returns the workspace, your role permissions, the current token scope, the setup guide link and the documentation links (the /help/llms.txt index and the three Quick start pages). Token scope can restrict what your account role normally allows.

A read token is enough for ordinary exploration and the permitted chat, lake-query and IdP-test operations. Tenant writes, connection tests and execution previews need write or admin scope and the relevant workspace permission. Personal, webhook and private-agent token management, and every change that gives another person a login to the workspace — member invites (an activation link is a new login), adding, re-roling or removing a member, the workspace identity provider and an organization administrator's workspace staffing — require admin scope. Every platform-admin tool requires admin scope and a superadmin account; tools backed by tenant routes also retain those routes' tenant permission checks. Approval, change-window, quorum and review requirements apply exactly as in the portal.

The MCP readOnlyHint is operation metadata, not a token-scope grant. Report exports that save an artifact (export_change_stats, export_benchmark_model_report, export_rca and the like) are POST operations and need write scope; some GET downloads available to a read PAT still record an audit row, so a read PAT does not guarantee that no record is persisted. Conversely, an execution preview can be read-only but still require write scope under the current REST policy.

Calling a tool

All known product features are included for enabled tenants and workspaces. Feature grants and terms acceptance are no longer required. The legacy grant, revoke and accept tools are deprecated compatibility no-ops: they do not change availability or create agreement records. Workspace membership, role permissions, token scope and actual connection/runtime setup still apply.

Connection role accepts read, write or read_write. New connections default to allow_approved_execution=false; set it explicitly for a write-capable connection intended for reviewed plans. Changing role clears consent unless explicitly renewed. read_write allows read tools to use the credential, but does not permit investigation tools to write. A plan still requires its exact review and approval.

Prepared incident and standalone Change plans use supported execution_steps with selected_connections when a connection choice is needed. No route creation is required. Route-management tools remain legacy compatibility operations. An invalid or empty structured plan never falls back to a legacy route; clients must follow the returned readiness reason and current review digest. A revert operation (aws.security_group.authorize_ingress, azure.nsg_rule.put or a restore_* operation) is never authored: the platform compiles it from the change ledger's recorded pre-state (Roll back, Draft revert), and a plan that names one is refused as unsupported.

Both servers speak only the Streamable HTTP transport, at the same URL, and accept every MCP revision from 2024-11-05 to 2026-07-28: a client on 2025-11-25 or earlier starts with initialize as before, and a 2026-07-28 client sends stateless requests (server/discover, no session). Every call is an HTTP POST answered with JSON. The older HTTP+SSE transport, where the client opens a GET stream and waits for an endpoint event, is not served: a client set to sse waits for that event until its connect timeout. Set the client's transport to Streamable HTTP (http), as the generated configuration does. serverInfo.version is the platform build.

The server advertises a separate named, typed tool for each operation below. Structured request bodies are normally nested under body; path and query arguments stay outside it. Follow each tool's advertised schema, including its upload argument names. For example:

{
  "name": "patch_datasource",
  "arguments": {
    "ds_id": "CONNECTION_ID",
    "body": {"description": "Production metrics"}
  }
}

A workspace-bound URL supplies tenant automatically. On an unbound connection, supply tenant with the workspace ID or slug when you have more than one workspace. As in the REST API, tenant also reaches the Test Lab workspace of a workspace you belong to and, on the organization (group_*) tools, every workspace of an organization you administer. The bound connection rejects another workspace. Organization-wide and some account-management operations, including password changes and token revocation, require an unbound connection.

Omit a PATCH field to keep it unchanged. null clears a value only where the API permits it. Older tool names listed as aliases use the current advertised schema, including the nested body.

Results contain the HTTP status, canonical result in data, and relevant pagination/download metadata in headers. Errors retain the API's status and explanation. A response with ok: false is also marked as an MCP error, even when its HTTP status is 200. A started job is not a completed job: use get_investigation, get_chat_session, get_xray_scan, get_benchmark or factory_run_detail to read durable progress. Live SSE streams remain on their REST endpoints.

For uploads, pass file: {"filename": "cases.json", "content_base64": "..."}. The transport accepts up to 16 MiB of decoded file content; individual API limits still apply, including the 5 MiB document/Discovery attachment limit. Local file paths are never accepted. Download operations return the saved content and content type.

For a remediation, call preview_remediation with a write or admin token, show the exact payload in data to the user, then pass data.digest as body.review_digest to remediate_incident. Typed incident plans select a scoped execution-capable connection with explicit approved-plan consent, without a pre-created route. Include the same body.selected_connections in preview and release when choosing among matching connections. Use body.request_only=true to request human approval without executing; that is all an operator (incidents.act without approvals.decide) can do. Releasing needs approvals.decide, which the builtin approver, executive and owner roles hold; an L3 release needs two different people. If the plan, target, connection or policy changes, review again. A second approval or closed change window still prevents execution; opening a GitOps pull request is not evidence that the fix has landed.

For a Change action, use preview_change_execution, then include data.digest as body.review_digest when approving or executing. Prepared incident changes and standalone Changes with structured execution_steps need no route ID. Include the same body.selected_connections in preview and release when making a per-step connection choice. Historical route-based API clients retain body.route_id; a conceptual approval cannot approve an action selected later. A changed action needs fresh approvals. If execution is uncertain, inspect the target and reconcile the recorded outcome; reconciliation never authorizes automatic replay or proves recovery.

To suppress resources a compliance control flagged (EST-01 to EST-06), call accept_control_exception (the operation keeps its risk-acceptance name) with body.resource_keys taken from the control's latest evidence (get_compliance_control or the incident's control), a body.risk_statement — the reason — of at least 10 characters and an optional body.expires_at (default 90 days, at most 365). A suppression is a request: each resource lands in the risk register as requested and nothing changes until an approver other than the requester calls approve_risk_decision with its decision id (the requester may approve only when nobody else in the workspace holds approvals.decide) or reject_risk_decision with a body.note. decide_finding sends a scanner finding's risk decision the same way. Suppressing fixes nothing on the resource and is never a pass. When other resources stay flagged after an approval, a non-empty exception.reanalysis_id in that approval's response is the fresh analysis it started so the fix plan leaves the suppressed resources out; a plan drafted before the suppression can no longer be released. Revoke an approved decision through revoke_decision. Removed in 0.1.95: suppress_finding (POST /api/aiops/{tenant_id}/incidents/{incident_id}/suppress-rule) — clients that called it must move to accept_control_exception. Existing muted entries stop muting 90 days after they were set.

Common tasks

• What is waiting on me: needs_you lists every decision waiting on a person, most urgent first: incidents awaiting approval, escalated incidents, change approvals, merge proposals, risk requests, post-implementation reviews and routes a rollback or a deviated fix demoted, with a count per type; pass type to page through one kind. list_pending_approvals holds only the tool-call approvals of paused analyses.
• Ticket systems: discover_ticket_system checks a Jira, ServiceNow or Azure DevOps connection without writing to it. send_test_ticket files a real ticket through the route and closes it again. retry_incident_ticket retries a failed filing or write-back, or writes back to a customer's own ticket that was left to a person.
• Several connections into one account: an AWS or Azure read connection runs four jobs unless its config switches one off with false: harvest_inventory, platform_checks, sync_findings and harvest_changes; an AWS one also runs service_map, and builtin_detection while the workspace has built-in detection on. A patch_datasource config replaces the whole config: read the connection's current config from list_datasources, change only the switch and send all of it back. A config holding only the switches drops every other key, such as the role ARN, region or subscription, and the jobs left on then fail.
• Workspace toggles without their own tool: send them in patch_tenant body.settings, for example aiops_prompt_cache and aiops_prompt_diet (true, false, or null for the platform default); get_tenant reads them back. The benchmark run tools take prompt_diet the same way to measure both arms on one build, and compare_benchmark names each run's arm.
• Fix some resources now: reinvestigate_incident with body.defer = the open resources of a scanner incident (resource ARN, else the resource) to leave out of THIS analysis — a maintenance window, downtime. Not a decision: they stay open and nothing expires; the change request lists them as Not in this run and a certified runbook never releases that change on its own.
• Retention: preview_retention_sweep shows what the next sweep would remove and writes nothing; run_retention_sweep with body.dry_run=false seals the affected months' usage statements and deletes the closed records past the window.

Workspace operations

Platform operations

These tools are available at /mcp/admin and require a superadmin with an admin-scope PAT or SSO identity.

Separate protocols

Browser login/OIDC redirects, incoming webhooks, internal private-agent claims/checkpoints/secrets, the OpenAI-compatible agent facade, and live SSE streams keep their own protocols. They are not generic MCP tools. MCP cannot choose an arbitrary URL, HTTP method or Authorization header for an operation.

The source catalogue is app/mcp_operations.json. Regenerate both copies of this reference with python scripts/render-mcp-reference.py from the repository root. A coverage check fails if a new management route has no reviewed binding or an existing binding loses its REST route.

Next steps

• Next: Admin MCP server
• All Reference pages
• Documentation home