fix(tools): add cursor pagination to find_projects/find_organizations/find_teams (#1319)

`find_projects`, `find_organizations`, and `find_teams` can now fetch
the remaining results through cursor pagination instead of requiring
callers to narrow the query after the first 25 items.

Requests return up to 25 items by default. The optional `limit` controls
the page size (1–100), with no cap on the total number of items
retrieved across pages. Continue with `nextCursor`, keeping the same
filters, scope, and page size. `hasMore` reflects whether the API
returned a cursor for another page.

The implementation reuses the existing Link-header parser and response
helpers, shares the cursor parameter, and updates generated definitions
and the existing integration coverage.

---------

Co-authored-by: betegon <miguelbetegongarcia@gmail.com>
Co-authored-by: Codex (GPT-6) <noreply@openai.com>

Author: 3 people

docs/operations/security.md

@@ -323,8 +323,8 @@ catch (error) {
 
 ```typescript
 // Verify organization access
-const orgs = await apiService.listOrganizations();
-if (!orgs.find(org => org.slug === requestedOrg)) {
+const { organizations } = await apiService.listOrganizations();
+if (!organizations.find(org => org.slug === requestedOrg)) {
   throw new UserInputError("No access to organization");
 }
 ```

packages/mcp-core/src/api-client/client.test.ts

@@ -1309,6 +1309,7 @@ describe("listOrganizations", () => {
       if (url.includes("/organizations/")) {
         return Promise.resolve({
           ok: true,
+          headers: new Headers({ "content-type": "application/json" }),
           json: () => Promise.resolve(mockOrgs),
         });
       }
@@ -1320,12 +1321,17 @@ describe("listOrganizations", () => {
       accessToken: "test-token",
     });
 
-    const result = await apiService.listOrganizations();
+    const { organizations, nextCursor } = await apiService.listOrganizations();
 
     expect(callCount).toBe(1); // Single call, no region fanout
-    expect(result).toHaveLength(2);
-    expect(result).toContainEqual(expect.objectContaining({ slug: "org-us" }));
-    expect(result).toContainEqual(expect.objectContaining({ slug: "org-eu" }));
+    expect(organizations).toHaveLength(2);
+    expect(organizations).toContainEqual(
+      expect.objectContaining({ slug: "org-us" }),
+    );
+    expect(organizations).toContainEqual(
+      expect.objectContaining({ slug: "org-eu" }),
+    );
+    expect(nextCursor).toBeNull();
     // Region fanout is no longer used
     expect(globalThis.fetch).not.toHaveBeenCalledWith(
       expect.stringContaining("/users/me/regions/"),
@@ -1345,6 +1351,7 @@ describe("listOrganizations", () => {
       if (url.includes("/organizations/")) {
         return Promise.resolve({
           ok: true,
+          headers: new Headers({ "content-type": "application/json" }),
           json: () => Promise.resolve(mockOrgs),
         });
       }
@@ -1356,11 +1363,12 @@ describe("listOrganizations", () => {
       accessToken: "test-token",
     });
 
-    const result = await apiService.listOrganizations();
+    const { organizations, nextCursor } = await apiService.listOrganizations();
 
     expect(callCount).toBe(1); // Only 1 org call, no regions call
-    expect(result).toHaveLength(2);
-    expect(result).toEqual(mockOrgs);
+    expect(organizations).toHaveLength(2);
+    expect(organizations).toEqual(mockOrgs);
+    expect(nextCursor).toBeNull();
     // Verify that regions endpoint was not called
     expect(globalThis.fetch).not.toHaveBeenCalledWith(
       expect.stringContaining("/users/me/regions/"),

packages/mcp-core/src/api-client/client.ts

@@ -1614,19 +1614,20 @@ export class SentryApiService {
   }
 
   /**
-   * Lists all organizations accessible to the authenticated user.
+   * Lists a page of organizations accessible to the authenticated user.
    *
    * Queries the `/organizations/` endpoint on the root host.
    *
    * @param params Query parameters
    * @param params.query Search query to filter organizations by name/slug
    * @param params.limit Maximum number of organizations to return (defaults to 25)
-   * @returns Array of organizations across all accessible regions
+   * @param params.cursor Pagination cursor from a previous call's nextCursor
+   * @returns A page of organizations across all accessible regions, plus a cursor for the next page (null once exhausted)
    *
    * @example
    * ```typescript
-   * const orgs = await apiService.listOrganizations();
-   * orgs.forEach(org => {
+   * const { organizations } = await apiService.listOrganizations();
+   * organizations.forEach(org => {
    *   // regionUrl present for Cloud Service, empty for self-hosted
    *   console.log(`${org.name} (${org.slug}) - ${org.links?.regionUrl || 'No region URL'}`);
    * });
@@ -1635,7 +1636,8 @@ export class SentryApiService {
   async listOrganizations(params?: {
     query?: string;
     limit?: number;
-  }): Promise<OrganizationList> {
+    cursor?: string | null;
+  }): Promise<{ organizations: OrganizationList; nextCursor: string | null }> {
     const limit = params?.limit ?? 25;
 
     // Build query parameters
@@ -1644,6 +1646,9 @@ export class SentryApiService {
     if (params?.query) {
       queryParams.set("query", params.query);
     }
+    if (params?.cursor) {
+      queryParams.set("cursor", params.cursor);
+    }
     const queryString = queryParams.toString();
     const path = `/organizations/?${queryString}`;
 
@@ -1654,8 +1659,13 @@ export class SentryApiService {
       host = "sentry.io";
     }
 
-    const body = await this.requestJSON(path, undefined, { host });
-    return OrganizationListSchema.parse(body);
+    const response = await this.request(path, undefined, { host });
+    const body = await this.parseJsonResponse(response);
+
+    return {
+      organizations: OrganizationListSchema.parse(body),
+      nextCursor: getNextCursor(response.headers.get("link")),
+    };
   }
 
   /**
@@ -1675,31 +1685,40 @@ export class SentryApiService {
   }
 
   /**
-   * Lists teams within an organization.
+   * Lists a page of teams within an organization.
    *
    * @param organizationSlug Organization identifier
    * @param params Query parameters
    * @param params.query Search query to filter teams by name/slug
    * @param params.limit Maximum number of teams to return
+   * @param params.cursor Pagination cursor from a previous call's nextCursor
    * @param opts Request options including host override
-   * @returns Array of teams in the organization
+   * @returns A page of teams in the organization, plus a cursor for the next page (null once exhausted)
    */
   async listTeams(
     organizationSlug: string,
-    params?: { query?: string; limit?: number },
+    params?: { query?: string; limit?: number; cursor?: string | null },
     opts?: RequestOptions,
-  ): Promise<TeamList> {
+  ): Promise<{ teams: TeamList; nextCursor: string | null }> {
     const queryParams = new URLSearchParams();
     queryParams.set("per_page", String(params?.limit ?? 25));
     if (params?.query) {
       queryParams.set("query", params.query);
     }
+    if (params?.cursor) {
+      queryParams.set("cursor", params.cursor);
+    }
     const queryString = queryParams.toString();
     const teamsPath = apiPath`/organizations/${organizationSlug}/teams/`;
     const path = `${teamsPath}?${queryString}`;
 
-    const body = await this.requestJSON(path, undefined, opts);
-    return TeamListSchema.parse(body);
+    const response = await this.request(path, undefined, opts);
+    const body = await this.parseJsonResponse(response);
+
+    return {
+      teams: TeamListSchema.parse(body),
+      nextCursor: getNextCursor(response.headers.get("link")),
+    };
   }
 
   /**
@@ -1740,25 +1759,34 @@ export class SentryApiService {
    * @param params Query parameters
    * @param params.query Search query to filter projects by name/slug
    * @param params.limit Maximum number of projects to return
+   * @param params.cursor Pagination cursor from a previous call's nextCursor
    * @param opts Request options
-   * @returns Array of projects in the organization
+   * @returns Projects in the organization, plus a cursor for the next page (null once exhausted)
    */
   async listProjects(
     organizationSlug: string,
-    params?: { query?: string; limit?: number },
+    params?: { query?: string; limit?: number; cursor?: string | null },
     opts?: RequestOptions,
-  ): Promise<ProjectList> {
+  ): Promise<{ projects: ProjectList; nextCursor: string | null }> {
     const queryParams = new URLSearchParams();
     queryParams.set("per_page", String(params?.limit ?? 25));
     if (params?.query) {
       queryParams.set("query", params.query);
     }
+    if (params?.cursor) {
+      queryParams.set("cursor", params.cursor);
+    }
     const queryString = queryParams.toString();
     const projectsPath = apiPath`/organizations/${organizationSlug}/projects/`;
     const path = `${projectsPath}?${queryString}`;
 
-    const body = await this.requestJSON(path, undefined, opts);
-    return ProjectListSchema.parse(body);
+    const response = await this.request(path, undefined, opts);
+    const body = await this.parseJsonResponse(response);
+
+    return {
+      projects: ProjectListSchema.parse(body),
+      nextCursor: getNextCursor(response.headers.get("link")),
+    };
   }
 
   async listDashboards(

packages/mcp-core/src/schema.ts

@@ -50,6 +50,12 @@ export const ParamSearchQuery = z
     "Search query to filter results by name or slug. Use this to narrow down results when there are many items.",
   );
 
+export const ParamCursor = z
+  .string()
+  .describe(
+    "Pagination cursor from a previous call's nextCursor. Reuse it with the same filters, scope, and limit to fetch the next page.",
+  );
+
 export const ParamIssueShortId = z
   .string()
   .toUpperCase()

packages/mcp-core/src/server.test.ts

@@ -1414,6 +1414,7 @@ describe("buildServer", () => {
           },
         ],
         hasMore: false,
+        nextCursor: null,
       });
       expect(getTextContent(result)).toBe(
         getGeneratedTextFromStructuredContent(result),