Mastra MCPServer can opt into MCP 2026-07-28 and multi-round elicitation

Mastra’s core package is on npm at 1.60.0, and the framework’s MCP server can opt into the stateless 2026-07-28 Model Context Protocol revision without dropping clients that still expect a 2025-era session. The switch is explicit: pass protocolVersion: '2026-07-28' to MCPServer. Omit the field, or set '2025-11-25', and the server keeps the legacy behavior exactly.

That is the contract for teams who expose Mastra tools, agents, and workflows to external MCP clients such as Cursor, Windsurf, or Claude Desktop. MCPServer ships from @mastra/mcp for that purpose. If you only call tools inside a Mastra application, you do not need an MCP server at all.

A dual-era handler, not a second port

Default MCPServer still speaks the legacy protocol: sessionful streamable HTTP with an initialize handshake. Set the 2026 revision and HTTP plus serverless requests go through a dual-era handler.

Clients that speak 2026-07-28 are served natively—stateless, with a per-request envelope. Legacy clients hit a built-in stateless fallback on the same endpoint. startStdio() mirrors that split for subprocess transport: the opening exchange selects the era for the connection.

You do not stand up a second listener to keep old clients working. One server, two eras.

The 2026 path also changes notifications and logging. Tool list, prompt list, resource list, and resource update notifications reach 2026-07-28 clients through subscriptions/listen. Tool log messages honor the caller’s per-request logLevel opt-in rather than the session-level logging/setLevel. And cacheHints—ttlMs and cacheScope, keyed by operation such as tools/list—are advertised on cacheable results, but only when protocolVersion is '2026-07-28'.

const server = new MCPServer({
 name: 'My Server',
 version: '1.0.0',
 tools: { weatherTool },
 protocolVersion: '2026-07-28',
 cacheHints: {
 'tools/list': { ttlMs: 60_000, cacheScope: 'private' },
 },
})

Elicitation retries the whole tool

Tool elicitation via options.mcp.elicitation.sendRequest() works on both eras. On 2026-07-28 requests it uses the protocol’s multi round-trip mechanism.

The tool call first returns an input_required result. After the client answers, the call retries with the answer attached. The sendRequest() promise API is unchanged. The tool function re-executes from the top on each retry.

That is not a theoretical footnote. Any side effect above the elicitation runs again. Keep those effects idempotent, or move them until after the last sendRequest(). Keep the order of sendRequest() calls deterministic for a given input so retries attach answers to the same prompts.

If a tool writes a row, fires a webhook, or decrements a quota before it asks the client a question, turning on 2026-07-28 will replay that work. Audit those functions before you flip the flag.

Auth context and the rest of the constructor

MCPServer still takes id, name, version, and a tools map. Agents in the agents object become tools named ask_<agentIdentifier> and must carry a non-empty description or initialization throws. Workflows become run_<workflowKey>, also requiring a description; execution is workflow.createRun() followed by run.start({ inputData }). If a derived name collides with an explicit tool, the explicit tool wins, a warning is logged, and the agent or workflow is skipped.

Optional fields still cover description, instructions, repository, release date, packages, remotes, resources, prompts, and MCP Apps resources under ui:// URIs.

On the auth side, mapAuthInfoToUser maps MCP transport auth data from extra.authInfo into the user value used by Mastra FGA checks. Use it when an OAuth-protected MCP server is registered on a Mastra instance with an FGA provider. The fga config can override resource and permission mappings for this server’s tools/list and tools/call checks, so MCP authorization can be scoped differently from internal agent or workflow tool execution.

Opt in when the clients—and the tool bodies—are ready

Sessionful MCP and stateless MCP are different operational contracts. One expects a handshake and a session; the other is a per-request envelope. Mastra’s documented default is the older contract. The newer revision is available, with a dual-era HTTP fallback so legacy clients keep working, and with elicitation that matches the 2026 multi-round input_required retry.

If you publish MCP, those two behaviors—the shared endpoint and the full-tool retry—are what to test. If you do not publish MCP, you can ignore the flag.

Next step: Open the Protocol versions section of the MCPServer reference, set protocolVersion: '2026-07-28' on a development server, and call the same HTTP endpoint from a 2026-07-28 client and a legacy client. If any tool uses sendRequest(), run it twice in your head: the second pass must be safe.