Skip to content
SineraDocs

Application Adapter API

The proposed backend contract an application must implement before the ATP MCP server can read or run its jobs.

Not deployed

The Application Adapter API is the narrow, service-to-service interface the ATP MCP server calls on an application's backend. It is a design proposal. No application implements it today, so five of the six MCP tools cannot succeed yet. This page is for backend owners who are deciding whether to build it. Tool behavior is in the Tool reference, and the apps involved are in Integrations.

Why it exists

The MCP server must not own accounts, jobs, idempotency or signing. The application that owns a job already has its own claim, session check, simulation, signing and reconciliation steps. The adapter API lets MCP ask that application questions while MCP stays a thin client that fails closed. No lease token or signer credential ever reaches MCP or a model.

Transport and authentication

ItemRule
OriginOne per application, set by the MCP operator in ATP_MCP_<APP>_BACKEND_URL. https only (http for localhost), no path, no redirects.
PathsFive POST paths under /atp-mcp/v1/, each with a JSON body.
AuthenticationAuthorization: Bearer <service credential>, issued by the backend to one MCP deployment. It is never the user's token.
HeadersContent-Type, Accept and X-ATP-MCP-Request-Id (a correlation id for logs). No others.
Limits10 seconds for the whole exchange, 64 KiB response at most, application/json UTF-8.
RetriesNone. MCP never resends jobs/execute.

Operations

Every request body is { caller, <reference> }, where caller is { issuer, subject, clientId }. Each value is visible ASCII without spaces, 1 to 255 characters. The caller object is not a credential. The backend must map it to an account with its own records and must not accept tenant, Root, wallet or action fields. Schemas reject extra properties.

OperationPathRequestResponse
resolveSession/atp-mcp/v1/sessions/resolve{ caller, sessionRef }SessionBinding
getExecutionAttempt/atp-mcp/v1/jobs/attempt{ caller, jobRef }JobObservation
simulateAuthorizedAction/atp-mcp/v1/jobs/simulate{ caller, jobRef }PreflightObservation
requestAuthorizedExecution/atp-mcp/v1/jobs/execute{ caller, jobRef, requestId }JobObservation
getExecutionResult/atp-mcp/v1/jobs/result{ caller, jobRef }JobObservation
TypeFields
SessionBindingsessionRef, chainId (must be the pinned chain), sessionId (32-byte hex)
JobObservationjobRef, action (PAY or ACCEPT), kind, upstreamCode, atomId or null, transactionHash or null, observedAt (RFC 3339)
PreflightObservationjobRef, action, wouldSucceed, checks (up to 32 of { name, passed, code }), observedAt

kind is QUEUED, HELD, SUBMITTED, RECONCILIATION_REQUIRED, CONFIRMED, NO_EFFECT or REJECTED. CONFIRMED requires a transaction hash. wouldSucceed: true requires at least one check and every check passed.

A minimal request:

POST /atp-mcp/v1/jobs/attempt
Authorization: Bearer <service credential>
Content-Type: application/json
 
{
  "caller": { "issuer": "https://auth.example.org", "subject": "user-123", "clientId": "my-client" },
  "jobRef": "job-synthetic-0001"
}

Backend obligations

The backend must:

  1. Resolve caller to an account on the server side. Never trust tenancy, Root, wallet or action from the request.
  2. Answer a reference the account does not own and one that does not exist identically: 403 REFERENCE_NOT_ACCESSIBLE, same body, comparable latency.
  3. Make jobs/execute idempotent per job. A repeat returns the same observation and creates no second claim. Reusing a requestId with a different job is 409 REQUEST_ID_CONFLICT.
  4. Return no lease tokens, calldata, signatures, keys, internal ids, raw upstream bodies or stack traces.
  5. Report an unknown or ambiguous outcome as RECONCILIATION_REQUIRED, never NO_EFFECT.
  6. Echo the requested jobRef or sessionRef exactly. MCP treats a mismatch as a confused-deputy signal and rejects it.

Errors

Errors use { "error": { "code", "retryable" } }. Each code is bound to one HTTP status. A mismatched pair, an unknown code or an extra field is treated as an invalid response.

CodeHTTPMCP result
INVALID_REQUEST400INVALID_INPUT
SERVICE_UNAUTHENTICATED, SERVICE_FORBIDDEN401, 403DEPENDENCY_UNAVAILABLE (MCP's credential failed)
CALLER_NOT_LINKED, REFERENCE_NOT_ACCESSIBLE403FORBIDDEN
REQUEST_ID_CONFLICT409INVALID_INPUT / REQUEST_ID_REUSED
STALE_STATE409STALE_STATE
RECONCILIATION_REQUIRED409RECONCILIATION_REQUIRED
BLOCKED_INTEGRATION, BLOCKED_AUTHORITY, BLOCKED_POLICY422The matching BLOCKED_* category
RATE_LIMITED429RATE_LIMITED
INTERNAL_ERROR, UNAVAILABLE500, 503DEPENDENCY_UNAVAILABLE on reads, RECONCILIATION_REQUIRED on execute

On jobs/execute, any timeout, network error, redirect, schema violation or 5xx becomes RECONCILIATION_REQUIRED / EXECUTION_OUTCOME_UNKNOWN, and MCP never reports retrySafe: true.

Before you connect an application

  1. Implement the five operations to the schemas and obligations above, with a per-deployment credential and a machine scope for ATP.
  2. Review and approve the contract and how { issuer, subject, clientId } maps to an account.
  3. Pass backend contract tests, including cross-tenant denial that looks like nonexistence, idempotent execute and ambiguous-outcome reporting.
  4. Have the MCP operator set ATP_MCP_<APP>_BACKEND_URL and _TOKEN. See Get started. Keep the gates off until the release gates allow otherwise.