Preflight and execution
How a job moves from simulation to an execution request to a result, and why an unknown outcome is never retried.
The ATP MCP server never builds or signs a transaction. It asks the application that owns a job to simulate it, to run it, and to report what happened. This page follows that path and explains what the server does when the answer is unclear.
Not deployed
Current status
The server is not deployed. It has been tested locally against in-memory fakes only. Execution is gated off by default. No application implements the adapter API yet, so no execution has ever been requested through it, and none has run on a testnet. There has been no independent security review yet.
Who owns what
MCP receives only a non-secret job reference (jobRef). Commercial terms come from an approved record in the owning application's backend.
| Concern | Owner |
|---|---|
| Job identity, commercial terms, idempotency, claims and attempts | The owning application's job ledger |
| Signing mechanics | An isolated signer inside the application. MCP never calls it and never sees its credentials. |
| Delegation and Atom state | ATP contracts |
| Reporting observations and verifying finality | MCP |
MCP keeps no execution database of its own. See Authorization for scopes and gates.
Simulate, then request, then read
- Simulate. Call
atp_simulate_authorized_actionwith ajobRef. It needs theatp:preflightscope and the operator gateATP_MCP_PREFLIGHT_ENABLED_APPS. MCP forwards the caller andjobRefto the backend and gets backwouldSucceed, a list of named checks andobservedAt. - Read the verdict as an observation. MCP rejects any answer with unknown fields (for example calldata).
wouldSucceed: trueneeds at least one check and every check passed, and the echoedjobRefmust match. The result always carriesauthorizes: false. - Request. Call
atp_request_authorized_executionwithjobRefand arequestId. It needsatp:executeand the gateATP_MCP_EXECUTION_ENABLED_APPS. MCP sends one request to the backend and never retries. - Read the observation. The backend answers with one of
QUEUED,HELD,SUBMITTED,RECONCILIATION_REQUIRED,CONFIRMED,NO_EFFECTorREJECTED. Blocking is an error result with a category, not an observation. - Read the result. Call
atp_get_execution_result. If the ledger saysCONFIRMEDwith an Atom id, MCP also reads that Atom from the chain at a finalized block. OnlychainReadback.status = ATOM_OBSERVEDis canonical evidence.
A passed simulation does not prove allowance, funds, inventory, settlement or the current deadline. The backend repeats the checks when it submits. See Tool reference for exact inputs and outputs.
Job references and idempotency
jobRef identifies the approved job in the application's ledger. requestId identifies one MCP request. It is a replay key and nothing more: it is not the job identity, an ATP intent salt, a transaction nonce or a signer lease.
The backend is responsible for these rules, and MCP cannot prove them:
- Repeating an execute for one job returns the same authoritative observation. It never creates a second claim, attempt or commercial intent.
- Reusing a
requestIdwith a differentjobRefis rejected with HTTP 409REQUEST_ID_CONFLICT. - A durable attempt record exists before any unsafe submission.
MCP itself does not deduplicate. Each identical call is forwarded as it is.
Outcome unknown versus provably not sent
The server separates two kinds of failure on the execute path.
| Situation | Result | retrySafe |
|---|---|---|
Malformed jobRef or requestId, or an invalid caller assertion, caught before any network call | INVALID_INPUT or DEPENDENCY_UNAVAILABLE with a reason such as JOB_REF_INVALID, REQUEST_ID_INVALID, CALLER_ASSERTION_INVALID | false |
| Caller cancelled the request before it was sent | DEPENDENCY_UNAVAILABLE / EXECUTION_NOT_SENT. Zero backend calls were made. | false |
| Timeout, abort mid-flight, network error, redirect, 5xx, invalid or oversized body, unknown error code | RECONCILIATION_REQUIRED / EXECUTION_OUTCOME_UNKNOWN | false |
Backend answers a different jobRef | RECONCILIATION_REQUIRED | false |
| Output fails strict validation | RECONCILIATION_REQUIRED / BACKEND_RESPONSE_INVALID | false |
Backend well-formed 4xx such as STALE_STATE or REFERENCE_NOT_ACCESSIBLE | The mapped category, not reconciliation | false |
Only failures raised before the request left the server count as "not sent". Every other failure is treated as unknown, because a timeout does not prove the backend or chain did nothing. A worker can keep running after the caller gives up.
When retry is never safe
MCP never reports an execute call as retry-safe. Even a backend error that marks itself retrySafe is reported as retrySafe: false.
Do not resend after RECONCILIATION_REQUIRED. Read atp_get_execution_attempt and atp_get_execution_result for the same jobRef and contact the application owner. The backend reconciles ambiguous or failed attempts against finalized chain evidence. NO_EFFECT is the only observation after which a retry may be considered, and that decision belongs to the backend.
| Event | Allowed result | Forbidden reaction |
|---|---|---|
| Timeout after the backend was invoked | RECONCILIATION_REQUIRED | Send the same payment again |
| Indexer lag after a mined transaction | SUBMITTED with evidence | Force state in an application database |
| Delegation revoked | BLOCKED_AUTHORITY | Reuse an earlier approval or pick another Root |
| Job belongs to another tenant | FORBIDDEN, redacted | Confirm that the job exists |
For worked JSON, see Worked examples. For the chain side of the readback, see ATP binding and chain reads.