# What changed in @mastra/mcp

> 127 changes in @mastra/mcp 1 to 2 from its official release notes, upgrade guides and advisories: 39 breaking, 7 security, 41 new APIs and options. Each one cited. Sources checked 2026-10-22. HTML: https://unstale.sh/npm/@mastra/mcp/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## @mastra/mcp 2

### Breaking changes

- @mastra/mcp requires @mastra/core 1.79.0 or later; upgrade the core package together with @mastra/mcp and @mastra/connect. (2.5.0) — [release notes](https://github.com/mastra-ai/mastra/blob/4c22623ea342a0ce611e15f89f4ab8b377bf7ee8/packages/mcp/CHANGELOG.md#250)
- @mastra/mcp now requires @mastra/core 1.76.0 or later. (2.2.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#240), [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#220)
- The connectSSE API has been removed. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- Tools that need caller input suspend with a payload and return; after the caller replies, the tool runs again with `context.resumeData` and `context.suspendPayload`. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- Elicitation actions have been removed. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The method throws on a 2.0 server; caller-input workflows should use the suspend-and-resume flow instead. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The eventSourceInit setting has been removed. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The method throws on a 2.0 server. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The method throws on a 2.0 server. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The getServer API has been removed. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The handleServerlessRequest API has been removed. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The Hono dependency and peer ranges were raised to address a security advisory. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- MCPClient server definitions accept a per-server inputRequests handler in place of `mcp.elicitation.onRequest()`. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- Log levels are now requested per request through this metadata key. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The logging/setLevel API has been removed. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- This release requires @mastra/core 1.68 or newer. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- MastraApiMCPServer was removed while its tool design is reconsidered. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- Servers now serve only the MCP 2026-07-28 revision. Requests are self-contained, with no initialize handshake, session header, ping, or standalone HTTP+SSE transport; Streamable HTTP responses still stream as Server-Sent Events. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- Requires exactly one of `clientInformation` or `clientMetadataUrl` and no longer registers dynamically. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The OAuthClientRegistrationError API has been removed. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The server protocolVersion option has been removed. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The reconnectionOptions setting has been removed. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The registerClient API has been removed. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The resources/subscribe API has been removed. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The signature remains, but subscriptions now ride one `subscriptions/listen` stream per server. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The signature remains, but subscriptions now ride one `subscriptions/listen` stream per server. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The roots API has been removed. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The sampling API has been removed. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The sendLoggingMessage API has been removed. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- Returns a suspended or completed status object, and invalid input is answered with an error instead of a completed result. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The sessionId API has been removed. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The sessionIds API has been removed. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The startHonoSSE API has been removed. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The startSSE API has been removed. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)

### Security

- MCPClient can register a webhook URL and route requests to mcp.events.handleWebhook(); subscriptions prefer webhook delivery, verify signatures, and refresh before expiry. (2.5.0) — [release notes](https://github.com/mastra-ai/mastra/blob/4c22623ea342a0ce611e15f89f4ab8b377bf7ee8/packages/mcp/CHANGELOG.md#250)
- Tool schemas are advertised and validated as JSON Schema 2020-12; untrusted schemas are bounded to 128 levels and 10,000 nodes. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)

### New APIs and options

- Servers can enable experimental webhook delivery for emitted event types; callers must authenticate, and callback URLs must be public HTTPS URLs that pass a verification challenge. (2.5.0) — [release notes](https://github.com/mastra-ai/mastra/blob/4c22623ea342a0ce611e15f89f4ab8b377bf7ee8/packages/mcp/CHANGELOG.md#250)
- MCPServer exposes declared event descriptors to Studio, including whether each event type can be emitted. (2.5.0) — [release notes](https://github.com/mastra-ai/mastra/blob/4c22623ea342a0ce611e15f89f4ab8b377bf7ee8/packages/mcp/CHANGELOG.md#250)
- MCPServer provides a Studio inspector that polls and streams events through the same code path as protocol requests and can send test events. (2.5.0) — [release notes](https://github.com/mastra-ai/mastra/blob/4c22623ea342a0ce611e15f89f4ab8b377bf7ee8/packages/mcp/CHANGELOG.md#250)
- Clients can list and subscribe to events advertised by MCP servers, with push or poll delivery, cursor resumption, duplicate suppression, and reconnect handling. (2.5.0) — [release notes](https://github.com/mastra-ai/mastra/blob/4c22623ea342a0ce611e15f89f4ab8b377bf7ee8/packages/mcp/CHANGELOG.md#250)
- The experimental provider delivers MCP server events to agent threads as untrusted notifications, sharing subscriptions across threads and supporting pluggable cursor storage and optional event-management tools. (2.5.0) — [release notes](https://github.com/mastra-ai/mastra/blob/4c22623ea342a0ce611e15f89f4ab8b377bf7ee8/packages/mcp/CHANGELOG.md#250)
- MCPServer can declare and emit experimental MCP Events; clients can poll or stream occurrences, with optional argument matching and authorization. (2.5.0) — [release notes](https://github.com/mastra-ai/mastra/blob/4c22623ea342a0ce611e15f89f4ab8b377bf7ee8/packages/mcp/CHANGELOG.md#250)
- Set `traceContext` on the server configuration to send custom trace context or none. (2.4.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#240)
- Set the client name and version MCP servers receive on connect and with each request, globally or per server, instead of the server key and 1.0.0. (2.3.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#230)
- Returns the identity announced by each connected MCP server, including its name and version and optional display metadata; entries are undefined before connection or when no identity was announced. (2.2.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#220)
- MCPServer announces title, description, websiteUrl, and icons to MCP clients alongside name and version, enabling clients to display richer server identity. (2.2.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#220)
- MCPServer publishes tool titles, and tools returned by MCPClient retain the server title or fall back to annotations.title. (2.1.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#210)
- Adds a root span for each request handled by MCPServer and for executeTool(); served requests are traced when the server is registered on a Mastra instance with observability configured. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- The client probes servers with `server/discover` and falls back to the legacy handshake unless `protocolVersion` pins `'2026-07-28'` or `'legacy'`; `getServerProtocolVersions()` reports the outcome. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- Configure a shared key to sign continuation state so resumed rounds can be answered by any process; without it, rounds can only resume on the process that started them. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)
- Server definitions accept a traceContext provider, and received W3C trace fields are exposed to tools through requestContext. (2.0.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#200)

### Behavior and default changes

- With `onToolError: 'return'`, failed calls resolve with the full CallToolResult instead of only structuredContent, so callers can inspect isError and content. (2.5.0) — [release notes](https://github.com/mastra-ai/mastra/blob/4c22623ea342a0ce611e15f89f4ab8b377bf7ee8/packages/mcp/CHANGELOG.md#250)
- With the default `onToolError: 'throw'`, thrown MastraError instances include the structured reason as a JSON string in details.structuredContent. (2.5.0) — [release notes](https://github.com/mastra-ai/mastra/blob/4c22623ea342a0ce611e15f89f4ab8b377bf7ee8/packages/mcp/CHANGELOG.md#250)
- MCP tools declaring an outputSchema now pass embedded resource block text to the model along with text blocks; structuredContent remains excluded. (2.4.1) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#241)
- MCPClient propagates the tool call span's W3C trace context to MCPServer and links the client and server spans, making it possible to move between their traces. (2.4.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#240)
- MCP continuation keys are now generated with Web Crypto. (2.1.2) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#212)
- MCPClient now accepts tools from other MCP servers that describe their inputs with JSON Schema draft 2019-09. (2.1.1) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#211)

### Fixes and other changes

- The handler now registers and fires for MCP servers on older protocol revisions, and reconnecting no longer logs a subscriptions/listen failure. (2.5.0) — [release notes](https://github.com/mastra-ai/mastra/blob/4c22623ea342a0ce611e15f89f4ab8b377bf7ee8/packages/mcp/CHANGELOG.md#250)
- The handler now registers and fires for MCP servers on older protocol revisions, and reconnecting no longer logs a subscriptions/listen failure; resource subscriptions still require revision 2026-07-28. (2.5.0) — [release notes](https://github.com/mastra-ai/mastra/blob/4c22623ea342a0ce611e15f89f4ab8b377bf7ee8/packages/mcp/CHANGELOG.md#250)
- The handler now registers and fires for MCP servers on older protocol revisions, and reconnecting no longer logs a subscriptions/listen failure. (2.5.0) — [release notes](https://github.com/mastra-ai/mastra/blob/4c22623ea342a0ce611e15f89f4ab8b377bf7ee8/packages/mcp/CHANGELOG.md#250)
- @mastra/mcp declares zod as a peer dependency, at the minimum version already required by @modelcontextprotocol/ext-apps. (2.5.0) — [release notes](https://github.com/mastra-ai/mastra/blob/4c22623ea342a0ce611e15f89f4ab8b377bf7ee8/packages/mcp/CHANGELOG.md#250)
- Malformed or oversized tool input schemas are skipped with a warning so other tools remain usable; toolsFromDefinitions skips cached definitions, while toolFromDefinition throws MCP_CLIENT_INVALID_TOOL_INPUT_SCHEMA. (2.4.1) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#241)
- Disconnecting a replaced MCPClient no longer prevents reuse of the replacing client when both share an id. (2.3.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#230)
- Resource read results now include the optional mimeType and _meta fields, preserving content type and metadata such as MCP App UI settings. (2.2.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#220)
- Successful tool call results now include the tool's UI resource link under nested and legacy flat keys, so hosts can open MCP Apps from call results; flat-key-only tools also advertise the MCP Apps extension. (2.2.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#220)
- MCP tool calls no longer fail with a schema validation error when tools are defined with zod v3 schemas. (2.1.1) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#211)

## @mastra/mcp 1

### Breaking changes

- MCP now requires @mastra/core 1.64 or newer to use its tool output validation API. (1.17.3) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1173)
- Custom jsonSchemaValidator implementations must now be imported from the MCP client validators path instead of the SDK validation path. (1.16.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1160)
- Resource subscriptions are tracked per session; updates only reach sessions subscribed to the URI, so clients must subscribe before receiving resource update notifications. (1.14.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1140)
- Per server, onToolError: 'return' opts into resolving with the raw result instead of throwing; the default is 'throw'. (1.13.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1130)
- MCP tool results with isError: true now follow the failed-tool-call path and throw the server's error text, so failures are reflected in traces, stream chunks, scorers, and persisted messages. (1.13.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1130)

### Security

- Prompts no longer leak across authenticated callers. (1.17.2) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1172)
- Notification text now escapes backslashes, and osascript runs without a shell so notification text can't inject commands. (1.13.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1130)
- MCP serverless 500 responses no longer echo internal error messages to clients; details are still logged server-side. (1.13.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1130)
- Clean versions were published to supersede compromised versions that declared the malicious easy-day-js dependency, and the latest dist-tag was moved forward. (1.10.1) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1101)
- Opt in to forwarding instructions advertised by an MCP server into the system prompts of agents that use its tools; defaults to false. (1.9.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#190)

### New APIs and options

- Read the existing hidden MCP content channel through an exported helper. (1.17.2) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1172)
- Read result-level _meta from returned structured MCP tool results; metadata is now preserved for consumers such as MCP Apps hosts. (1.17.2) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1172)
- Servers can optionally advertise ttlMs and cacheScope on cacheable results such as tools/list. (1.17.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1170)
- The 2026-07-28 protocol revision supports multi-round-trip elicitation; tool calls retry after clients answer, and elicitation.onRequest() handles requests on both protocol eras. (1.17.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1170)
- MCP discovery methods accept per-server time budgets and return duration metrics. (1.17.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1170)
- MCPServer and the MCP client can opt into protocol revision 2026-07-28; omitting the flag keeps existing behavior unchanged. (1.17.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1170)
- Custom middleware can use this server.mcpOptions hook to build request auth info when it verifies the caller. (1.17.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1170)
- HTTP server configs can restrict which hosts the client's requests may target, including during initial connection, SSE fallback, and OAuth discovery. (1.16.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1160)
- Setting inheritDefaultEnv to false prevents stdio subprocesses from inheriting SDK default environment variables; only entries listed in env are passed. (1.16.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1160)
- Exports the MCP tool catalog as JSON-serializable definitions grouped by server and keyed by tool name, allowing it to be cached and reused. (1.16.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1160)
- Reports per-server failures alongside tool definitions so partial catalogs are not cached silently. (1.16.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1160)
- Rebuilds a single executable tool from a cached definition; hydrated tools connect lazily on first execution. (1.16.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1160)
- Rebuilds a namespaced tool map from definitions, matching the serverName_toolName keys from listTools(). (1.16.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1160)
- Adds an end-to-end interactive OAuth authorization-code flow for HTTP MCP servers, including token exchange and reconnection. (1.15.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1150)
- Exports the local loopback OAuth callback server for hosts that need custom redirect handling. (1.15.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1150)
- Exposes the server authentication state, including `needs-auth` when an HTTP MCP server rejects a connection with an authorization error. (1.15.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1150)
- Adds a way for a tool to send a log notification to the client that called it. (1.14.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1140)
- Adds a way for tools to report progress to the calling client. (1.14.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1140)
- Adds a client callback for reacting to server tool-list changes. (1.14.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1140)
- Adds server-side log notifications that can be broadcast to connected clients; each session's minimum level set through logging/setLevel is honored. (1.14.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1140)
- Adds request-scoped SSE streaming in serverless mode so progress notifications reach the MCP client before the final result; the default JSON-response behavior is unchanged. (1.14.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1140)
- Adds runtime tool management and list-change notification methods; when registered with Mastra, dynamic additions and removals also synchronize the Mastra tool registry. (1.14.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1140)
- Adds a method that returns namespaced tools alongside per-server discovery errors, allowing applications to use discovered tools and inspect failures. (1.12.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1120)
- The new fga option customizes resource and permission mappings for tools/list and tools/call authorization checks without changing the Mastra instance-level tool mapping. (1.10.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1100)
- Inspect cached server instructions without forwarding them to agent prompts. (1.9.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#190)
- Set the maximum number of characters forwarded per server. (1.9.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#190)

### Performance

- CHANGELOG.md is no longer included in distributed npm files, reducing package size. (1.17.3) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1173)
- Discovery methods query configured servers concurrently rather than sequentially, reducing total discovery time and preventing a slow server from stalling the rest; ordering and per-server error reporting are unchanged. (1.15.1) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1151)

### Behavior and default changes

- MCP tools over HTTP now receive the authenticated user in extra.authInfo when server.auth is configured, on streamable HTTP and SSE transports. (1.17.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1170)
- Resource updates and resource/prompt list changes now reach clients connected over streamable HTTP, with notifications broadcast to every connected session across all transports. (1.14.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1140)
- MCP no longer relies on core-bundled Hono context types at package boundaries; request types support standard Request objects and Hono-compatible request shapes. (1.9.1) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#191)
- Image and audio content parts in MCP-style tool results are converted into model-native media output when building model prompts, without requiring duplicate media payloads in providerMetadata.mastra.modelOutput. (1.9.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#190)
- The global option on agent.stream and agent.generate now accepts a function as well as a boolean; the function is evaluated per tool call, and errors default to requiring approval. (1.9.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#190)

### Fixes and other changes

- MCP tools rebuilt from cached catalogs and live-discovered tools now validate structured results against their output schema before sending them to the model. (1.17.3) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1173)
- Aggregate MCP discovery errors preserve structured HTTP status and transport codes while retaining legacy string errors. (1.17.2) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1172)
- Fixed tool listing when a tool has no input schema. (1.17.1) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1171)
- Declared the MCP SDK v1 peer required by @modelcontextprotocol/ext-apps as a direct dependency, preventing import failures when automatic peer installation is skipped. (1.17.1) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1171)
- In-band tool errors containing transport-like words are no longer mistaken for transport failures that trigger reconnects and retries, preventing duplicate calls. (1.16.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1160)
- Tool schemas advertised over MCP no longer declare a draft-07 $schema dialect, avoiding rejection by the MCP 2.0 default validator. (1.16.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1160)
- After a transport-level reconnect fails, callers receive the actual reconnection error rather than the stale error that triggered recovery. (1.16.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1160)
- Corrects fallback handling for non-OK Streamable HTTP responses so servers that only support HTTP+SSE can be reached. (1.16.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1160)
- MCP tools with outputSchema send LLM-facing content text to the model through toModelOutput while retaining structuredContent in tool.execute() results. (1.16.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1160)
- Concurrent MCP tool calls no longer fail while the client reconnects after a dropped connection. (1.15.1) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1151)
- `listTools()`, `callTool()`, and `forceReconnect()` work again after a failed reconnect once the server is reachable. (1.15.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1150)
- Fixes MCP clients advertising elicitation support before a handler is registered. (1.14.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1140)
- Preserves a resource's _meta in resources/read results, allowing clients to receive metadata such as UI CSP settings. (1.14.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1140)
- MCP tools that declare outputSchema now expose it on the Mastra tool wrapper, allowing Studio and other consumers to document expected outputs. (1.13.1) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1131)
- MCPClient can now be safely imported on workerd without causing Cloudflare Workers to fail during module initialization. (1.12.1) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#1121)
- FGA-enabled MCP servers can map OAuth authInfo to a Mastra user before tools/list and tools/call authorization. (1.9.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#190)
- The stale MCP transport is closed before reconnecting, preventing orphaned EventSource instances and accumulated server-side sessions on implicit reconnect. (1.9.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#190)
- MCP tools wrapping a server-level requireToolApproval function now preserve and honor the per-tool approval function when converted by the agent. (1.9.0) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/mcp/CHANGELOG.md#190)