Model Context Protocol (MCP)

MCP is the default protocol ContextOS uses to integrate tools and resources. MCP servers are wrapped as adapters and brokered through the Tool Gateway; the Gateway is the only path through which the Decision plane produces side effects.

Why MCP matters

• Interoperability: one adapter contract works across runtimes and agents.
• Typed contracts: tools and resources declare their schemas; argument validation happens at the Gateway boundary.
• Governed execution: capability approval_mode declarations bind to the approval-mode tier taxonomy.
• Operational safety: structured errors with retryability, idempotency keys on write-class capabilities, OTEL trace propagation.

Versioning and compatibility

Pin MCP protocol versions in adapter manifests and integration tests. Validate host and server compatibility before production rollout. Keep migration notes when moving between MCP revisions.

{
  "protocol": "mcp",
  "protocol_version": "2025-11-25",
  "transport": "streamable_http",
  "capabilities": ["tools", "resources", "prompts"]
}

ContextOS as an MCP host

ContextOS acts as an MCP host. It connects to MCP servers and exposes their capabilities as adapters in the Tool Gateway.

• MCP Server: a service that exposes tools, resources, prompts.
• MCP Host (ContextOS): the runtime that consumes those interfaces and applies the Trust plane around them.
• Adapter policy boundary: ContextOS applies the Policy Engine, approval-mode binding, idempotency, identity propagation, and audit at the Gateway — not at the MCP server.

MCP request lifecycle

1. Conversation Manager materializes the Run Context.
2. Compiler emits tool_manifest listing only permitted MCP-backed capabilities (with their declared approval_mode).
3. Planner picks a step; Critic verifies; Tool Manager constructs the ToolCallEnvelope.
4. Tool Gateway brokers credential exchange, validates args, propagates W3C trace context.
5. MCP server executes; response is normalized into a ToolResultEnvelope with citations, mutation refs, policy_decision_id, and trace metadata.

Approval-mode declaration

Every MCP capability declares the highest approval_mode it can produce. This is the binding the Tool Gateway enforces:

Policy may select a lower effective mode for a specific bounded request when the capability’s declared maximum allows it, but it cannot exceed that maximum.

Cached read-only aliases

Well-used read_only MCP tools may be exposed as cached, first-class aliases (mcp_<server>_<tool>) for prompt density. Constraints:

• alias only synthesized from cached MCP discovery (no live discovery on registry startup);
• only read_only tools eligible;
• the tool must be operator-pinned or score well from prior usage;
• execution still routes through the Tool Manager so policy, approval, tracing, and scoring stay centralized;
• alias cache invalidated on bundle promotion.

Transport and auth

• Transport: support stdio for local/dev and streamable HTTP for remote deployments.
• Auth: OAuth/OIDC or mTLS validated at the adapter boundary; the Gateway adds tenant + workload identity propagation on top.
• Least privilege: scope credentials per capability, tenant, environment.
• Correlation: every request and response carries the W3C traceparent plus baggage with run_id and decision_id.

For the current build contract, see Build an Adapter. It covers the 2025-11-25 MCP additions that matter in ContextOS: icons metadata, URL mode elicitation, tool-enabled sampling, incremental OAuth scope consent, experimental tasks, and stricter local-server security posture.

Typical MCP capabilities

• Tools: callable actions and procedures with typed arguments.
• Resources: documents, lists, datasets for retrieval workflows.
• Prompts: reusable prompt artifacts exposed by servers (subject to the Trust plane’s prompt-injection controls).
• Structured errors: machine-actionable error codes drive safe retries and fallbacks.

Example tool schema (with approval-mode)

{
  "name": "lookup_order",
  "description": "Fetch order by ID.",
  "approval_mode": "read_only",
  "input_schema": {
    "type": "object",
    "properties": { "order_id": { "type": "string" } },
    "required": ["order_id"]
  }
}

Recommended adapter practices

• Declare approval_mode on every capability (the Gateway requires it).
• Validate inputs against the schema; emit structured errors with retryability.
• Require idempotency_key on every write-class capability.
• Emit correlation IDs (traceparent) on every request and response.
• Pin MCP protocol version in deployment config.
• Keep tool permissions explicit and minimal.
• Define timeouts per capability; the Gateway enforces them at the Run Context level.

Next steps

• Build an Adapter
• Tool Manager component
• Adapter Mesh
• Context Pack contract
• Security and Compliance