Skip to content
SineraDocs

Schemas and contracts

The generated JSON Schemas for each MCP tool, the catalog hash you can check, and the proposed OpenAPI contract for application backends.

The ATP MCP server publishes machine-readable contracts for every tool. This page shows where they live, how to check them and how they are produced.

Not deployed

Maturity

The tool schemas are generated from code and tested locally. The server is not deployed. The adapter API contract is a design proposal that no application implements yet.

Tool schemas

Each tool has an input schema and an output schema, written as JSON Schema draft 2020-12 under schemas/tools/.

ToolScopeRisk classFiles
atp_get_atomatp:readREADatp_get_atom.input.json, atp_get_atom.output.json
atp_get_delegation_sessionatp:readREADatp_get_delegation_session.*.json
atp_get_execution_attemptatp:readREADatp_get_execution_attempt.*.json
atp_simulate_authorized_actionatp:preflightPREFLIGHTatp_simulate_authorized_action.*.json
atp_request_authorized_executionatp:executeEXECUTEatp_request_authorized_execution.*.json
atp_get_execution_resultatp:readREADatp_get_execution_result.*.json

All schemas are strict: unknown keys fail. Sizes are finite. Unsigned integers are canonical decimal strings, and ids are lowercase hex. No schema contains a wallet key, signer token, lease token, arbitrary URL, caller-chosen tenant, calldata or signature. For what each tool does, see Tools.

This is the input of atp_get_atom:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "atomCore": {
      "description": "Lowercase hex address of the pinned ATP AtomCore.",
      "pattern": "^0x[0-9a-f]{40}$",
      "type": "string"
    },
    "atomId": {
      "description": "Lowercase 32-byte hex Atom id.",
      "pattern": "^0x[0-9a-f]{64}$",
      "type": "string"
    },
    "chainId": {
      "description": "Chain id of the pinned ATP deployment.",
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": ["chainId", "atomCore", "atomId"],
  "type": "object"
}

The full file also sets minLength and maxLength on the two hex strings. The locator is the full chainId, atomCore, atomId triple. A locator that names any other deployment is refused before any chain call.

Error result

Every failed tool call returns one shared shape, described in error.output.json:

{
  "status": "ERROR",
  "error": {
    "category": "BLOCKED_INTEGRATION",
    "reasonCode": "BACKEND_BLOCKED_INTEGRATION",
    "retrySafe": false,
    "correlationId": "example-correlation-id"
  }
}

category is one of twelve values: UNAUTHENTICATED, FORBIDDEN, INVALID_INPUT, UNSUPPORTED_PROTOCOL, UNSUPPORTED_DEPLOYMENT, BLOCKED_INTEGRATION, BLOCKED_AUTHORITY, BLOCKED_POLICY, STALE_STATE, RECONCILIATION_REQUIRED, RATE_LIMITED and DEPENDENCY_UNAVAILABLE. reasonCode matches ^[A-Z][A-Z0-9_]{2,63}$. No field carries free text, so nothing from the caller or a backend is echoed back. The correlation id value above is an example.

Catalog and integrity check

catalog.json lists the six tools with title, description, annotations, risk class, required scope, and a SHA-256 hash for each input and output schema. It also records the catalog version, the MCP revision (2026-07-28), the JSON Schema dialect and the hash of the error schema.

{
  "name": "atp_get_atom",
  "requiredScope": "atp:read",
  "riskClass": "READ",
  "annotations": { "readOnlyHint": true, "idempotentHint": true, "destructiveHint": false, "openWorldHint": false },
  "inputSchema": { "file": "atp_get_atom.input.json", "sha256": "55383aa7..." },
  "outputSchema": { "file": "atp_get_atom.output.json", "sha256": "f3fb4a34..." }
}

CATALOG.sha256 holds the hash of the canonical catalog. Hashes are computed over recursively key-sorted, compact JSON, so you can recompute them in any language. To verify a copy you downloaded:

  1. Parse each schema file and re-serialize it with sorted keys and no whitespace.
  2. Compute SHA-256 and compare it with the entry in catalog.json.
  3. Do the same for catalog.json itself and compare with CATALOG.sha256.

The server also serves identical schemas, titles, descriptions and annotations in tools/list for every caller. The served catalog hash equals the committed one.

How they are generated

Never edit schemas/tools/ by hand. The files come from the server's own tool definitions and policy table:

npm run schemas:generate   # rewrite schemas/tools/ from the code
npm run schemas:check      # fail if committed files differ from the code

Rendering is deterministic, so files and hashes change only when a schema, title, description, annotation or policy row changes. Tests fail on stale files, a wrong catalog hash, or any forbidden tool or property name. A change to a published schema is a catalog change and needs a new catalog version.

Identifier patterns are defined once. Tests assert the patterns in the tool schemas, the OpenAPI document and the code are identical.

Adapter API OpenAPI proposal

application-adapter-api-v1.openapi.json is a hand-written OpenAPI 3.1 document, version 1.0.0-proposal. Its status is DESIGN_PROPOSAL. It describes the minimal service-to-service contract an application backend would offer the MCP server. No application implements it, and it grants nothing by itself.

PathPurpose
/atp-mcp/v1/sessions/resolveResolve a session reference for the caller
/atp-mcp/v1/jobs/attemptRead an execution attempt
/atp-mcp/v1/jobs/simulateSimulate an approved job
/atp-mcp/v1/jobs/executeRequest execution of an approved job
/atp-mcp/v1/jobs/resultRead a job result

Backends authenticate the server with a per-application service credential, never the user's token. Responses use closed schemas, echo the requested reference, and report an unknown outcome as RECONCILIATION_REQUIRED. The full rules are in Adapter API. The signer is out of scope: this server never calls it.