mastra-ai/mastra · error · HTTPException

Server '${serverId}' cannot execute tools in this way.

Error message

Server '${serverId}' cannot execute tools in this way.

What it means

A 501 thrown when the resolved MCP server object exists but has no executeTool method, meaning the server implementation cannot run tools through this HTTP path. It protects against calling execute on a partial/stub server object (e.g. a handle that only exposes discovery or resource APIs).

Source

Thrown at packages/server/src/server/handlers/mcp.ts:234

  handler: async ({
    mastra,
    serverId,
    toolId,
    data,
    requestContext,
  }: ServerContext & { serverId: string; toolId: string; data?: unknown }) => {
    if (!mastra || typeof mastra.getMCPServerById !== 'function') {
      throw new HTTPException(500, { message: 'Mastra instance or getMCPServerById method not available' });
    }

    const server = mastra.getMCPServerById(serverId);

    if (!server) {
      throw new HTTPException(404, { message: `MCP server with ID '${serverId}' not found` });
    }

    if (typeof server.executeTool !== 'function') {
      throw new HTTPException(501, { message: `Server '${serverId}' cannot execute tools in this way.` });
    }

    const result = await server.executeTool(toolId, data, { requestContext });
    return { result };
  },
});

// ============================================================================
// MCP Resource Routes
// ============================================================================

export const LIST_MCP_SERVER_RESOURCES_ROUTE = createRoute({
  method: 'GET',
  path: '/mcp/:serverId/resources',
  responseType: 'json',
  pathParamSchema: mcpServerResourcePathParams,
  responseSchema: listResourcesResponseSchema,
  summary: 'List MCP server resources',

View on GitHub (pinned to 75dd419e61)

Solutions

1. Register a real MCPServer instance from @mastra/core/mcp, which implements executeTool.
2. Update @mastra/core so the registered server class includes executeTool.
3. If you wrapped or stubbed the server, add/forward executeTool(toolId, data, { requestContext }).
4. Use a different execution path (direct client/tool call) if the server intentionally does not support remote tool execution.

Example fix

// before
const server = { id: 'weather', listResources: async () => [] };
// after
import { MCPServer } from '@mastra/core/mcp';
const server = new MCPServer({ id: 'weather' /* full config */ });

const server = mastra.getMCPServerById(serverId);
if (server && typeof (server as any).executeTool !== 'function') {
  throw new Error(`Server '${serverId}' does not support tool execution via HTTP`);
}

function canExecuteTools(server: unknown): server is { executeTool: (toolId: string, data?: unknown, opts?: unknown) => Promise<unknown> } {
  return !!server && typeof (server as any).executeTool === 'function';
}

try {
  const { result } = await executeMcpTool(serverId, toolId, data);
} catch (e) {
  if (e.status === 501) {
    console.warn(`Server ${serverId} cannot execute tools; use direct MCPServer client instead`);
    return;
  }
  throw e;
}

When it happens

Trigger: POST /mcp/:serverId/tools/:toolId/execute where getMCPServerById returns an object whose interface lacks executeTool — typically a custom MCP server wrapper, a stubbed object, or an older/alternative server implementation in @mastra/core/mcp.

Common situations: Test doubles for MCP servers missing executeTool; mixing server object types from different @mastra/core versions; wrapping/proxying MCP server objects and dropping methods.

Related errors

• Cannot authenticate MCP server ${serverName}: it is not conf
• Mastra instance or listMCPServers method not available
• No relevance score found in VoyageAI response
• ${label} must be a string.
• ${label} must be an object.

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/bdec3c00545e67a4. Report an issue: GitHub.