🪢 fix: Paginate MCP tools/list to Load All Tools

packages/api/src/mcp/__tests__/MCPConnectionAgentLifecycle.test.ts

@@ -45,7 +45,7 @@ jest.mock('~/auth', () => ({
 }));
 
 jest.mock('~/mcp/mcpConfig', () => ({
-  mcpConfig: { CONNECTION_CHECK_TTL: 0 },
+  mcpConfig: { CONNECTION_CHECK_TTL: 0, TOOLS_LIST_MAX_PAGES: 50 },
 }));
 
 const mockLogger = logger as jest.Mocked<typeof logger>;

packages/api/src/mcp/__tests__/MCPConnectionFactory.oauthSdk.integration.test.ts

@@ -40,7 +40,11 @@ jest.mock('~/auth', () => ({
 }));
 
 jest.mock('~/mcp/mcpConfig', () => ({
-  mcpConfig: { CONNECTION_CHECK_TTL: 0, USER_CONNECTION_IDLE_TIMEOUT: 30 * 60 * 1000 },
+  mcpConfig: {
+    CONNECTION_CHECK_TTL: 0,
+    USER_CONNECTION_IDLE_TIMEOUT: 30 * 60 * 1000,
+    TOOLS_LIST_MAX_PAGES: 50,
+  },
 }));
 
 const SERVER_NAME = 'sdk-oauth-server';

packages/api/src/mcp/__tests__/MCPConnectionFetchTools.test.ts

