MCP Actions

3 min readLast updated View as MarkdownAgent setup

Actions

With Allow actions on in the grant, these tools are also available. Each is the Public API’s action of the same name: the same checks, the same limits and the same result.

ToolWhat it doesArguments
start_auditStarts an audit of one project’s store app and answers its operation. The audit runs for several minutes: follow it with get_operation, then get_audit with the audit id the operation lists. Asks you to confirm first where your client can.orgId, projectId, idempotencyKey; store
start_audit_batchStarts one audit per listed project as one operation. Every project is checked before anything starts. Follow it with get_operation. Asks you to confirm first where your client can.orgId, items, idempotencyKey
create_revision_draftWrites text into a project’s working draft listing for one store, for a person to review and publish in Apptonomy. Nothing is published. Name the accepted recommendation the text implements, if any.orgId, projectId, store, fields, idempotencyKey; recommendationId, baseRevision
transition_recommendationMoves a recommendation to open, accepted, deferred, resolved or dismissed — for every audit that observed it (its stableKey) — and records who, why and when. Pass the stateVersion you read as expectedVersion. From resolved or dismissed it can only go back to open.orgId, recommendationId, to, expectedVersion, idempotencyKey; reason, deferredUntil, resolution, draftRevisionId
get_operationThe status of an operation start_audit, start_audit_batch, create_revision_draft or transition_recommendation queued: its state, each item’s end, and the audits, revision or recommendation it produced.orgId, operationId
  • Confirming. Starting audits counts against your organization’s quota and its plan’s audit cadence, so before start_audit or start_audit_batch queues anything, the client asks you to confirm — where the client can ask (MCP elicitation). Decline and nothing is queued. A client that can’t ask shows these tools as ones that change data, and asks you for permission itself before it runs one.
  • idempotencyKey is a value the client picks for each new request. The client can repeat a call with the same key and arguments safely: it gets the same operation back, and nothing starts twice.
  • What the client gets back is an operation: follow it with get_operation, then the audit itself with get_audit — an audit runs for several minutes. A draft and a recommendation’s new state are written before the tool answers.
  • Who it acts as. An audit the client starts runs as you, and the audit shows you started it. A draft or a recommendation’s change records you and the client.
  • Your role. Every role can start audits, write drafts and change a recommendation’s state, as in the app. The grant must also let the client read recommendations to change one. Publishing a draft stays in the app.
  • A draft written this way waits in Apptonomy’s listing editor, like any other draft, until someone reviews and publishes it.

A typical session, as a client’s tool log shows it:

StepToolArguments
Which organizations this connection reaches, your role in each, and whether this client is granted there.list_organizations{}
The organization’s projects.list_projects{"orgId":"<ORG_ID>"}
The project’s latest completed audit.list_audits{"projectId":"<PROJECT_ID>","status":"completed","limit":1}
That audit’s open recommendations.list_recommendations{"projectId":"<PROJECT_ID>","auditId":"<AUDIT_ID>","status":"open"}
One recommendation with its provenance.get_recommendation{"projectId":"<PROJECT_ID>","recommendationId":"<RECOMMENDATION_ID>"}

Every tool result and every refusal from Apptonomy includes a requestId (an argument the client sent in the wrong shape is refused by the MCP layer before it reaches Apptonomy, and has none). Recommendations, scores and impact results carry provenance: which statements were measured, which were derived, which are AI interpretations, and the sources behind each — so you can check what the client tells you against where it came from. Ask the client to show its sources.