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.

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.

Appendix: 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)