Mastra/mcp

Implements the Model Context Protocol (MCP) client specification with support for stdio, SSE, and WebSocket transports. The client handles bidirectional JSON-RPC 2.0 message framing, automatic reconnection with exponential backoff, and capability negotiation during the initialization handshake. Built on top of Mastra's core message routing system, it abstracts transport layer complexity while maintaining full protocol compliance for tool discovery, resource access, and prompt management.

Translates MCP tool schemas (JSON Schema format) into Mastra's internal tool representation, enabling unified execution regardless of whether tools come from MCP servers, native Mastra tools, or external APIs. The system performs runtime schema validation using Zod, converts parameter types between protocol representations, and maps execution results back to the agent's expected output format. This abstraction layer allows agents to treat all tool sources identically while maintaining type safety and error handling consistency.

Enables agents to invoke multiple MCP tools in parallel or sequence, with automatic result aggregation and error handling. The system batches tool calls to the same MCP server to reduce round-trips, implements parallel execution for tools on different servers, and provides result aggregation strategies (collect all, fail-fast, partial success). Batch execution is transparent to agents — they specify tool calls and the system optimizes execution automatically.

Caches results from MCP tool invocations to avoid repeated execution of expensive or deterministic operations. The system implements multiple cache invalidation strategies (TTL-based, event-based, manual), allows tools to specify cache behavior (cacheable, non-cacheable, cache-with-validation), and integrates with Mastra's memory system for cross-agent cache sharing. Cache hits are tracked in observability for performance analysis.

Manages a pool of MCP server connections with automatic initialization, health checking, and graceful shutdown. Each connection maintains state including negotiated capabilities, available tools, and resource metadata. The system implements connection reuse to avoid repeated initialization handshakes, automatic reconnection on failure with exponential backoff, and cleanup of stale connections. Built on Node.js EventEmitter for lifecycle events, it integrates with Mastra's observability system to track connection health and tool availability.

Discovers available tools from MCP servers during initialization and caches tool schemas locally to avoid repeated server queries. Uses lazy loading to defer schema fetching for tools that may never be invoked, reducing startup time and memory overhead. The cache is invalidated on reconnection or when explicitly refreshed, and supports TTL-based expiration for long-running agents. Tool discovery integrates with Mastra's agent planning system to inform which tools are available for a given task.

Provides access to resources exposed by MCP servers (files, documents, API responses) through a unified interface with automatic content type detection and streaming support. The system handles resource URI resolution, implements range requests for large files, and supports both text and binary content. Streaming is implemented using Node.js readable streams, enabling agents to process large resources without loading them entirely into memory. Content type negotiation allows clients to request specific formats (e.g., markdown vs. HTML for web pages).

Discovers and executes prompt templates exposed by MCP servers, enabling agents to use server-provided prompts for specialized tasks. The system handles prompt parameter substitution, integrates with Mastra's prompt engineering tools, and caches prompt definitions. Prompts can be composed with agent system prompts or used as standalone instructions, and execution results are tracked in the observability system for prompt performance analysis.

Implements comprehensive error handling for MCP tool invocations with automatic fallback to alternative tools or execution strategies. When an MCP tool fails, the system categorizes the error (network, schema mismatch, server error, timeout) and attempts recovery based on the error type. Fallback strategies include retrying with exponential backoff, routing to alternative MCP servers that expose the same tool, or falling back to native Mastra tools. Error details are logged with full context for debugging and observability.

Manages authentication credentials for MCP servers (API keys, OAuth tokens, mTLS certificates) with secure storage and automatic refresh. The system integrates with Mastra's credential management system to store secrets in encrypted vaults, supports multiple authentication schemes (bearer tokens, basic auth, custom headers), and handles token expiration with automatic refresh. Credentials are passed to MCP servers during initialization and can be rotated without restarting connections.

Handles MCP protocol version negotiation during server initialization, ensuring client and server are compatible before attempting tool execution. The system detects which capabilities each server supports (tools, resources, prompts, sampling) and adapts agent behavior accordingly. Version compatibility is checked at initialization and periodically during execution, with graceful degradation if servers downgrade capabilities. Incompatible servers are marked as unavailable and excluded from tool routing.

Integrates MCP tool execution with Mastra's observability system, emitting structured logs, traces, and metrics for all tool invocations. Each tool call is traced with full context (tool name, parameters, result, latency, error details), and traces are correlated with agent execution traces for end-to-end visibility. Metrics include tool success rate, latency percentiles, and error distribution, enabling teams to monitor MCP tool health and performance. Integration with OpenTelemetry allows exporting traces to external observability platforms.