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
| Item | Rule |
|---|---|
| Origin | One per application, set by the MCP operator in ATP_MCP_<APP>_BACKEND_URL. https only (http for localhost), no path, no redirects. |
| Paths | Five POST paths under /atp-mcp/v1/, each with a JSON body. |
| Authentication | Authorization: Bearer <service credential>, issued by the backend to one MCP deployment. It is never the user's token. |
| Headers | Content-Type, Accept and X-ATP-MCP-Request-Id (a correlation id for logs). No others. |
| Limits | 10 seconds for the whole exchange, 64 KiB response at most, application/json UTF-8. |
| Retries | None. 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.
| Operation | Path | Request | Response |
|---|---|---|---|
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 |
| Type | Fields |
|---|---|
SessionBinding | sessionRef, chainId (must be the pinned chain), sessionId (32-byte hex) |
JobObservation | jobRef, action (PAY or ACCEPT), kind, upstreamCode, atomId or null, transactionHash or null, observedAt (RFC 3339) |
PreflightObservation | jobRef, 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:
- Resolve
callerto an account on the server side. Never trust tenancy, Root, wallet or action from the request. - Answer a reference the account does not own and one that does not exist identically:
403 REFERENCE_NOT_ACCESSIBLE, same body, comparable latency. - Make
jobs/executeidempotent per job. A repeat returns the same observation and creates no second claim. Reusing arequestIdwith a different job is409 REQUEST_ID_CONFLICT. - Return no lease tokens, calldata, signatures, keys, internal ids, raw upstream bodies or stack traces.
- Report an unknown or ambiguous outcome as
RECONCILIATION_REQUIRED, neverNO_EFFECT. - Echo the requested
jobReforsessionRefexactly. 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.
| Code | HTTP | MCP result |
|---|---|---|
INVALID_REQUEST | 400 | INVALID_INPUT |
SERVICE_UNAUTHENTICATED, SERVICE_FORBIDDEN | 401, 403 | DEPENDENCY_UNAVAILABLE (MCP's credential failed) |
CALLER_NOT_LINKED, REFERENCE_NOT_ACCESSIBLE | 403 | FORBIDDEN |
REQUEST_ID_CONFLICT | 409 | INVALID_INPUT / REQUEST_ID_REUSED |
STALE_STATE | 409 | STALE_STATE |
RECONCILIATION_REQUIRED | 409 | RECONCILIATION_REQUIRED |
BLOCKED_INTEGRATION, BLOCKED_AUTHORITY, BLOCKED_POLICY | 422 | The matching BLOCKED_* category |
RATE_LIMITED | 429 | RATE_LIMITED |
INTERNAL_ERROR, UNAVAILABLE | 500, 503 | DEPENDENCY_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
- Implement the five operations to the schemas and obligations above, with a per-deployment credential and a machine scope for ATP.
- Review and approve the contract and how
{ issuer, subject, clientId }maps to an account. - Pass backend contract tests, including cross-tenant denial that looks like nonexistence, idempotent execute and ambiguous-outcome reporting.
- Have the MCP operator set
ATP_MCP_<APP>_BACKEND_URLand_TOKEN. See Get started. Keep the gates off until the release gates allow otherwise.