cleveragents-core/docs/adr/ADR-029-model-context-protocol.md

adr_number, title, status_history, tier, authors, superseded_by, related_adrs, acceptance

adr_number	title	status_history	tier	authors	superseded_by	related_adrs	acceptance
29	Model Context Protocol (MCP) Adoption	2026-02-17 Proposed Jeffrey Phillips Freeman 2026-02-17 Accepted Jeffrey Phillips Freeman	4	Jeffrey Phillips Freeman	null	number title relationship 11 Tool System MCP tools are registered as Tool records and follow the four-stage tool lifecycle number title relationship 12 Skill System MCP tools are exposed through skills for actor assignment number title relationship 15 Sandbox and Checkpoint MCP tool execution must respect sandbox boundaries and checkpoint rules number title relationship 22 LangChain/LangGraph Integration MCP SDK is part of the LLM runtime stack; MCPToolAdapter bridges to LangGraph tool nodes number title relationship 28 Agent Skills Standard (AgentSkills.io) Agent Skills commonly orchestrate MCP tools within multi-step workflows number title relationship 30 Skill Abstraction Definition MCP tools are one of the four tool sources unified under the skill abstraction	votes_for votes_against abstentions voter comment Jeffrey Phillips Freeman <Jeffrey.Freeman@CleverThis.com> MCP provides a proven standard for tool integration that aligns with the broader AI tooling ecosystem

Context

CleverAgents needs a standard way to discover and invoke external tools without building bespoke integrations for each service. The system also requires that externally hosted tools can be composed into skills and used as nodes in actor graphs while still honoring sandboxing, checkpointing, and change tracking. A vendor-neutral protocol is necessary to keep the tool ecosystem portable and extensible.

Decision Drivers

• External tools must be discoverable and invocable through a vendor-neutral protocol to keep the tool ecosystem portable and extensible
• Externally hosted tools must honor sandboxing, checkpointing, and change tracking identically to built-in tools
• Tool capability metadata (read-only vs. write) must be available for safety enforcement, even when the protocol provides limited native metadata
• MCP tools must compose into skills and participate as nodes in actor graphs using the same four-stage lifecycle as all other tools
• Tool lists may change at runtime; the system must dynamically refresh available tools without restarting

Decision

CleverAgents adopts the Model Context Protocol (MCP) as the standard for discovering and invoking external tools. MCP servers are integrated through the MCPToolAdapter, which registers MCP tools into the Tool Registry with extended capability metadata, allowing them to be composed into skills and invoked within actor graphs using the same four-stage tool lifecycle as built-in tools.

Design

Tool Discovery and Mapping

1. MCP servers are declared in tool or skill YAML configuration with transport (stdio, sse, streamable-http), command/URL, and optional environment variables.
2. During the discover phase the adapter spawns the server process (or connects to a remote endpoint), performs the MCP initialize handshake, negotiates capabilities, then calls tools/list to enumerate available tools.
3. Each MCP tool becomes a separate ToolDescriptor record with source mcp, the server's JSON Schema inputSchema, and inferred capability metadata.

Capability Inference and Override

MCP's native metadata is limited (name, description, inputSchema). CleverAgents infers extended capability metadata using heuristics:

• Tool names containing create, write, delete, update → writes: true
• Tool names containing get, list, read, search → read_only: true
• All others default to writes: true (conservative).

Inferred capabilities can be overridden in the tool or skill YAML configuration via an overrides block, ensuring safety constraints are explicit where heuristics are insufficient.

MCP Tools as Skills

• Skills reference MCP servers in their mcp_servers section.
• The Skill Registry flattens MCP-sourced tools alongside built-ins, custom tools, and Agent Skills.
• MCP tools are available to any actor assigned a skill that includes them — no special treatment required.
• Per-tool metadata overrides can be applied at the skill inclusion point.

MCP Tools in Actor Graphs

• Actor graphs use tool nodes that resolve through the actor's assigned skills.
• MCP tools appear as tool nodes identical in shape to built-in or Agent Skill tool nodes.
• The actor runtime invokes MCP tools via the MCPToolAdapter's execute() method, which translates the call into an MCP tools/call JSON-RPC request.
• Change tracking, checkpoint creation, and rollback apply identically to MCP tool nodes and built-in tool nodes.

