Build an Adapter

Adapters are the Action-plane boundary between a model-driven plan and the outside world. They are not “API wrappers.” They are typed, versioned execution contracts that ContextOS brokers through the Tool Gateway.

Your adapter declares what the outside system can do. ContextOS decides whether a specific run may do it, on whose behalf, under which policy, with which evidence, and how the result is recorded.

The production rule

A production adapter must be able to answer five questions without reading a prompt:

If any answer is “the model knows” or “the prompt says,” the adapter is not ready.

Choose the adapter path

Pick the smallest surface that fits the system. Do not wrap a whole API when the workflow needs three capabilities.

This page focuses on MCP because MCP is the richest adapter path. The same ContextOS contract applies to OpenAPI, function, and custom connectors.

MCP 2025-11-25 baseline

ContextOS adapter builds should target MCP 2025-11-25 unless a deployment has a specific compatibility reason to pin an older version.

Spec references: MCP base protocol, tools, resources, prompts, transports, authorization, sampling, elicitation, tasks, security best practices, and Agent Skills.

Architecture in ContextOS

Planner step
  -> Critic.verify
  -> Tool Gateway
  -> Adapter contract
  -> MCP server / OpenAPI service / function / connector
  -> normalized ToolResultEnvelope
  -> Critic.score
  -> DecisionRecord

The model never calls an adapter directly. It proposes a step. The Tool Gateway:

1. Resolves the capability from the compiled tool manifest.
2. Validates arguments against the adapter schema.
3. Re-evaluates policy at execute time.
4. Applies approval-mode routing.
5. Brokers user and agent identity.
6. Enforces idempotency, timeout, rate, and egress rules.
7. Invokes the adapter.
8. Normalizes results, errors, evidence, metrics, and trace metadata.

Build sequence

Follow this order. Reversing it usually produces broad tools that are hard to govern.

Adapter manifest

The manifest is the artifact ContextOS reviews and pins. MCP discovery is useful, but it is not enough for production because MCP does not know your enterprise risk taxonomy by itself.

{
  "adapter_id": "adp_payments_mcp",
  "name": "Payments MCP Adapter",
  "owner_role": "payments_platform",
  "protocol": "mcp",
  "protocol_version": "2025-11-25",
  "transport": {
    "kind": "streamable_http",
    "endpoint_ref": "https://payments.example.com/mcp",
    "origin_allowlist": ["https://contextos.example.com"]
  },
  "server_capabilities": {
    "tools": { "listChanged": true },
    "resources": { "subscribe": false, "listChanged": true },
    "prompts": { "listChanged": false },
    "tasks": { "list": true, "cancel": true }
  },
  "auth": {
    "type": "oauth2",
    "resource": "https://payments.example.com/mcp",
    "initial_scopes": ["payments.read"],
    "step_up_scopes": {
      "payments.issue_refund": ["payments.refund.write"]
    },
    "token_audience": "payments-mcp",
    "allow_token_passthrough": false
  },
  "capabilities": [
    {
      "capability_id": "payments.lookup_transaction",
      "mcp_tool_name": "payments_lookup_transaction",
      "capability_class": "observe",
      "approval_mode": "read_only",
      "decision_bindings": ["support.refund.eligibility"],
      "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",
      "mcp_tool_name": "payments_issue_refund",
      "capability_class": "act",
      "approval_mode": "destructive",
      "decision_bindings": ["support.refund.execute"],
      "requires_approval_gate": "GATE_FINANCE_APPROVAL",
      "idempotency": {
        "required": true,
        "dedup_window_seconds": 86400
      },
      "arg_constraints": {
        "amount_inr": { "min": 1, "max": 50000 },
        "currency": { "enum": ["INR"] }
      },
      "evidence_keys": ["refund_id", "transaction_id", "reversal_token"]
    }
  ],
  "observability": {
    "trace_context": "w3c",
    "span_name_prefix": "contextos.adapter.payments",
    "metrics": ["latency_ms", "retry_count", "upstream_status", "cost_cents"]
  }
}

MCP server surface

Design MCP features with different trust semantics. Do not treat every MCP object as a tool.

Tool design rules

MCP tools are model-invocable. That makes their names, descriptions, schemas, and error behavior part of the safety boundary.

MCP’s default schema dialect is JSON Schema 2020-12 when $schema is absent. ContextOS adapters should use 2020-12 unless a dependency forces another dialect.

Example tool contract

MCP tool definition:

{
  "name": "payments_issue_refund",
  "title": "Issue Refund",
  "description": "Issue a refund against an existing settled transaction.",
  "inputSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "transaction_id": { "type": "string", "pattern": "^txn_[a-z0-9]+$" },
      "amount_inr": { "type": "number", "minimum": 1, "maximum": 50000 },
      "currency": { "type": "string", "enum": ["INR"] },
      "reason_code": { "type": "string", "enum": ["duplicate", "customer_request", "service_failure"] },
      "idempotency_key": { "type": "string", "pattern": "^ik_[a-z0-9]{16}$" }
    },
    "required": ["transaction_id", "amount_inr", "currency", "reason_code", "idempotency_key"]
  },
  "outputSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "refund_id": { "type": "string" },
      "status": { "type": "string", "enum": ["accepted", "queued", "rejected"] },
      "transaction_id": { "type": "string" },
      "reversal_token": { "type": "string" },
      "evidence_refs": {
        "type": "array",
        "items": { "type": "string" }
      }
    },
    "required": ["refund_id", "status", "transaction_id", "evidence_refs"]
  },
  "icons": [
    {
      "src": "https://payments.example.com/icons/refund.png",
      "mimeType": "image/png",
      "sizes": ["48x48"]
    }
  ]
}

