cleveragents-core/docs/reference/mcp_adapter.md

MCP Tool Adapter

This document covers the MCP (Model Context Protocol) adapter introduced in M2.3.mcp-runtime: connecting to external MCP servers, discovering tools, invoking them with schema validation, and registering them in the ToolRegistry.

Overview

The MCPToolAdapter bridges any MCP-compatible tool server into the CleverAgents runtime. It manages the full lifecycle:

Operation	Method	Description
Connect	connect(timeout?)	Start the server process or HTTP session, perform handshake
Disconnect	disconnect()	Clean shutdown of the server connection
Reconnect	reconnect(timeout?)	Disconnect and re-connect; clears cached tool list
Discover	discover_tools(filter?)	Enumerate available tools from the server
Invoke	invoke(name, args)	Call a tool with automatic input validation
Register	register_tools(registry, namespace)	Bulk-register into a ToolRegistry

Server Configuration

MCPServerConfig Fields

Field	Type	Required	Description
name	string	Yes	Server identifier
transport	string	Yes	stdio, sse, or streamable-http
command	string	stdio only	Command to spawn the server process
args	list[string]	No	Command-line arguments
env	dict	No	Environment variables for the server process
url	string	sse/http only	Server URL for remote connections
headers	dict	No	HTTP headers for remote connections

Validation Rules

• stdio transport requires command
• sse / streamable-http transport requires url

Tool Discovery

After connecting, call discover_tools() to enumerate all tools exposed by the MCP server. Each returned MCPToolDescriptor includes the tool name, description, and JSON Schema for inputs.

Filtering

Use MCPToolFilter with include or exclude lists to control which tools are exposed.

MCPToolDescriptor Fields

Field	Type	Description
name	string	Tool name as exposed by the server
description	string	Human-readable description
input_schema	dict	JSON Schema for tool inputs

Tool Invocation

Call invoke(name, arguments) to execute a discovered tool. Input arguments are validated against the tool's JSON Schema before the call is made. If validation fails, the result is returned immediately with success=False.

MCPToolResult Fields

Field	Type	Description
success	bool	Whether the invocation succeeded
data	dict	Result payload from the server
error	string or null	Error message on failure
duration_ms	float	Wall-clock execution time in milliseconds

Reconnect

Use reconnect(timeout?) to recover from a dropped connection or after a server restart. It performs a clean disconnect() followed by a fresh connect() and clears the cached tool list. Call discover_tools() again after reconnecting.

try:
    adapter.invoke("create_issue", {"title": "Bug"})
except RuntimeError:
    # Connection dropped — attempt recovery
    adapter.reconnect(timeout=10.0)
    adapter.discover_tools()

If the new connection attempt fails or times out, reconnect() raises ConnectionError.

ToolRegistry Integration

Discovered MCP tools can be bulk-registered into any ToolRegistry via register_tools(registry, namespace). Each tool is registered with the name {namespace}/{tool_name}. Re-registration after tool list changes replaces stale entries automatically.

Registered tools always carry source="mcp" and source_metadata={"server": "<server-name>"} for provenance tracking. checkpointable is always False for MCP tools — external server calls cannot be rolled back transactionally.

Capability Inference

MCP tools expose limited metadata (name, description, inputSchema). The adapter automatically infers extended ToolCapability metadata using name-based heuristics:

Tool name keywords	Inferred capability
read, get, list, search, find	read_only: true
write, create, update, delete, set	writes: true
Both read and write keywords	writes: true (write takes precedence)
Neither	read_only: false, writes: false

Inferences are applied automatically when registering tools via register_tools(). They can be overridden via the overrides block in tool or skill YAML.

Use MCPToolAdapter.infer_capabilities(tool_name) directly to check what would be inferred for a given tool name.

Error Classification

Error Type	When	Exception / Field
Connection failure	connect() with unreachable server	ConnectionError
Not connected	invoke() / discover_tools() before connect()	RuntimeError
Tool not found	invoke() with unknown tool name	result.error contains "not found"
Validation failure	invoke() with invalid input	result.error contains "validation"
Timeout	Server call exceeds deadline	result.error contains "timeout"
Server error	Server returns isError: true	result.error contains "server error"

Transport Layer

The MCPTransport base class defines the abstract interface. Concrete implementations handle stdio (child process) and HTTP (SSE / streamable-http) protocols. For testing, provide a mock transport to the adapter constructor.

Thread Safety

MCPToolAdapter uses threading.RLock internally. All public methods are safe to call from multiple threads concurrently.