Sandbox Path Rewriting

MCP servers operate on real filesystem paths, but CleverAgents executes plans in sandboxes. The MCPToolAdapter transparently rewrites file paths in tool arguments:

• Logical path src/main.py → sandbox path /tmp/sandbox-01HXM/worktree/src/main.py
• The MCP server operates on the sandboxed state without awareness of the sandbox model.
• On return, paths in the result are rewritten back to logical paths for the plan's change set.

Dynamic Tool Refresh

The adapter subscribes to notifications/tools/list_changed events. When an MCP server's tool list changes at runtime, the adapter re-enumerates available tools and updates the Tool Registry, ensuring skill resolution and actor graphs always reflect the current tool surface.

Server Lifecycle Management

Phase 1 — Registration:
  CLI → Registry: agents tool add / skill add
  Registry validates server command or endpoint, stores config.

Phase 2 — Actor Activation:
  Actor Runtime → Adapter: activate (for each MCP server)
  Adapter spawns process (stdio) or connects (HTTP)
  Adapter performs MCP initialize handshake, tools/list, subscribes to notifications.

Phase 3 — Execution:
  Actor Runtime → Adapter: tool call
  Adapter → MCP Server: tools/call (JSON-RPC)
  MCP Server → Adapter: result
  Adapter → Actor Runtime: result + change tracking

Phase 4 — Deactivation:
  Actor Runtime → Adapter: deactivate
  Adapter sends clean shutdown to MCP server, closes connection.

Constraints

• MCP tools must only be invoked via the MCPToolAdapter — direct JSON-RPC calls from domain code are prohibited.
• MCP tool execution must respect sandbox boundaries through argument path rewriting.
• MCP tool records must be refreshable at runtime when notifications/tools/list_changed events are received.
• Capability metadata must be either correctly inferred or explicitly overridden; the conservative default is writes: true.
• MCP server processes spawned by the adapter must be cleanly shut down during actor deactivation.

Consequences

Positive

• Standardized tool integration with a growing ecosystem of MCP servers (GitHub, Linear, AWS, databases, etc.).
• MCP tools are immediately usable in skills and actor graphs without custom glue code.
• External tooling can be swapped or upgraded without changing core domain logic.
• Sandbox path rewriting ensures MCP tools operate safely within plan boundaries.

Negative

• MCP tools expose limited capability metadata, requiring inference heuristics and manual overrides.
• External server availability and latency directly affect plan execution speed.
• The adapter adds a serialization/deserialization layer for every tool call.

Risks

• Misclassified tool capabilities (e.g., a write tool inferred as read-only) could lead to unsafe executions if not overridden.
• MCP server outages could block plan execution or degrade skill availability.
• Long-running MCP server processes could leak resources if deactivation is not handled cleanly.

Alternatives Considered

Custom tool RPC protocol — Greater control over metadata and lifecycle but increases integration burden for every new tool provider and forfeits MCP ecosystem interoperability. Rejected.

Direct SDK integrations — Simplifies single-tool integrations (e.g., GitHub SDK, AWS SDK) but scales poorly, fragments the tool ecosystem, and bypasses the uniform tool lifecycle. Rejected as a primary strategy (may be used for performance-critical built-ins).

Agent Skills only (no schema-driven tools) — Instruction-driven skills are powerful but cannot replace low-latency, deterministic schema-driven tool calls for atomic operations. MCP and Agent Skills are complementary. Rejected as a sole tool source.

Compliance

• Handshake tests: Verify MCP initialization, capability negotiation, and tool listing for both stdio and HTTP transports.
• Tool registry tests: Ensure MCP tools are registered with correct schemas, source tags, and inferred/overridden capability metadata.
• Skill exposure tests: Validate that MCP tools appear in flattened skill tool sets and can be invoked by actors.
• Sandbox rewrite tests: Confirm path rewriting for filesystem-based MCP tools in both directions (request and response).
• Notification tests: Verify tool list refresh on notifications/tools/list_changed events with correct registry updates.
• Lifecycle tests: Verify clean startup and shutdown of MCP server processes across actor activation/deactivation cycles.