Build an Adapter

Adapters are the Action-plane boundary between a model-proposed plan and an external system. They are typed, versioned execution contracts—not API wrappers. The protocol moves a request; the ContextOS binding decides whether that request is admissible and what evidence it must leave.

For profile-aware work, bind the admitted adapter release to the Execution Contract. Control Profiles add requirements from actual enabled features, including active code/tool boundaries, credential and egress mediation, data routes, shared budgets and recovery. A supported protocol or schema-valid manifest is insufficient evidence that those controls run; Conformance requires useful and denied cases against the real deployment.

The production rule

An adapter must answer these questions without consulting model prose:

If any answer is “the model knows,” “the description says,” or “the server advertised it,” the adapter is not admitted.

Choose the narrowest path

MCP and A2A are profiles, not prerequisites. Every path normalizes into the same ContextOS envelopes.

Current standards profile

New MCP work targets MCP 2026-07-28. Existing 2025-11-25 servers may use a separately tested compatibility profile.

For protocol details and migration rules, use the MCP integration profile.

Architecture

Planner proposal
  -> Critic verification
  -> Tool Gateway
       manifest + identity + policy + ActionRisk + approval
       args + destination + budget + idempotency
  -> MCP / A2A / OpenAPI / function / connector
  -> schema + postcondition validation
  -> ToolResultEnvelope
  -> Critic score
  -> DecisionRecord + replay material

The Tool Gateway, not the adapter protocol, owns final execution admission.

Build sequence

Classify against the actual arguments, not only the tool name. A generic operation whose risk changes arbitrarily with its payload is too broad.

Adapter manifest

The manifest is the reviewed admission artifact. Live protocol discovery can confirm compatibility, but it cannot replace this contract.

{
  "adapter_id": "adp_payments_mcp",
  "version": "2.0.0",
  "owner_role": "payments_platform",
  "protocol": {
    "kind": "mcp",
    "profile": "2026-07-28",
    "transport": "streamable_http",
    "endpoint_ref": "https://payments.example.com/mcp",
    "extensions": ["io.modelcontextprotocol/tasks"]
  },
  "auth": {
    "type": "oauth2",
    "resource": "https://payments.example.com/mcp",
    "issuer_allowlist": ["https://identity.example.com"],
    "allow_token_passthrough": false
  },
  "capabilities": [
    {
      "capability_id": "payments.lookup_transaction",
      "protocol_tool": "payments_lookup_transaction",
      "capability_class": "observe",
      "action_risk": {
        "effect": "none",
        "authority": "service",
        "reversibility": "read_only",
        "interaction": "api",
        "data_scope": "CONFIDENTIAL",
        "decision_ttl_seconds": 300
      },
      "approval_mode": "network",
      "input_schema_ref": "schema://payments.lookup_transaction.input.v1",
      "output_schema_ref": "schema://payments.lookup_transaction.output.v1",
      "evidence_keys": ["transaction_id", "status", "settlement_ref"]
    },
    {
      "capability_id": "payments.issue_refund",
      "protocol_tool": "payments_issue_refund",
      "capability_class": "act",
      "action_risk": {
        "effect": "external_state",
        "authority": "user_delegated",
        "reversibility": "compensatable",
        "interaction": "api",
        "data_scope": "CONFIDENTIAL",
        "decision_ttl_seconds": 120
      },
      "approval_mode": "destructive",
      "requires_approval_gate": "GATE_FINANCE_APPROVAL",
      "arg_constraints": {
        "amount_inr": { "min": 1, "max": 50000 },
        "currency": { "enum": ["INR"] }
      },
      "idempotency": {
        "required": true,
        "dedup_window_seconds": 86400
      },
      "postcondition": "refund_exists_for_transaction",
      "recovery": "compensation_token_required",
      "evidence_keys": ["refund_id", "transaction_id", "reversal_token"]
    }
  ],
  "observability": {
    "trace_context": "w3c",
    "metrics": ["latency_ms", "retry_count", "upstream_status", "cost_cents"]
  },
  "kill_switch_ref": "registry://adapters/adp_payments_mcp/revoke"
}

