feat: add search support to find_organizations, find_teams, and find_projects (#574)

Add optional query parameter to list endpoints to support filtering by
name/slug. Return up to 25 results with clear messaging when limit is
hit, directing users to use the query parameter to narrow results.

Changes:
- Added ParamSearchQuery schema for consistent search validation
- Updated API client methods (listOrganizations, listTeams,
listProjects) to accept query parameter
- Hardcoded per_page=25 limit in API client (not exposed to callers)
- Updated all three find_* tools to support optional query parameter
- Added warning message when hitting 25 result limit
- Updated tool descriptions to mention search capability and result
limits

Fixes #573

---------

Co-authored-by: Claude Code <noreply@anthropic.com>

Author: dcramer

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

@@ -798,8 +798,10 @@ export class SentryApiService {
    * Automatically handles multi-region queries by fetching from all
    * available regions and combining results.
    *
+   * @param params Query parameters
+   * @param params.query Search query to filter organizations by name/slug
    * @param opts Request options
-   * @returns Array of organizations across all accessible regions
+   * @returns Array of organizations across all accessible regions (limited to 25 results)
    *
    * @example
    * ```typescript
@@ -810,10 +812,22 @@ export class SentryApiService {
    * });
    * ```
    */
-  async listOrganizations(opts?: RequestOptions): Promise<OrganizationList> {
+  async listOrganizations(
+    params?: { query?: string },
+    opts?: RequestOptions,
+  ): Promise<OrganizationList> {
+    // Build query parameters
+    const queryParams = new URLSearchParams();
+    queryParams.set("per_page", "25");
+    if (params?.query) {
+      queryParams.set("query", params.query);
+    }
+    const queryString = queryParams.toString();
+    const path = `/organizations/?${queryString}`;
+
     // For self-hosted instances, the regions endpoint doesn't exist
     if (!this.isSaas()) {
-      const body = await this.requestJSON("/organizations/", undefined, opts);
+      const body = await this.requestJSON(path, undefined, opts);
       return OrganizationListSchema.parse(body);
     }
 
@@ -828,10 +842,10 @@ export class SentryApiService {
       );
       const regionData = UserRegionsSchema.parse(regionsBody);
 
-      return (
+      const allOrganizations = (
         await Promise.all(
           regionData.regions.map(async (region) =>
-            this.requestJSON(`/organizations/`, undefined, {
+            this.requestJSON(path, undefined, {
               ...opts,
               host: new URL(region.url).host,
             }),
@@ -840,12 +854,15 @@ export class SentryApiService {
       )
         .map((data) => OrganizationListSchema.parse(data))
         .reduce((acc, curr) => acc.concat(curr), []);
+
+      // Apply the limit after combining results from all regions
+      return allOrganizations.slice(0, 25);
     } catch (error) {
       // If regions endpoint fails (e.g., older self-hosted versions identifying as sentry.io),
       // fall back to direct organizations endpoint
       if (error instanceof ApiNotFoundError) {
         // logger.info("Regions endpoint not found, falling back to direct organizations endpoint");
-        const body = await this.requestJSON("/organizations/", undefined, opts);
+        const body = await this.requestJSON(path, undefined, opts);
         return OrganizationListSchema.parse(body);
       }
 
@@ -874,18 +891,25 @@ export class SentryApiService {
    * Lists teams within an organization.
    *
    * @param organizationSlug Organization identifier
+   * @param params Query parameters
+   * @param params.query Search query to filter teams by name/slug
    * @param opts Request options including host override
-   * @returns Array of teams in the organization
+   * @returns Array of teams in the organization (limited to 25 results)
    */
   async listTeams(
     organizationSlug: string,
+    params?: { query?: string },
     opts?: RequestOptions,
   ): Promise<TeamList> {
-    const body = await this.requestJSON(
-      `/organizations/${organizationSlug}/teams/`,
-      undefined,
-      opts,
-    );
+    const queryParams = new URLSearchParams();
+    queryParams.set("per_page", "25");
+    if (params?.query) {
+      queryParams.set("query", params.query);
+    }
+    const queryString = queryParams.toString();
+    const path = `/organizations/${organizationSlug}/teams/?${queryString}`;
+
+    const body = await this.requestJSON(path, undefined, opts);
     return TeamListSchema.parse(body);
   }
 
@@ -924,18 +948,25 @@ export class SentryApiService {
    * Lists projects within an organization.
    *
    * @param organizationSlug Organization identifier
+   * @param params Query parameters
+   * @param params.query Search query to filter projects by name/slug
    * @param opts Request options
-   * @returns Array of projects in the organization
+   * @returns Array of projects in the organization (limited to 25 results)
    */
   async listProjects(
     organizationSlug: string,
+    params?: { query?: string },
     opts?: RequestOptions,
   ): Promise<ProjectList> {
-    const body = await this.requestJSON(
-      `/organizations/${organizationSlug}/projects/`,
-      undefined,
-      opts,
-    );
+    const queryParams = new URLSearchParams();
+    queryParams.set("per_page", "25");
+    if (params?.query) {
+      queryParams.set("query", params.query);
+    }
+    const queryString = queryParams.toString();
+    const path = `/organizations/${organizationSlug}/projects/?${queryString}`;
+
+    const body = await this.requestJSON(path, undefined, opts);
     return ProjectListSchema.parse(body);
   }
 

packages/mcp-server/src/schema.ts

@@ -45,6 +45,13 @@ export const ParamProjectSlugOrAll = z
     "The project's slug. This will default to all projects you have access to. It is encouraged to specify this when possible.",
   );
 
+export const ParamSearchQuery = z
+  .string()
+  .trim()
+  .describe(
+    "Search query to filter results by name or slug. Use this to narrow down results when there are many items.",
+  );
+
 export const ParamIssueShortId = z
   .string()
   .toUpperCase()

packages/mcp-server/src/tools/find-organizations.ts

@@ -1,6 +1,9 @@
 import { defineTool } from "../internal/tool-helpers/define";
 import { apiServiceFromContext } from "../internal/tool-helpers/api";
 import type { ServerContext } from "../types";
+import { ParamSearchQuery } from "../schema";
+
+const RESULT_LIMIT = 25;
 
 export default defineTool({
   name: "find_organizations",
@@ -9,20 +12,33 @@ export default defineTool({
     "Find organizations that the user has access to in Sentry.",
     "",
     "Use this tool when you need to:",
-    "- View all organizations in Sentry",
+    "- View organizations in Sentry",
     "- Find an organization's slug to aid other tool requests",
+    "- Search for specific organizations by name or slug",
+    "",
+    `Returns up to ${RESULT_LIMIT} results. If you hit this limit, use the query parameter to narrow down results.`,
   ].join("\n"),
-  inputSchema: {},
+  inputSchema: {
+    query: ParamSearchQuery.optional(),
+  },
   async handler(params, context: ServerContext) {
     // User data endpoints (like /users/me/regions/) should never use regionUrl
     // as they must always query the main API server, not region-specific servers
     const apiService = apiServiceFromContext(context);
-    const organizations = await apiService.listOrganizations();
+    const organizations = await apiService.listOrganizations({
+      query: params.query,
+    });
 
     let output = "# Organizations\n\n";
 
+    if (params.query) {
+      output += `**Search query:** "${params.query}"\n\n`;
+    }
+
     if (organizations.length === 0) {
-      output += "You don't appear to be a member of any organizations.\n";
+      output += params.query
+        ? `No organizations found matching "${params.query}".\n`
+        : "You don't appear to be a member of any organizations.\n";
       return output;
     }
 
@@ -37,6 +53,10 @@ export default defineTool({
       )
       .join("\n\n");
 
+    if (organizations.length === RESULT_LIMIT) {
+      output += `\n\n---\n\n**Note:** Showing ${RESULT_LIMIT} results (maximum). There may be more organizations available. Use the \`query\` parameter to search for specific organizations.`;
+    }
+
     output += "\n\n# Using this information\n\n";
     output += `- The organization's name is the identifier for the organization, and is used in many tools for \`organizationSlug\`.\n`;
 

packages/mcp-server/src/tools/find-projects.ts

@@ -3,7 +3,13 @@ import { defineTool } from "../internal/tool-helpers/define";
 import { apiServiceFromContext } from "../internal/tool-helpers/api";
 import { UserInputError } from "../errors";
 import type { ServerContext } from "../types";
-import { ParamOrganizationSlug, ParamRegionUrl } from "../schema";
+import {
+  ParamOrganizationSlug,
+  ParamRegionUrl,
+  ParamSearchQuery,
+} from "../schema";
+
+const RESULT_LIMIT = 25;
 
 export default defineTool({
   name: "find_projects",
@@ -12,12 +18,16 @@ export default defineTool({
     "Find projects in Sentry.",
     "",
     "Use this tool when you need to:",
-    "- View all projects in a Sentry organization",
+    "- View projects in a Sentry organization",
     "- Find a project's slug to aid other tool requests",
+    "- Search for specific projects by name or slug",
+    "",
+    `Returns up to ${RESULT_LIMIT} results. If you hit this limit, use the query parameter to narrow down results.`,
   ].join("\n"),
   inputSchema: {
     organizationSlug: ParamOrganizationSlug,
     regionUrl: ParamRegionUrl.optional(),
+    query: ParamSearchQuery.optional(),
   },
   async handler(params, context: ServerContext) {
     const apiService = apiServiceFromContext(context, {
@@ -33,13 +43,29 @@ export default defineTool({
 
     setTag("organization.slug", organizationSlug);
 
-    const projects = await apiService.listProjects(organizationSlug);
+    const projects = await apiService.listProjects(organizationSlug, {
+      query: params.query,
+    });
+
     let output = `# Projects in **${organizationSlug}**\n\n`;
+
+    if (params.query) {
+      output += `**Search query:** "${params.query}"\n\n`;
+    }
+
     if (projects.length === 0) {
-      output += "No projects found.\n";
+      output += params.query
+        ? `No projects found matching "${params.query}".\n`
+        : "No projects found.\n";
       return output;
     }
+
     output += projects.map((project) => `- **${project.slug}**\n`).join("");
+
+    if (projects.length === RESULT_LIMIT) {
+      output += `\n---\n\n**Note:** Showing ${RESULT_LIMIT} results (maximum). There may be more projects available. Use the \`query\` parameter to search for specific projects.`;
+    }
+
     return output;
   },
 });

packages/mcp-server/src/tools/find-teams.ts

@@ -3,7 +3,13 @@ import { defineTool } from "../internal/tool-helpers/define";
 import { apiServiceFromContext } from "../internal/tool-helpers/api";
 import { UserInputError } from "../errors";
 import type { ServerContext } from "../types";
-import { ParamOrganizationSlug, ParamRegionUrl } from "../schema";
+import {
+  ParamOrganizationSlug,
+  ParamRegionUrl,
+  ParamSearchQuery,
+} from "../schema";
+
+const RESULT_LIMIT = 25;
 
 export default defineTool({
   name: "find_teams",
@@ -12,12 +18,16 @@ export default defineTool({
     "Find teams in an organization in Sentry.",
     "",
     "Use this tool when you need to:",
-    "- View all teams in a Sentry organization",
+    "- View teams in a Sentry organization",
     "- Find a team's slug to aid other tool requests",
+    "- Search for specific teams by name or slug",
+    "",
+    `Returns up to ${RESULT_LIMIT} results. If you hit this limit, use the query parameter to narrow down results.`,
   ].join("\n"),
   inputSchema: {
     organizationSlug: ParamOrganizationSlug,
     regionUrl: ParamRegionUrl.optional(),
+    query: ParamSearchQuery.optional(),
   },
   async handler(params, context: ServerContext) {
     const apiService = apiServiceFromContext(context, {
@@ -33,13 +43,29 @@ export default defineTool({
 
     setTag("organization.slug", organizationSlug);
 
-    const teams = await apiService.listTeams(organizationSlug);
+    const teams = await apiService.listTeams(organizationSlug, {
+      query: params.query,
+    });
+
     let output = `# Teams in **${organizationSlug}**\n\n`;
+
+    if (params.query) {
+      output += `**Search query:** "${params.query}"\n\n`;
+    }
+
     if (teams.length === 0) {
-      output += "No teams found.\n";
+      output += params.query
+        ? `No teams found matching "${params.query}".\n`
+        : "No teams found.\n";
       return output;
     }
+
     output += teams.map((team) => `- ${team.slug}\n`).join("");
+
+    if (teams.length === RESULT_LIMIT) {
+      output += `\n---\n\n**Note:** Showing ${RESULT_LIMIT} results (maximum). There may be more teams available. Use the \`query\` parameter to search for specific teams.`;
+    }
+
     return output;
   },
 });