ContextOS capability binding:

{
  "capability_id": "payments.issue_refund",
  "adapter_id": "adp_payments_mcp",
  "protocol_tool": "payments_issue_refund",
  "capability_class": "act",
  "approval_mode": "destructive",
  "decision_binding": "support.refund.execute",
  "requires_approval_gate": "GATE_FINANCE_APPROVAL",
  "policy_refs": ["POLICY_RETURNS_V4"],
  "evidence_keys": ["refund_id", "transaction_id", "reversal_token"],
  "retry_policy": {
    "max_attempts": 1,
    "retryable_error_codes": ["UPSTREAM_TIMEOUT"],
    "requires_same_idempotency_key": true
  }
}

Error model

Use the right failure channel:

Keep protocol errors rare. A model can often correct a tool execution error; it usually cannot correct a protocol violation.

Resources and evidence

Resources are not just “files the model can read.” In ContextOS, resources often become evidence.

For parameterized resources, use MCP resource templates, but constrain parameters in the ContextOS manifest. A template like file:///{path} is not a permission model by itself.

Prompts, Skills, and plugins

MCP prompts, Agent Skills, and plugins solve different layers of the adapter problem.

Use Skills for repeatable micro-workflows such as identity verification, address validation, evidence extraction, or PR review. Register the Skill beside the Context Pack and evaluate it independently.

skill_id: skill.support.refund_evidence
version: "1.0.0"
purpose: "Collect the minimum evidence needed for a refund execution decision."
required_capabilities:
  - orders.lookup
  - payments.lookup_transaction
preconditions:
  - "run_context.intent == support.refund"
postconditions:
  - "evidence_refs includes order_lookup"
  - "evidence_refs includes transaction_lookup"
prompt_fragment_ref: "prompt://skills/support/refund_evidence.v1"
evaluation_set_ref: "goldenset://skills/support/refund_evidence.v1"

Transport guidance

For Streamable HTTP, validate Origin, bind local servers to localhost during development, authenticate production requests, and treat resumable SSE streams as state that must be bound to user identity.

Authorization and scope model

MCP HTTP auth is powerful enough for enterprise use, but it is easy to over-scope. ContextOS requires least privilege.

For a ContextOS adapter, scopes are not sufficient authorization. The Gateway still evaluates tenant, user delegation, agent workload identity, policy, approval gate, and capability constraints.

Elicitation

Use elicitation when the server needs information from the user/client before proceeding. Do not fake it with a tool error that asks the model to ask the user later.

URL mode must not become a credential leak. The server should generate the URL, bind state to the user/session, complete the OAuth flow directly with the third-party service, and store downstream tokens server-side.

Sampling

Sampling lets an MCP server ask the client to run a model. That can be useful for adapters that need classification, summarization, or transformation. It is also a way to accidentally hide model calls from the main harness.

ContextOS rule: sampling is allowed only when it is declared, budgeted, traced, and evaluated.

If a server needs complex autonomous behavior, prefer modeling it as a Skill or sub-plan under the ContextOS Orchestrator rather than hiding an agent loop inside an adapter.

Tasks and long-running tools

Use MCP tasks for durable, pollable work: report generation, large exports, background scans, or workflows waiting on external input.

All task-related messages should carry task metadata and trace correlation so replay can connect the eventual result to the original decision.

Security checklist

This is the minimum bar before production.

Testing matrix

Release checklist

• Protocol version pinned to 2025-11-25 or a documented older version.
• Transport declared and tested (stdio, Streamable HTTP, or custom).
• Server capabilities discovered and pinned in the adapter manifest.
• Tool names are specific, stable, and non-generic.
• Input schemas are valid JSON Schema objects; no write-class tool accepts arbitrary payloads.
• Output schemas exist for structured results that affect decisions.
• Every capability has capability_class and maximum approval_mode.
• Every write-class capability requires idempotency and has adapter-side dedup.
• Auth uses least privilege, proper token audience, resource indicators, and no token passthrough.
• Streamable HTTP origin validation, timeouts, and session binding are implemented.
• Resources carry MIME type, classification, source/freshness, and evidence identity.
• Prompts and Skills are versioned, reviewed, and evaluated.
• Elicitation and sampling are explicitly declared; users can decline where appropriate.
• Tool errors are structured and mapped to retry/replan/escalate behavior.
• OTEL trace propagation and ToolCallEnvelope / ToolResultEnvelope capture work end-to-end.
• Golden tests, replay tests, and release gates pass.

Common mistakes

Next steps

• Model Context Protocol (MCP)
• Tool Manager component
• Adapter Mesh
• Governance - Approval-mode tiers
• API Contracts - ToolCallEnvelope / ToolResultEnvelope
• Decision Record