npm / @mastra/mcp
@mastra/mcp
What changed in @mastra/mcp 1 to 2, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-22.
39 breaking7 security41 new APIs and options2 performance11 behavior and defaults27 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@mastra/mcp 266 changes
Breaking changes 34
@mastra/mcp requires @mastra/core 1.79.0 or later; upgrade the core package together with @mastra/mcp and @mastra/connect.
@mastra/mcp now requires @mastra/core 1.76.0 or later.
The connectSSE API has been removed.
Tools that need caller input suspend with a payload and return; after the caller replies, the tool runs again with
context.resumeDataandcontext.suspendPayload.Elicitation actions have been removed.
The method throws on a 2.0 server; caller-input workflows should use the suspend-and-resume flow instead.
The eventSourceInit setting has been removed.
The method throws on a 2.0 server.
The method throws on a 2.0 server.
The getServer API has been removed.
The handleServerlessRequest API has been removed.
The Hono dependency and peer ranges were raised to address a security advisory.
MCPClient server definitions accept a per-server inputRequests handler in place of
mcp.elicitation.onRequest().Log levels are now requested per request through this metadata key.
The logging/setLevel API has been removed.
This release requires @mastra/core 1.68 or newer.
MastraApiMCPServer was removed while its tool design is reconsidered.
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.
Requires exactly one of
clientInformationorclientMetadataUrland no longer registers dynamically.The OAuthClientRegistrationError API has been removed.
The server protocolVersion option has been removed.
The reconnectionOptions setting has been removed.
The registerClient API has been removed.
The resources/subscribe API has been removed.
The signature remains, but subscriptions now ride one
subscriptions/listenstream per server.The signature remains, but subscriptions now ride one
subscriptions/listenstream per server.The roots API has been removed.
The sampling API has been removed.
The sendLoggingMessage API has been removed.
Returns a suspended or completed status object, and invalid input is answered with an error instead of a completed result.
The sessionId API has been removed.
The sessionIds API has been removed.
The startHonoSSE API has been removed.
The startSSE API has been removed.
Security 2
MCPClient can register a webhook URL and route requests to mcp.events.handleWebhook(); subscriptions prefer webhook delivery, verify signatures, and refresh before expiry.
Tool schemas are advertised and validated as JSON Schema 2020-12; untrusted schemas are bounded to 128 levels and 10,000 nodes.
New APIs and options 15
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.
MCPServer exposes declared event descriptors to Studio, including whether each event type can be emitted.
MCPServer provides a Studio inspector that polls and streams events through the same code path as protocol requests and can send test events.
Clients can list and subscribe to events advertised by MCP servers, with push or poll delivery, cursor resumption, duplicate suppression, and reconnect handling.
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.
MCPServer can declare and emit experimental MCP Events; clients can poll or stream occurrences, with optional argument matching and authorization.
Set
traceContexton the server configuration to send custom trace context or none.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.
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.
MCPServer announces title, description, websiteUrl, and icons to MCP clients alongside name and version, enabling clients to display richer server identity.
MCPServer publishes tool titles, and tools returned by MCPClient retain the server title or fall back to annotations.title.
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.
The client probes servers with
server/discoverand falls back to the legacy handshake unlessprotocolVersionpins'2026-07-28'or'legacy';getServerProtocolVersions()reports the outcome.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.
Server definitions accept a traceContext provider, and received W3C trace fields are exposed to tools through requestContext.
Behavior and default changes 6
With
onToolError: 'return', failed calls resolve with the full CallToolResult instead of only structuredContent, so callers can inspect isError and content.With the default
onToolError: 'throw', thrown MastraError instances include the structured reason as a JSON string in details.structuredContent.MCP tools declaring an outputSchema now pass embedded resource block text to the model along with text blocks; structuredContent remains excluded.
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.
MCP continuation keys are now generated with Web Crypto.
MCPClient now accepts tools from other MCP servers that describe their inputs with JSON Schema draft 2019-09.
Fixes and other changes 9
The handler now registers and fires for MCP servers on older protocol revisions, and reconnecting no longer logs a subscriptions/listen failure.
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.
The handler now registers and fires for MCP servers on older protocol revisions, and reconnecting no longer logs a subscriptions/listen failure.
@mastra/mcp declares zod as a peer dependency, at the minimum version already required by @modelcontextprotocol/ext-apps.
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.
Disconnecting a replaced MCPClient no longer prevents reuse of the replacing client when both share an id.
Resource read results now include the optional mimeType and _meta fields, preserving content type and metadata such as MCP App UI settings.
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.
MCP tool calls no longer fail with a schema validation error when tools are defined with zod v3 schemas.
@mastra/mcp 161 changes
Breaking changes 5
MCP now requires @mastra/core 1.64 or newer to use its tool output validation API.
Custom jsonSchemaValidator implementations must now be imported from the MCP client validators path instead of the SDK validation path.
Resource subscriptions are tracked per session; updates only reach sessions subscribed to the URI, so clients must subscribe before receiving resource update notifications.
Per server, onToolError: 'return' opts into resolving with the raw result instead of throwing; the default is 'throw'.
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.
Security 5
Prompts no longer leak across authenticated callers.
Notification text now escapes backslashes, and osascript runs without a shell so notification text can't inject commands.
MCP serverless 500 responses no longer echo internal error messages to clients; details are still logged server-side.
Clean versions were published to supersede compromised versions that declared the malicious easy-day-js dependency, and the latest dist-tag was moved forward.
Opt in to forwarding instructions advertised by an MCP server into the system prompts of agents that use its tools; defaults to false.
New APIs and options 26
Read the existing hidden MCP content channel through an exported helper.
Read result-level _meta from returned structured MCP tool results; metadata is now preserved for consumers such as MCP Apps hosts.
Servers can optionally advertise ttlMs and cacheScope on cacheable results such as tools/list.
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.
MCP discovery methods accept per-server time budgets and return duration metrics.
MCPServer and the MCP client can opt into protocol revision 2026-07-28; omitting the flag keeps existing behavior unchanged.
Custom middleware can use this server.mcpOptions hook to build request auth info when it verifies the caller.
HTTP server configs can restrict which hosts the client's requests may target, including during initial connection, SSE fallback, and OAuth discovery.
Setting inheritDefaultEnv to false prevents stdio subprocesses from inheriting SDK default environment variables; only entries listed in env are passed.
Exports the MCP tool catalog as JSON-serializable definitions grouped by server and keyed by tool name, allowing it to be cached and reused.
Reports per-server failures alongside tool definitions so partial catalogs are not cached silently.
Rebuilds a single executable tool from a cached definition; hydrated tools connect lazily on first execution.
Rebuilds a namespaced tool map from definitions, matching the serverName_toolName keys from listTools().
Adds an end-to-end interactive OAuth authorization-code flow for HTTP MCP servers, including token exchange and reconnection.
Exports the local loopback OAuth callback server for hosts that need custom redirect handling.
Exposes the server authentication state, including
needs-authwhen an HTTP MCP server rejects a connection with an authorization error.Adds a way for a tool to send a log notification to the client that called it.
Adds a way for tools to report progress to the calling client.
Adds a client callback for reacting to server tool-list changes.
Adds server-side log notifications that can be broadcast to connected clients; each session's minimum level set through logging/setLevel is honored.
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.
Adds runtime tool management and list-change notification methods; when registered with Mastra, dynamic additions and removals also synchronize the Mastra tool registry.
Adds a method that returns namespaced tools alongside per-server discovery errors, allowing applications to use discovered tools and inspect failures.
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.
Inspect cached server instructions without forwarding them to agent prompts.
Set the maximum number of characters forwarded per server.
Performance 2
CHANGELOG.md is no longer included in distributed npm files, reducing package size.
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.
Behavior and default changes 5
MCP tools over HTTP now receive the authenticated user in extra.authInfo when server.auth is configured, on streamable HTTP and SSE transports.
Resource updates and resource/prompt list changes now reach clients connected over streamable HTTP, with notifications broadcast to every connected session across all transports.
MCP no longer relies on core-bundled Hono context types at package boundaries; request types support standard Request objects and Hono-compatible request shapes.
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.
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.
Fixes and other changes 18
MCP tools rebuilt from cached catalogs and live-discovered tools now validate structured results against their output schema before sending them to the model.
Aggregate MCP discovery errors preserve structured HTTP status and transport codes while retaining legacy string errors.
Fixed tool listing when a tool has no input schema.
Declared the MCP SDK v1 peer required by @modelcontextprotocol/ext-apps as a direct dependency, preventing import failures when automatic peer installation is skipped.
In-band tool errors containing transport-like words are no longer mistaken for transport failures that trigger reconnects and retries, preventing duplicate calls.
Tool schemas advertised over MCP no longer declare a draft-07 $schema dialect, avoiding rejection by the MCP 2.0 default validator.
After a transport-level reconnect fails, callers receive the actual reconnection error rather than the stale error that triggered recovery.
Corrects fallback handling for non-OK Streamable HTTP responses so servers that only support HTTP+SSE can be reached.
MCP tools with outputSchema send LLM-facing content text to the model through toModelOutput while retaining structuredContent in tool.execute() results.
Concurrent MCP tool calls no longer fail while the client reconnects after a dropped connection.
listTools(),callTool(), andforceReconnect()work again after a failed reconnect once the server is reachable.Fixes MCP clients advertising elicitation support before a handler is registered.
Preserves a resource's _meta in resources/read results, allowing clients to receive metadata such as UI CSP settings.
MCP tools that declare outputSchema now expose it on the Mastra tool wrapper, allowing Studio and other consumers to document expected outputs.
MCPClient can now be safely imported on workerd without causing Cloudflare Workers to fail during module initialization.
FGA-enabled MCP servers can map OAuth authInfo to a Mastra user before tools/list and tools/call authorization.
The stale MCP transport is closed before reconnecting, preventing orphaned EventSource instances and accumulated server-side sessions on implicit reconnect.
MCP tools wrapping a server-level requireToolApproval function now preserve and honor the per-tool approval function when converted by the agent.