Skip to content
SineraDocs

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.

ConcernOwner
Job identity, commercial terms, idempotency, claims and attemptsThe owning application's job ledger
Signing mechanicsAn isolated signer inside the application. MCP never calls it and never sees its credentials.
Delegation and Atom stateATP contracts
Reporting observations and verifying finalityMCP

MCP keeps no execution database of its own. See Authorization for scopes and gates.

Simulate, then request, then read

  1. Simulate. Call atp_simulate_authorized_action with a jobRef. It needs the atp:preflight scope and the operator gate ATP_MCP_PREFLIGHT_ENABLED_APPS. MCP forwards the caller and jobRef to the backend and gets back wouldSucceed, a list of named checks and observedAt.
  2. Read the verdict as an observation. MCP rejects any answer with unknown fields (for example calldata). wouldSucceed: true needs at least one check and every check passed, and the echoed jobRef must match. The result always carries authorizes: false.
  3. Request. Call atp_request_authorized_execution with jobRef and a requestId. It needs atp:execute and the gate ATP_MCP_EXECUTION_ENABLED_APPS. MCP sends one request to the backend and never retries.
  4. Read the observation. The backend answers with one of QUEUED, HELD, SUBMITTED, RECONCILIATION_REQUIRED, CONFIRMED, NO_EFFECT or REJECTED. Blocking is an error result with a category, not an observation.
  5. Read the result. Call atp_get_execution_result. If the ledger says CONFIRMED with an Atom id, MCP also reads that Atom from the chain at a finalized block. Only chainReadback.status = ATOM_OBSERVED is 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 requestId with a different jobRef is rejected with HTTP 409 REQUEST_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.

SituationResultretrySafe
Malformed jobRef or requestId, or an invalid caller assertion, caught before any network callINVALID_INPUT or DEPENDENCY_UNAVAILABLE with a reason such as JOB_REF_INVALID, REQUEST_ID_INVALID, CALLER_ASSERTION_INVALIDfalse
Caller cancelled the request before it was sentDEPENDENCY_UNAVAILABLE / EXECUTION_NOT_SENT. Zero backend calls were made.false
Timeout, abort mid-flight, network error, redirect, 5xx, invalid or oversized body, unknown error codeRECONCILIATION_REQUIRED / EXECUTION_OUTCOME_UNKNOWNfalse
Backend answers a different jobRefRECONCILIATION_REQUIREDfalse
Output fails strict validationRECONCILIATION_REQUIRED / BACKEND_RESPONSE_INVALIDfalse
Backend well-formed 4xx such as STALE_STATE or REFERENCE_NOT_ACCESSIBLEThe mapped category, not reconciliationfalse

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.

EventAllowed resultForbidden reaction
Timeout after the backend was invokedRECONCILIATION_REQUIREDSend the same payment again
Indexer lag after a mined transactionSUBMITTED with evidenceForce state in an application database
Delegation revokedBLOCKED_AUTHORITYReuse an earlier approval or pick another Root
Job belongs to another tenantFORBIDDEN, redactedConfirm that the job exists

For worked JSON, see Worked examples. For the chain side of the readback, see ATP binding and chain reads.