Context

Implement Model Context Protocol (MCP) integration as defined in spec 5.2 and 11.1. MCP enables agents to discover and use external tools provided by MCP-compatible servers, greatly extending the tool ecosystem available to agents.

Acceptance Criteria

• MCP client implementation (protocol-compliant)
• Tool discovery from MCP servers (list available tools with schemas)
• Tool invocation via MCP protocol (request/response handling)
• MCP-discovered tools appear in agent available tools list
• Permission system applies to MCP tools (same trust levels as native tools)
• At least 1 MCP server integration tested end-to-end
• Error handling for MCP connection failures, timeouts, and malformed responses
• MCP server configuration via YAML (server URL, auth, enabled tools)
• Tool result caching for idempotent MCP tool calls
• Unit tests for MCP client, tool discovery, and invocation

Dependencies

• End-to-end integration test: single agent receives and completes a task #24 — Tool execution framework

Design Spec Reference

• Spec 5.2, Spec 11.1, Spec 15.2

Design Decisions Finalized

• D17 — MCP SDK: Official mcp Python SDK, pinned >=1.25,<2. Thin MCPBridgeTool adapter layer isolates codebase from SDK API changes. Support stdio + Streamable HTTP transports. Skip deprecated SSE.
• D18 — MCP Result Mapping: Adapter in MCPBridgeTool keeps ToolResult as-is. Text → concatenate, images/audio → placeholder + metadata["attachments"], structuredContent → metadata["structured_content"], isError → is_error. Future: optional attachments on ToolResult.

Common pattern: All strategies use pluggable protocol interfaces with one initial implementation. Alternative strategies are documented in DESIGN_SPEC.md for future.