The schema above is an integration blueprint, not a new published ContextOS schema. A deployment should validate its manifest format and version it independently.

Tool design

Use JSON Schema 2020-12 unless a protocol or upstream system requires a different dialect. Keep ContextOS metadata in the adapter binding unless the protocol provides a clearly namespaced extension point.

Protocol objects are not equally trusted

Discovery metadata and returned content are untrusted evidence. Neither can alter the registered principal, scope, destination, risk ceiling, or approval status.

Input-required and durable work

For MCP multi-round-trip input:

1. persist the input_required result and request state;
2. validate that each requested input type is supported;
3. apply consent, redaction, approval, and identity policy;
4. retry the original request with inputResponses and a new protocol request id; and
5. preserve stable ContextOS operation identity, any provider idempotency key and originating run lineage when the same admitted action continues.

Protocol request IDs are attempt identifiers, not business-operation identity. If returned input changes the bound action, arguments, destination or release, invalidate the old approval and construct the appropriate new authorized proposal; a continuation cannot edit an already approved operation’s immutable action. A broken response after possible dispatch remains unknown until the declared provider contract makes recovery safe.

For the Tasks extension, authenticate and authorize tasks/get, tasks/update, and cancellation individually. Scope handles to the original relationship, generate them with high entropy, and never expose a task-listing backchannel. Resuming a task does not reset ContextOS budget or approval state.

A2A tasks follow the same principle: the remote task lifecycle is interoperability state; ContextOS still owns the narrowed delegation envelope and parent/child evidence linkage.

Error model

Transport and authorization

• For stdio, launch a pinned command, keep protocol data on stdout/stdin, send logs to stderr, sandbox the process, and minimize filesystem/network access.
• For Streamable HTTP, validate Origin, authenticate every request, bind tokens to issuer and resource, constrain redirects/egress, and apply request/body/time limits.
• For MCP 2026-07-28, do not implement protocol sessions or resumable SSE. Any permitted reissue uses a new protocol request id while retaining stable operation identity and any provider key for the same bound action. The transport’s new-request requirement does not authorize an unsafe write retry; reconcile uncertain effects first.
• Never pass through a user token minted for another service. Exchange for a short-lived, capability-bound credential when possible.
• Keep authorization independent from application-level approval: OAuth scope does not prove tenant eligibility, evidence sufficiency, user intent, or approval-gate completion.

Supply-chain admission

Pin and verify:

• publisher/owner and source revision;
• manifest and schema hashes;
• executable or image digest;
• dependencies and build provenance;
• protocol/profile compatibility;
• requested destinations, scopes, data ceilings, and local permissions;
• security and conformance results; and
• operational owner, revocation path, and rollback target.

Re-run admission when publisher, dependency, endpoint, schema, requested permission, ownership, or executable digest changes. A protocol registry entry is useful discovery, not supply-chain assurance.

Testing matrix

Test through the Tool Gateway. A raw protocol server can be correct while its ContextOS binding is unsafe.

Release checklist

• Stable capability ids, owner, version, and kill switch exist.
• Protocol and compatibility profile are pinned; legacy behavior is isolated.
• Discovery and admission are separate.
• Every capability has a class, native ActionRisk, and conservative v1 approval mode.
• Inputs, outputs, errors, evidence, postconditions, and partial effects are typed.
• Write-class calls persist operation identity before dispatch and enforce the declared provider-specific retry/reconciliation contract; key presence alone is not a guarantee.
• Required execution boundary, credential mediation, actual data/processor route and aggregate reservation are verified before protected work.
• Exact stored approvals and current ancestor authority are rechecked on input, retry, resume and delegation; cancellation preserves in-flight uncertainty.
• Identity, tenant, scope, destination, amount, data, and time ceilings are explicit.
• Input-required and task flows preserve authorization, budget, trace, and idempotency state.
• Deprecated MCP features are absent from new adapters.
• Supply-chain artifacts and provenance are pinned.
• Conformance, security, replay, and evaluation suites pass.
• Rollout, rollback/compensation, cancellation, and revocation have been rehearsed.

Common mistakes

Next steps

• Model Context Protocol profile
• Adapter Mesh
• Governance
• API Contracts
• Security and Compliance