@@ -0,0 +1,183 @@
+/**
+ * Unit tests for MCPConnection.fetchTools pagination.
+ *
+ * MCP `tools/list` is a paginated method: the server may return a page of tools
+ * plus a `nextCursor` that the client must follow to retrieve the rest. These
+ * tests verify that fetchTools walks every page, passes the cursor back
+ * unchanged, and is bounded against misbehaving servers (page cap + repeated
+ * cursor guard) while preserving the original single-page and error behavior.
+ */
+
+import { logger } from '@librechat/data-schemas';
+import { MCPConnection } from '~/mcp/connection';
+
+jest.mock('@librechat/data-schemas', () => ({
+  logger: {
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+    debug: jest.fn(),
+  },
+}));
+
+jest.mock('~/auth', () => ({
+  createSSRFSafeUndiciConnect: jest.fn(() => undefined),
+  isOAuthUrlAllowed: jest.fn(() => false),
+  isSSRFTarget: jest.fn(() => false),
+  resolveHostnameSSRF: jest.fn(async () => false),
+}));
+
+/** Pin the page cap to a small value so the cap path is cheap to exercise. */
+jest.mock('~/mcp/mcpConfig', () => ({
+  mcpConfig: { TOOLS_LIST_MAX_PAGES: 3, CONNECTION_CHECK_TTL: 0 },
+}));
+
+const mockLogger = logger as jest.Mocked<typeof logger>;
+
+const makeTool = (name: string) => ({
+  name,
+  description: `${name} description`,
+  inputSchema: { type: 'object' as const, properties: {} },
+});
+
+/** Build a bare MCPConnection (no real transport) with an injected, controllable client. */
+function createConnectionWithListTools(listTools: jest.Mock): MCPConnection {
+  const conn = new MCPConnection({
+    serverName: 'pagination-test',
+    serverConfig: { type: 'streamable-http', url: 'http://localhost/mcp' },
+    useSSRFProtection: false,
+  });
+  conn.client = { listTools } as unknown as MCPConnection['client'];
+  return conn;
+}
+
+describe('MCPConnection.fetchTools pagination', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('returns the tools from a single page and makes one request when there is no nextCursor', async () => {
+    const listTools = jest.fn().mockResolvedValue({ tools: [makeTool('a'), makeTool('b')] });
+    const conn = createConnectionWithListTools(listTools);
+
+    const tools = await conn.fetchTools();
+
+    expect(tools.map((t) => t.name)).toEqual(['a', 'b']);
+    expect(listTools).toHaveBeenCalledTimes(1);
+    expect(listTools).toHaveBeenNthCalledWith(1, undefined);
+    expect(mockLogger.warn).not.toHaveBeenCalled();
+  });
+
+  it('follows nextCursor across pages, concatenating every tool and passing the cursor back', async () => {
+    const listTools = jest.fn(async (params?: { cursor?: string }) => {
+      switch (params?.cursor) {
+        case undefined:
+          return { tools: [makeTool('a'), makeTool('b')], nextCursor: 'c1' };
+        case 'c1':
+          return { tools: [makeTool('c'), makeTool('d')], nextCursor: 'c2' };
+        case 'c2':
+          return { tools: [makeTool('e')] };
+        default:
+          throw new Error(`unexpected cursor: ${params?.cursor}`);
+      }
+    });
+    const conn = createConnectionWithListTools(listTools);
+
+    const tools = await conn.fetchTools();
+
+    expect(tools.map((t) => t.name)).toEqual(['a', 'b', 'c', 'd', 'e']);
+    expect(listTools).toHaveBeenCalledTimes(3);
+    expect(listTools).toHaveBeenNthCalledWith(1, undefined);
+    expect(listTools).toHaveBeenNthCalledWith(2, { cursor: 'c1' });
+    expect(listTools).toHaveBeenNthCalledWith(3, { cursor: 'c2' });
+    expect(mockLogger.warn).not.toHaveBeenCalled();
+  });
+
+  it('stops at the page cap and warns when a server keeps returning new cursors', async () => {
+    let page = 0;
+    const listTools = jest.fn(async () => {
+      page += 1;
+      return { tools: [makeTool(`t${page}`)], nextCursor: `cursor-${page}` };
+    });
+    const conn = createConnectionWithListTools(listTools);
+
+    const tools = await conn.fetchTools();
+
+    // mcpConfig.TOOLS_LIST_MAX_PAGES is mocked to 3.
+    expect(listTools).toHaveBeenCalledTimes(3);
+    expect(tools.map((t) => t.name)).toEqual(['t1', 't2', 't3']);
+    expect(mockLogger.warn).toHaveBeenCalledWith(expect.stringContaining('pagination limit'));
+  });
+
+  it('stops and warns when the server repeats a cursor instead of looping forever', async () => {
+    const listTools = jest.fn().mockResolvedValue({ tools: [makeTool('x')], nextCursor: 'same' });
+    const conn = createConnectionWithListTools(listTools);
+
+    const tools = await conn.fetchTools();
+
+    expect(listTools).toHaveBeenCalledTimes(2);
+    // The second page's tools are collected before the repeated cursor is detected, hence two copies.
+    expect(tools.map((t) => t.name)).toEqual(['x', 'x']);
+    expect(mockLogger.warn).toHaveBeenCalledWith(
+      expect.stringContaining('repeated tools/list cursor'),
+    );
+  });
+
+  it('continues paginating across an empty intermediate page', async () => {
+    const listTools = jest.fn(async (params?: { cursor?: string }) => {
+      if (params?.cursor == null) {
+        return { tools: [], nextCursor: 'c1' };
+      }
+      return { tools: [makeTool('a')] };
+    });
+    const conn = createConnectionWithListTools(listTools);
+
+    const tools = await conn.fetchTools();
+
+    expect(tools.map((t) => t.name)).toEqual(['a']);
+    expect(listTools).toHaveBeenCalledTimes(2);
+  });
+
+  it('treats an empty-string nextCursor as a valid cursor, not end-of-list', async () => {
+    const listTools = jest.fn(async (params?: { cursor?: string }) => {
+      if (params?.cursor == null) {
+        return { tools: [makeTool('a')], nextCursor: '' };
+      }
+      return { tools: [makeTool('b')] };
+    });
+    const conn = createConnectionWithListTools(listTools);
+
+    const tools = await conn.fetchTools();
+
+    expect(tools.map((t) => t.name)).toEqual(['a', 'b']);
+    expect(listTools).toHaveBeenCalledTimes(2);
+    expect(listTools).toHaveBeenNthCalledWith(2, { cursor: '' });
+  });
+
+  it('returns the pages already fetched when a later page fails, without throwing', async () => {
+    const listTools = jest.fn(async (params?: { cursor?: string }) => {
+      if (params?.cursor == null) {
+        return { tools: [makeTool('a'), makeTool('b')], nextCursor: 'c1' };
+      }
+      throw new Error('page 2 boom');
+    });
+    const conn = createConnectionWithListTools(listTools);
+
+    const tools = await conn.fetchTools();
+
+    expect(tools.map((t) => t.name)).toEqual(['a', 'b']);
+    expect(listTools).toHaveBeenCalledTimes(2);
+    expect(mockLogger.error).toHaveBeenCalledWith(expect.stringContaining('Failed to fetch tools'));
+  });
+
+  it('returns an empty array when the first page request rejects', async () => {
+    const listTools = jest.fn().mockRejectedValue(new Error('boom'));
+    const conn = createConnectionWithListTools(listTools);
+
+    const tools = await conn.fetchTools();
+
+    expect(tools).toEqual([]);
+    expect(listTools).toHaveBeenCalledTimes(1);
+    expect(mockLogger.error).toHaveBeenCalledWith(expect.stringContaining('Failed to fetch tools'));
+  });
+});

