Tool reference
The six fixed tools of the ATP MCP server, with scope, inputs, outputs and errors.
Not deployed
The ATP MCP server exposes six fixed tools. The tool list is identical for every caller, and authorization is checked on each call. There is no raw-transaction, signing, URL-fetch or arbitrary-call tool.
Conventions
| Topic | Rule |
|---|---|
| Arguments | Strict objects. Unknown fields are rejected. Hex is lowercase. No argument selects an application, tenant, Root, wallet, action, amount or URL. |
| References | jobRef, sessionRef and requestId are opaque. They use dot-separated segments of A-Za-z0-9_:-, start with an alphanumeric character, and are at most 128 characters. A requestId has 8 to 128 characters, so a UUID works. |
| Success | structuredContent matches the tool's output schema. |
| Failure | isError: true with { status: "ERROR", error: { category, reasonCode, retrySafe, correlationId } }. No upstream text or stack is returned. Quote the correlationId to the operator. |
| Evidence | Chain results carry evidence with finality: "FINALIZED". This is chain finality of the block, not the ATP Atom state FINALIZED. |
| Meaning | Every result is an observation. None is a permission, approval or settlement claim. |
| Tool | Risk class | Scope | Operator gate | Needs backend |
|---|---|---|---|---|
atp_get_atom | READ | atp:read | None | No |
atp_get_delegation_session | READ | atp:read | None | Yes |
atp_get_execution_attempt | READ | atp:read | None | Yes |
atp_simulate_authorized_action | PREFLIGHT | atp:preflight | ATP_MCP_PREFLIGHT_ENABLED_APPS | Yes |
atp_request_authorized_execution | EXECUTE | atp:execute | ATP_MCP_EXECUTION_ENABLED_APPS | Yes |
atp_get_execution_result | READ | atp:read | None | Yes |
"Backend" is the backend of the caller's own application. If none is configured, the tool answers BLOCKED_INTEGRATION. Today no application implements the adapter API, so only atp_get_atom can succeed.
atp_get_atom
Reads one Atom from the pinned AtomCore contract at the finalized block.
| Input | Type | Notes |
|---|---|---|
chainId | integer | Must be the pinned chain, 97. |
atomCore | 20-byte hex | Must be the pinned AtomCore address. |
atomId | 32-byte hex | The Atom to read. |
Scope: atp:read. It calls the chain reader only.
The result is FOUND with atom and evidence, or NOT_FOUND with atomId and evidence. The atom has state (PENDING_ACCEPTANCE, PENDING_REACCEPTANCE, ACTIVE, DISPUTED, FINALIZED), terminalOutcome, configId, completionMode, rootBuyer, rootSeller, objectRef, assetId, quantity, dispute and finalization fields, and sellerShareBps.
Errors include UNSUPPORTED_DEPLOYMENT, STALE_STATE (the finalized block is older than 120 seconds), DEPENDENCY_UNAVAILABLE, INVALID_INPUT, FORBIDDEN and RATE_LIMITED. NOT_FOUND only means the Atom was absent at that block.
atp_get_delegation_session
Resolves an application-issued session reference through the caller's application, then reads that delegation session at the finalized block.
| Input | Type | Notes |
|---|---|---|
sessionRef | string | Issued by the application. Raw on-chain session ids are not accepted. |
Scope: atp:read. The result is FOUND (sessionRef, session, evidence) or NOT_FOUND. The session reports root, delegate, configId, settlementToken, actionMask, the decoded actions, validUntil, active, the epochs, the spend caps and the four scope hashes. Zero caps are reported as stored and are not interpreted.
The actions are a subset of BUY_CREATE_AND_ESCROW, SELL_ACCEPT_ORIGINAL, SELL_PROPOSE_REVISION, BUY_REACCEPT_TERMS and BUY_CONFIRM_COMPLETION. An unowned reference and a nonexistent one look the same: FORBIDDEN / REFERENCE_NOT_ACCESSIBLE.
atp_get_execution_attempt
Returns what the owning application's ledger reports for one approved job.
| Input | Type | Notes |
|---|---|---|
jobRef | string | An approved job in the caller's application. |
Scope: atp:read. The result is { status: "OBSERVED", source: "APPLICATION_LEDGER", job }. The job has jobRef, action (PAY or ACCEPT), kind, upstreamCode, atomId, transactionHash and observedAt.
kind is one of QUEUED, HELD, SUBMITTED, RECONCILIATION_REQUIRED, CONFIRMED, NO_EFFECT, REJECTED. This is a ledger observation, not chain state. SUBMITTED is not finalized, and CONFIRMED is only a ledger claim.
atp_simulate_authorized_action
Asks the owning backend to re-check and simulate the exact action of one approved job.
| Input | Type | Notes |
|---|---|---|
jobRef | string | The job to simulate. |
Scope: atp:preflight, and the caller's application must be listed in ATP_MCP_PREFLIGHT_ENABLED_APPS.
The result is { status: "OBSERVED", source: "APPLICATION_BACKEND_SIMULATION", authorizes: false, preflight }. The preflight has jobRef, action, wouldSucceed, checks (each with name, passed, code) and observedAt. wouldSucceed: true needs at least one check and all checks passed. With the gate off, the error is BLOCKED_POLICY / PREFLIGHT_DISABLED and the backend is not called.
A passing simulation does not authorize execution or guarantee on-chain success. authorizes is always false.
atp_request_authorized_execution
Asks the owning backend to run one job it already approved.
| Input | Type | Notes |
|---|---|---|
jobRef | string | The approved job. |
requestId | string | Caller-generated replay key, 8 to 128 characters. A UUID works. |
Scope: atp:execute, and the application must be listed in ATP_MCP_EXECUTION_ENABLED_APPS. The tool accepts no amount, payee, wallet, token, transaction data or signature. The server calls the backend once and never retries.
The result is { status: "OBSERVED", source: "APPLICATION_LEDGER", requestId, job }. It is the ledger state at request time, never a success claim.
If a timeout, network error, 5xx or invalid answer happens after the request may have left the server, the error is RECONCILIATION_REQUIRED / EXECUTION_OUTCOME_UNKNOWN with retrySafe: false. That is never "no effect". Do not resend. Read atp_get_execution_attempt and atp_get_execution_result for the same jobRef, and contact the application owner.
atp_get_execution_result
Returns the ledger observation for one job. When the ledger reports CONFIRMED with an Atom id, it also reads that Atom from the chain.
| Input | Type | Notes |
|---|---|---|
jobRef | string | The job to look up. |
Scope: atp:read. The result is { status: "OBSERVED", source: "APPLICATION_LEDGER", job, chainReadback }.
chainReadback.status | Meaning |
|---|---|
ATOM_OBSERVED | The Atom exists at the finalized block. This is the only canonical evidence of the Atom. |
ATOM_NOT_OBSERVED_AT_FINALIZED_BLOCK | The ledger says confirmed, but the Atom is not there. Do not treat the job as done. |
UNAVAILABLE | The readback failed. The ledger claim stands unconfirmed. |
NOT_PERFORMED | No readback was tried: the ledger kind was not CONFIRMED, or it had no Atom id. |
A chain failure never fails the whole call and never upgrades a ledger claim.
Error results
| Field | Values |
|---|---|
category | UNAUTHENTICATED, FORBIDDEN, INVALID_INPUT, UNSUPPORTED_PROTOCOL, UNSUPPORTED_DEPLOYMENT, BLOCKED_INTEGRATION, BLOCKED_AUTHORITY, BLOCKED_POLICY, STALE_STATE, RECONCILIATION_REQUIRED, RATE_LIMITED, DEPENDENCY_UNAVAILABLE |
reasonCode | A stable upper-snake-case machine code. Never free text. |
retrySafe | true only when repeating the identical request is proven harmless, such as a pure read. Never true for execution. |
correlationId | Server-generated. Also sent in the X-Correlation-Id header. |
Per-tool denials, such as a missing scope or a gate that is off, are tool results with isError: true, not HTTP errors. For HTTP-level failures see Authorization.