MCP Actions
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.
| Tool | What it does | Arguments |
|---|---|---|
start_audit | Starts 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_batch | Starts 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_draft | Writes 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_recommendation | Moves 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_operation | The 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_auditorstart_audit_batchqueues 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. idempotencyKeyis 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 withget_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:
| Step | Tool | Arguments |
|---|---|---|
| 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.