packages/api/src/mcp/__tests__/MCPConnectionSSRF.test.ts

@@ -71,7 +71,7 @@ jest.mock('~/auth', () => ({
 }));
 
 jest.mock('~/mcp/mcpConfig', () => ({
-  mcpConfig: { CONNECTION_CHECK_TTL: 0 },
+  mcpConfig: { CONNECTION_CHECK_TTL: 0, TOOLS_LIST_MAX_PAGES: 50 },
 }));
 
 const mockedResolveHostnameSSRF = resolveHostnameSSRF as jest.MockedFunction<

packages/api/src/mcp/__tests__/dbSourced.integration.test.ts

@@ -43,7 +43,7 @@ jest.mock('~/auth', () => ({
 }));
 
 jest.mock('~/mcp/mcpConfig', () => ({
-  mcpConfig: { CONNECTION_CHECK_TTL: 0 },
+  mcpConfig: { CONNECTION_CHECK_TTL: 0, TOOLS_LIST_MAX_PAGES: 50 },
 }));
 
 /** Track all Agents for cleanup */

packages/api/src/mcp/connection.ts

@@ -2191,6 +2191,15 @@ export class MCPConnection extends EventEmitter {
     }
   }
 
+  /**
+   * Fetches the server's tools, following MCP `tools/list` cursor pagination so a
+   * server that spans multiple pages (e.g. an aggregating gateway exposing many
+   * tools) is loaded in full instead of being truncated to the first page.
+   *
+   * Pagination is bounded by {@link mcpConfig.TOOLS_LIST_MAX_PAGES} and a
+   * repeated-cursor guard. On error, the tools already fetched are returned rather
+   * than discarded, and the method never throws.
+   */
   async fetchTools(): Promise<
     {
       inputSchema: {
@@ -2235,13 +2244,42 @@ export class MCPConnection extends EventEmitter {
       title?: string | undefined;
     }[]
   > {
-    try {
-      const { tools } = await this.client.listTools();
-      return tools;
-    } catch (error) {
-      this.emitError(error, 'Failed to fetch tools');
-      return [];
+    const allTools: Awaited<ReturnType<typeof this.client.listTools>>['tools'] = [];
+    const seenCursors = new Set<string>();
+    let cursor: string | undefined;
+    let hasMore = true;
+
+    for (let page = 1; page <= mcpConfig.TOOLS_LIST_MAX_PAGES && hasMore; page++) {
+      try {
+        const { tools, nextCursor } = await this.client.listTools(
+          cursor != null ? { cursor } : undefined,
+        );
+        allTools.push(...tools);
+
+        if (nextCursor == null) {
+          hasMore = false;
+        } else if (seenCursors.has(nextCursor)) {
+          logger.warn(
+            `${this.getLogPrefix()} MCP server returned a repeated tools/list cursor; stopping pagination after ${page} page(s).`,
+          );
+          hasMore = false;
+        } else {
+          seenCursors.add(nextCursor);
+          cursor = nextCursor;
+        }
+      } catch (error) {
+        this.emitError(error, 'Failed to fetch tools');
+        hasMore = false;
+      }
     }
+
+    if (hasMore) {
+      logger.warn(
+        `${this.getLogPrefix()} Reached the tools/list pagination limit of ${mcpConfig.TOOLS_LIST_MAX_PAGES} page(s); some tools may be omitted. Set MCP_TOOLS_LIST_MAX_PAGES higher if this server legitimately exposes more.`,
+      );
+    }
+
+    return allTools;
   }
 
   async fetchPrompts(): Promise<t.MCPPrompt[]> {

packages/api/src/mcp/mcpConfig.ts

@@ -23,6 +23,9 @@ export const mcpConfig: {
   /** TTL (ms) for OAuth flow state. Must outlive OAUTH_HANDLING_TIMEOUT so the state survives the wait. Default: 15 minutes */
   OAUTH_FLOW_TTL: number;
   CONNECTION_CHECK_TTL: number;
+  /** Max number of `tools/list` pages to request when an MCP server paginates its tool list.
+   * Bounds the pagination loop so a misbehaving server cannot stall tool discovery. Default: 50 */
+  TOOLS_LIST_MAX_PAGES: number;
   /** Idle timeout (ms) after which user connections are disconnected. Default: 15 minutes */
   USER_CONNECTION_IDLE_TIMEOUT: number;
   /** Max connect/disconnect cycles before the circuit breaker trips. Default: 7 */
@@ -47,6 +50,8 @@ export const mcpConfig: {
   /** TTL (ms) for OAuth flow state. Clamped to never fall below OAUTH_HANDLING_TIMEOUT. Default: 15 minutes */
   OAUTH_FLOW_TTL: oauthFlowTtl,
   CONNECTION_CHECK_TTL: math(process.env.MCP_CONNECTION_CHECK_TTL ?? 60000),
+  /** Max number of `tools/list` pages to request when an MCP server paginates its tool list. Clamped to >= 1. Default: 50 */
+  TOOLS_LIST_MAX_PAGES: Math.max(1, math(process.env.MCP_TOOLS_LIST_MAX_PAGES ?? 50)),
   /** Idle timeout (ms) after which user connections are disconnected. Default: 15 minutes */
   USER_CONNECTION_IDLE_TIMEOUT: math(
     process.env.MCP_USER_CONNECTION_IDLE_TIMEOUT ?? 15 * 60 * 1000,

packages/api/src/mcp/registry/MCPServerInspector.ts

@@ -150,8 +150,8 @@ export class MCPServerInspector {
   private async fetchServerCapabilities(): Promise<void> {
     const capabilities = this.connection!.client.getServerCapabilities();
     this.config.capabilities = JSON.stringify(capabilities);
-    const tools = await this.connection!.client.listTools();
-    this.config.tools = tools.tools.map((tool) => tool.name).join(', ');
+    const tools = await this.connection!.fetchTools();
+    this.config.tools = tools.map((tool) => tool.name).join(', ');
   }
 
   private async fetchToolFunctions(): Promise<void> {
@@ -171,7 +171,7 @@ export class MCPServerInspector {
     serverName: string,
     connection: MCPConnection,
   ): Promise<t.LCAvailableTools> {
-    const { tools }: t.MCPToolListResponse = await connection.client.listTools();
+    const tools = await connection.fetchTools();
 
     const toolFunctions: t.LCAvailableTools = {};
     tools.forEach((tool) => {

packages/api/src/mcp/registry/__tests__/MCPReinitRecovery.integration.test.ts

@@ -56,7 +56,7 @@ jest.mock('~/cluster', () => ({
 }));
 
 jest.mock('~/mcp/mcpConfig', () => ({
-  mcpConfig: { CONNECTION_CHECK_TTL: 0 },
+  mcpConfig: { CONNECTION_CHECK_TTL: 0, TOOLS_LIST_MAX_PAGES: 50 },
 }));
 
 jest.mock('~/mcp/registry/db/ServerConfigsDB', () => ({