MCP

MCP (Model Context Protocol) tool execution context has been reorganized, and deprecated client classes have been removed.

Changed

getMCPServers to listMCPServers

The mastra.getMCPServers() method has been renamed to mastra.listMCPServers(). This change aligns with the naming convention used across the API where plural getter methods use the list prefix.

To migrate, replace all calls to mastra.getMCPServers() with mastra.listMCPServers().

- const servers = await mastra.getMCPServers();
+ const servers = await mastra.listMCPServers();

Codemod

You can use Mastra's codemod CLI to update your code automatically:

npx @mastra/codemod@latest v1/mastra-plural-apis .

getTools to listTools

The mcp.getTools() method has been renamed to mcp.listTools(). This change aligns with the naming convention used across the API where plural getter methods use the list prefix.

To migrate, replace all calls to mcp.getTools() with mcp.listTools().

- const tools = await mcp.getTools();
+ const tools = await mcp.listTools();

Codemod

You can use Mastra's codemod CLI to update your code automatically:

npx @mastra/codemod@latest v1/mcp-get-tools .

getToolsets to listToolsets

The mcp.getToolsets() method has been renamed to mcp.listToolsets(). This change aligns with the naming convention used across the API where plural getter methods use the list prefix.

To migrate, replace all calls to mcp.getToolsets() with mcp.listToolsets().

- const toolsets = await mcp.getToolsets();
+ const toolsets = await mcp.listToolsets();

Codemod

You can use Mastra's codemod CLI to update your code automatically:

npx @mastra/codemod@latest v1/mcp-get-toolsets .

MCP tool context properties organization

Context properties in MCP tools are now organized under the context.mcp namespace. The namespace organizes MCP-specific functionality under a clear API surface.

To migrate, access MCP-specific properties like elicitation and extra through context.mcp instead of directly from the context parameter.

  createTool({
    id: 'account-balance',
-   execute: async ({ context, elicitation, extra }) => {
-     await checkAuth(extra.authInfo);
-     const result = await elicitation.sendRequest({
-       message: `Is it ok to fetch account ${context.accountId}?`,
-     });
-   },
+   execute: async (inputData, context) => {
+     await checkAuth(context?.mcp?.extra.authInfo);
+     const result = await context?.mcp?.elicitation.sendRequest({
+       message: `Is it ok to fetch account ${inputData.accountId}?`,
+     });
+   },
  });

备注

context.mcp.elicitation.sendRequest() is deprecated. It throws on servers running @mastra/mcp 2.x, which serve the MCP 2026-07-28 revision. On those servers, call context.suspend(payload) and read the caller's answer from context.resumeData when the tool runs again. See Tools that ask the caller for input suspend and resume.

Removed

Deprecated MCP client classes

The MastraMCPClient and related deprecated APIs have been removed from @mastra/mcp. This change consolidates on the new MCP client API.

To migrate, use the new MCPClient class instead of deprecated classes.

- import { MastraMCPClient, MCPConfiguration } from '@mastra/mcp/client';
+ import { MCPClient } from '@mastra/mcp/client';

- const client = new MastraMCPClient({ ... });
- const config = new MCPConfiguration({ ... });
+ const client = new MCPClient({ ... });