# ADR-029: Model Context Protocol (MCP) Adoption

**Status:** Proposed  
**Date:** 2026-02-17  
**Supersedes:** None  
**Author(s):** CleverAgents Team  
**Approver(s):**

## 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

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.

## Related ADRs

| ADR | Title | Relationship |
|-----|-------|-------------|
| [ADR-011](ADR-011-tool-system.md) | Tool System | MCP tools are registered as Tool records and follow the four-stage tool lifecycle |
| [ADR-012](ADR-012-skill-system.md) | Skill System | MCP tools are exposed through skills for actor assignment |
| [ADR-015](ADR-015-sandbox-and-checkpoint.md) | Sandbox and Checkpoint | MCP tool execution must respect sandbox boundaries and checkpoint rules |
| [ADR-022](ADR-022-langchain-langgraph-integration.md) | LangChain/LangGraph Integration | MCP SDK is part of the LLM runtime stack; MCPToolAdapter bridges to LangGraph tool nodes |
| [ADR-028](ADR-028-agent-skills-standard.md) | Agent Skills Standard (AgentSkills.io) | Agent Skills commonly orchestrate MCP tools within multi-step workflows |
| [ADR-030](ADR-030-skill-abstraction-definition.md) | Skill Abstraction Definition | MCP tools are one of the four tool sources unified under the skill abstraction |

## Acceptance

### Votes For

| Voter | Comment |
|-------|---------|

**Total: 0**

### Votes Against

| Voter | Comment |
|-------|---------|

**Total: 0**

### Abstentions

| Voter | Comment |
|-------|---------|

**Total: 0**
