Model Context Protocol (MCP)

MCP is an important interoperability protocol for the ContextOS Action plane. It is not the ContextOS authority model and it is not required by the core contract. A deployment may use MCP, A2A, OpenAPI, direct functions, or custom connectors; each path must still pass through the same policy, identity, risk, evidence, and audit boundary.

What MCP owns—and what ContextOS owns

MCP annotations, tool descriptions, icons, prompts, resources, and server identity are metadata—not permission. The Tool Gateway must not allow a discovered object to grant itself a capability, scope, destination, or approval.

The additive Execution Contract binds selected exact profiles and current observations to the admitted run. Actual network/code/memory/effect/delegation features activate the corresponding controls; protocol support does not satisfy them. A production host must enforce current authority, exact approvals, active boundaries, credential/egress/data mediation, reservations and provider-safe recovery. The repository’s synthetic reference cases are separate from runtime conformance evidence.

Version and capability negotiation

For the 2026-07-28 profile:

1. Optionally call server/discover to learn supported protocol versions, capabilities, extensions, and server identity.
2. Put io.modelcontextprotocol/protocolVersion and client capabilities in every request’s _meta; include client identity as recommended by the protocol.
3. Verify the server identity and result metadata on every response.
4. Fail visibly on UnsupportedProtocolVersionError; do not silently downgrade.
5. Cache list/read results only according to their required ttlMs and cacheScope, and invalidate on the corresponding change notification.

{
  "protocol": "mcp",
  "protocol_version": "2026-07-28",
  "transport": "streamable_http",
  "server_features": ["tools", "resources", "prompts"],
  "extensions": ["io.modelcontextprotocol/tasks"]
}

The adapter manifest pins a tested profile. It must not copy a live discovery response into production without review.

ContextOS host role

An implementation of ContextOS may act as an MCP host and run one or more MCP clients. The spec repository itself is not a host runtime.

• MCP server: exposes tools, resources, prompts, and optional extensions.
• MCP client: maintains the protocol relationship with one server.
• Host implementation: coordinates clients and applies product-level consent and security.
• ContextOS Tool Gateway: performs deterministic admission, policy, risk, credential, idempotency, evidence, and audit checks around a protocol call.

Request lifecycle

1. The Conversation Manager materializes the RunContext and the compiler emits only admitted capabilities.
2. The Planner proposes a capability; the Critic checks the compiled manifest, argument shape, and evidence requirements.
3. The Tool Gateway resolves the pinned adapter and re-evaluates identity, policy, native action risk, approval state, destination, data scope, budget, and idempotency.
4. The MCP client sends a self-contained request with its version, capabilities, identity, and W3C trace context in _meta.
5. The server returns complete or input_required; a negotiated Tasks extension may instead return resultType: "task".
6. A complete result is validated and normalized into a ToolResultEnvelope. An input request is independently authorized before the original MCP request is retried with inputResponses.
7. The run records the protocol version, server identity, capability, policy decision, evidence, artifacts, mutations, latency, and any durable task handle.

ContextOS session_id remains a run/orchestration concept. It must not be represented as an MCP protocol session in the 2026-07-28 profile.

Keep protocol request IDs distinct from stable action/operation identity. Changed business arguments or destinations need a newly bound proposal and any required approval; inputResponses cannot rewrite an approved action. Transport reissue rules never authorize blind redispatch after a possible external commit.

MCP object mapping

ActionRisk binding

ActionRisk is the native ContextOS declaration. ApprovalMode remains required in the v1 tool envelope as a conservative compatibility projection.

{
  "capability_id": "payments.issue_refund",
  "protocol_tool": "payments_issue_refund",
  "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",
  "idempotency": { "required": true }
}

Policy evaluates the vector and actual arguments immediately before execution. It also verifies that the legacy approval_mode is no less conservative than the deterministic projection of the vector. A favorable value in one dimension never cancels a denial in another.

Multi-round-trip input

MCP 2026-07-28 replaces server-initiated Roots, Sampling, and Elicitation requests with the multi-round-trip request pattern:

1. the server returns resultType: "input_required" and typed inputRequests;
2. the host decides which requests it supports and may show the user a consent or approval surface;
3. ContextOS records the request, responder identity, redactions, and authority decision; and
4. the client retries the original operation with inputResponses and a new request id.

Input requests are not trusted more than the originating tool. They cannot widen the tool’s registered authority or bypass a ContextOS approval gate.

Tasks extension

Use io.modelcontextprotocol/tasks for long-running operations that need a durable handle, polling, cancellation, or mid-flight input. The 2026 extension uses tasks/get and tasks/update; it has no tasks/list operation and no blocking tasks/result call.

Task cancellation is cooperative. A tasks/cancel acknowledgment does not prove work stopped, and a terminal remote task label does not prove an external effect was prevented or reversed. Keep controller stop acknowledgments and effect reconciliation separate, with current executor ownership on resume. The official Tasks overview describes the transport lifecycle; ContextOS adds the local authority/accounting obligations.

Every task request must be authenticated and authorized. Task identifiers need high entropy and must remain scoped to the same user, tenant, client, and resource relationship as the original operation. A task handle is a reference, not a bearer capability.

Transport, authorization, and trace

• stdio: local/private integrations; JSON-RPC only on stdout/stdin, logs on stderr, explicit install consent, sandboxing, and minimal filesystem/network access.
• Streamable HTTP: shared integrations; validate Origin, authenticate every request, use the required MCP headers, and constrain egress and redirects.
• No protocol-session assumptions: do not implement Mcp-Session-Id, the removed HTTP GET event endpoint, Last-Event-ID, or resumable redelivery in the 2026-07-28 profile. Any permitted reissue uses a new request id while retaining the original operation identity and provider key. Resolve uncertain write safety before reissue; a key alone provides no remote guarantee.
• Authorization: bind credentials to the authorization-server issuer and resource, validate issuer information, use least privilege, and never pass through a token minted for another audience.
• Trace: propagate traceparent, tracestate, and approved baggage keys through MCP _meta; keep sensitive principal details in ContextOS records rather than baggage.

Deprecated and legacy features

Roots, Sampling, and Logging remain available only during MCP’s deprecation window. New adapters should not add them:

Keep a separate 2025-11-25 compatibility adapter only when an existing server requires its initialize/session lifecycle. Label every related test, config, and trace with that profile.

Conformance checklist

• Protocol version and compatibility profile are pinned.
• server/discover or an equivalent compatibility probe is tested.
• Every request carries version and capability metadata; unsupported versions fail visibly.
• Discovery is separated from ContextOS admission.
• Each tool binding declares native ActionRisk plus the v1 ApprovalMode projection.
• Input-required retries preserve policy, consent, identity, trace, budget, and idempotency state.
• Task handles are authenticated, scoped, unguessable, and linked to the originating run.
• Cache scope and TTL are honored.
• Deprecated features are absent from new builds or isolated behind a legacy profile.
• Tool results are schema-validated and emit evidence, mutation, postcondition, and failure metadata needed by replay.

Authoritative protocol references: MCP 2026-07-28 specification, key changes, multi-round-trip requests, Streamable HTTP, authorization, and Tasks extension.

Next steps

• Build an Adapter
• Tool Manager component
• Adapter Mesh
• Governance
• Security and Compliance