What causes "MCP_CLIENT_ON_LIST_CHANGED_TOOLS_FAILED" in mastra-ai/mastra?

Confirm serverName is configured and spelled correctly.

mastra-ai/mastra · error · MastraError

MCP_CLIENT_ON_LIST_CHANGED_TOOLS_FAILED

MCP_CLIENT_ON_LIST_CHANGED_TOOLS_FAILED

Error message

MCP_CLIENT_ON_LIST_CHANGED_TOOLS_FAILED

What it means

MastraError thrown when registering a tool list-changed notification handler fails. Like the prompts variant, it resolves a connected client for the server and then calls setToolListChangedNotificationHandler; any failure to connect is wrapped with the serverName in details. It means tool change notifications cannot be subscribed for that server.

Source

Thrown at packages/mcp/src/client/configuration.ts:692

       *
       * @param serverName - Name of the server to monitor
       * @param handler - Callback function invoked when tools are added/removed/modified
       * @returns Promise resolving when handler is registered
       * @throws {MastraError} If setting up the handler fails
       *
       * @example
       * ```typescript
       * await mcp.tools.onListChanged('weatherServer', async () => {
       *   const tools = await mcp.listTools();
       * });
       * ```
       */
      onListChanged: async (serverName: string, handler: () => void) => {
        try {
          const internalClient = await this.getConnectedClientForServer(serverName);
          return internalClient.setToolListChangedNotificationHandler(handler);
        } catch (error) {
          throw new MastraError(
            {
              id: 'MCP_CLIENT_ON_LIST_CHANGED_TOOLS_FAILED',
              domain: ErrorDomain.MCP,
              category: ErrorCategory.THIRD_PARTY,
              details: {
                serverName,
              },
            },
            error,
          );
        }
      },
    };
  }

  private addToInstanceCache() {
    if (!mcpClientInstances.has(this.id)) {
      mcpClientInstances.set(this.id, this);

View on GitHub (pinned to 75dd419e61)

Solutions

Confirm serverName is configured and spelled correctly.
Establish the connection before calling onListChanged.
Inspect the wrapped cause for the transport-level failure (e.g., stdio spawn error, HTTP 4xx/5xx).
Re-register the handler after the client reconnects.

Example fix

// before
client.tools.onListChanged(serverName, handler);
// after
try {
  client.tools.onListChanged(serverName, handler);
} catch (e) {
  logger.error('tool-list subscription failed', { serverName, cause: (e as MastraError).detail?.originalMessage });
}

Defensive patterns

Strategy: try-catch

Validate before calling

if (!Object.keys(configuredServers).includes(serverName)) throw new Error(`unknown server ${serverName}`);
await client.getConnectedClientForServer(serverName);

Try / catch

try {
  client.tools.onListChanged(serverName, handler);
} catch (e) {
  if (e instanceof MastraError && e.id === 'MCP_CLIENT_ON_LIST_CHANGED_TOOLS_FAILED') {
    logger.error('tool list subscription failed', { serverName, cause: e });
  } else throw e;
}

Prevention

Wire tool-change subscriptions after initial connection succeeds.
Re-register handlers after reconnects.
Validate server names against config keys at startup.
Keep handler registration idempotent to survive retries.

When it happens

Trigger: Calling mcpClient.tools.onListChanged(serverName, handler) (or getToolsForServer paths that set it up) when the connection for serverName cannot be established.

Common situations: Server name typo; server not yet connected when wiring dynamic tool refresh; MCP server restarted and connection dropped before handler registration.

Related errors

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