feat(mcp): Expand profile and replay event support (#905)

Expand profile, replay, and metrics-adjacent MCP coverage

This adds concrete profile detail support for transaction profiles and
continuous profiles, routes profile URLs through `get_sentry_resource`,
and exposes profiles through the existing `list_events` and
`search_events` surfaces so profile queries have both discovery and
detail paths.

It also aligns replay detail output with upstream replay schemas, makes
metrics output point to trace drill-downs instead of inventing a
separate detail surface, and fixes follow-up issues in profile
formatting and explorer-link generation so profile search results
round-trip into Sentry correctly.

I kept this within the existing public tool surface rather than adding
more top-level tools because the MCP server is already above the
preferred tool-count budget. The regression coverage focuses on the
changed behavior, including hotspot counting, user-code filtering,
profile detail link generation, and grouped profile explorer URLs.

---------

Co-authored-by: Codex GPT-5 <noreply@openai.com>

Author: dcramer

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

@@ -1332,5 +1332,34 @@ describe("API query builders", () => {
         ]);
       });
     });
+
+    describe("profiles page URLs", () => {
+      it("should preserve grouped profile field selection", () => {
+        const apiService = new SentryApiService({ host: "sentry.io" });
+
+        const url = apiService.getEventsExplorerUrl(
+          "my-org",
+          "",
+          "123456",
+          "profiles",
+          ["release", "count()"],
+          "-count()",
+          ["count()"],
+          ["release"],
+          "7d",
+        );
+
+        const parsedUrl = new URL(url);
+
+        expect(parsedUrl.pathname).toBe("/explore/profiling/");
+        expect(parsedUrl.searchParams.get("project")).toBe("123456");
+        expect(parsedUrl.searchParams.get("statsPeriod")).toBe("7d");
+        expect(parsedUrl.searchParams.get("sort")).toBe("-count()");
+        expect(parsedUrl.searchParams.getAll("field")).toEqual([
+          "release",
+          "count()",
+        ]);
+      });
+    });
   });
 });

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

@@ -1,6 +1,9 @@
 import { z } from "zod";
 import {
+  getContinuousProfileUrl as getContinuousProfileUrlUtil,
   getIssueUrl as getIssueUrlUtil,
+  getProfileUrl as getProfileUrlUtil,
+  getProfilingExplorerUrl,
   getReplayUrl as getReplayUrlUtil,
   getReplaysSearchUrl as getReplaysSearchUrlUtil,
   getTraceMetricsExploreUrl,
@@ -10,6 +13,7 @@ import {
 } from "../utils/url-utils";
 import {
   isMetricsDataset,
+  isProfilesDataset,
   normalizeEventsDataset,
   type EventsDataset,
 } from "../utils/events-datasets";
@@ -42,6 +46,7 @@ import {
   UserRegionsSchema,
   FlamegraphSchema,
   ProfileChunkResponseSchema,
+  TransactionProfileSchema,
   ReplayDetailsSchema,
   ReplayListResponseSchema,
   ReplayIdsByResourceSchema,
@@ -74,6 +79,7 @@ import type {
   User,
   Flamegraph,
   ProfileChunk,
+  TransactionProfile,
   ReplayDetails,
   ReplayList,
   ReplayRecordingSegments,
@@ -535,6 +541,36 @@ export class SentryApiService {
     return getReplayUrlUtil(this.host, organizationSlug, replayId);
   }
 
+  getProfileUrl(
+    organizationSlug: string,
+    projectSlug: string,
+    profileId: string,
+  ): string {
+    return getProfileUrlUtil(
+      this.host,
+      organizationSlug,
+      projectSlug,
+      profileId,
+    );
+  }
+
+  getContinuousProfileUrl(
+    organizationSlug: string,
+    projectSlug: string,
+    options: {
+      profilerId: string;
+      start: string;
+      end: string;
+    },
+  ): string {
+    return getContinuousProfileUrlUtil(
+      this.host,
+      organizationSlug,
+      projectSlug,
+      options,
+    );
+  }
+
   getReplaysSearchUrl(
     organizationSlug: string,
     options: Parameters<typeof getReplaysSearchUrlUtil>[2] = {},
@@ -867,6 +903,20 @@ export class SentryApiService {
       });
     }
 
+    if (isProfilesDataset(dataset)) {
+      return getProfilingExplorerUrl(this.host, organizationSlug, {
+        query,
+        projectId,
+        fields,
+        sort,
+        statsPeriod,
+        start,
+        end,
+        aggregateFunctions,
+        groupByFields,
+      });
+    }
+
     // Route to modern EAP API (spans and logs)
     return this.buildEapUrl({
       organizationSlug,
@@ -2273,7 +2323,7 @@ export class SentryApiService {
     fields: string[];
     limit: number;
     projectId?: string;
-    dataset?: "errors" | "tracemetrics";
+    dataset?: "errors" | "tracemetrics" | "profiles";
     statsPeriod?: string;
     start?: string;
     end?: string;
@@ -2435,7 +2485,8 @@ export class SentryApiService {
 
     if (
       normalizedDataset === "errors" ||
-      normalizedDataset === "tracemetrics"
+      normalizedDataset === "tracemetrics" ||
+      normalizedDataset === "profiles"
     ) {
       // Use Discover API query builder
       queryParams = this.buildDiscoverApiQuery({
@@ -2676,6 +2727,23 @@ export class SentryApiService {
     return FlamegraphSchema.parse(body);
   }
 
+  async getTransactionProfile(
+    {
+      organizationSlug,
+      projectSlugOrId,
+      profileId,
+    }: {
+      organizationSlug: string;
+      projectSlugOrId: string | number;
+      profileId: string;
+    },
+    opts?: RequestOptions,
+  ): Promise<TransactionProfile> {
+    const path = `/projects/${organizationSlug}/${projectSlugOrId}/profiling/profiles/${profileId}/`;
+    const body = await this.requestJSON(path, undefined, opts);
+    return TransactionProfileSchema.parse(body);
+  }
+
   /**
    * Retrieves raw profile chunk data for detailed analysis.
    *

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

@@ -1140,3 +1140,73 @@ export const ProfileChunkResponseSchema = z
     chunks: z.array(ProfileChunkSchema),
   })
   .passthrough();
+
+const ProfileReleaseSchema = z
+  .union([
+    z.string(),
+    z
+      .object({
+        version: z.string(),
+      })
+      .passthrough(),
+    z.null(),
+  ])
+  .optional();
+
+export const TransactionProfileSchema = z
+  .object({
+    event_id: z.string().optional(),
+    profile_id: z.string().optional(),
+    profiler_id: z.string().optional(),
+    environment: z.string().nullable().optional(),
+    platform: z.string(),
+    release: ProfileReleaseSchema,
+    version: z.union([z.string(), z.number()]).transform(String).optional(),
+    profile: ProfileChunkSchema.shape.profile,
+    transaction: z
+      .object({
+        name: z.string().optional(),
+        trace_id: z.string().optional(),
+        id: z.string().optional(),
+        active_thread_id: z.string().optional(),
+        relative_start_ns: z
+          .union([z.string(), z.number()])
+          .transform((value) => Number(value))
+          .optional(),
+        relative_end_ns: z
+          .union([z.string(), z.number()])
+          .transform((value) => Number(value))
+          .optional(),
+      })
+      .passthrough()
+      .optional(),
+    device: z
+      .object({
+        classification: z.string().nullable().optional(),
+        manufacturer: z.string().nullable().optional(),
+        locale: z.string().nullable().optional(),
+        model: z.string().nullable().optional(),
+        arch: z.string().nullable().optional(),
+      })
+      .passthrough()
+      .nullable()
+      .optional(),
+    os: z
+      .object({
+        name: z.string().nullable().optional(),
+        version: z.string().nullable().optional(),
+        build_number: z.string().nullable().optional(),
+      })
+      .passthrough()
+      .nullable()
+      .optional(),
+    client_sdk: z
+      .object({
+        name: z.string().nullable().optional(),
+        version: z.string().nullable().optional(),
+      })
+      .passthrough()
+      .nullable()
+      .optional(),
+  })
+  .passthrough();

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

@@ -83,6 +83,7 @@ import type {
   FlamegraphProfileMetadataSchema,
   ProfileChunkSchema,
   ProfileChunkResponseSchema,
+  TransactionProfileSchema,
   ProfileFrameSchema,
   ProfileSampleSchema,
 } from "./schema";
@@ -147,6 +148,7 @@ export type FlamegraphProfileMetadata = z.infer<
 >;
 export type ProfileChunk = z.infer<typeof ProfileChunkSchema>;
 export type ProfileChunkResponse = z.infer<typeof ProfileChunkResponseSchema>;
+export type TransactionProfile = z.infer<typeof TransactionProfileSchema>;
 export type ProfileFrame = z.infer<typeof ProfileFrameSchema>;
 export type ProfileSample = z.infer<typeof ProfileSampleSchema>;
 

packages/mcp-core/src/internal/issue-helpers.test.ts

@@ -168,6 +168,26 @@ describe("parseIssueParams", () => {
     });
   });
 
+  it("should allow matching organizationSlug with issueUrl", () => {
+    expect(
+      parseIssueParams({
+        organizationSlug: "sentry",
+        issueUrl: "https://sentry.io/sentry/issues/123",
+      }),
+    ).toEqual({ organizationSlug: "sentry", issueId: "123" });
+  });
+
+  it("should reject issueUrl outside the active organization constraint", () => {
+    expect(() =>
+      parseIssueParams({
+        organizationSlug: "other-org",
+        issueUrl: "https://sentry.io/sentry/issues/123",
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[UserInputError: Issue URL is outside the active organization constraint. Expected organization "other-org" but got "sentry".]`,
+    );
+  });
+
   it("should throw if neither issueId nor issueUrl is provided", () => {
     expect(() =>
       parseIssueParams({ organizationSlug: "foo" }),

packages/mcp-core/src/internal/issue-helpers.ts

@@ -8,6 +8,7 @@
  */
 
 import { UserInputError } from "../errors";
+import { resolveScopedOrganizationSlug } from "./url-scope";
 
 /**
  * Extracts the Sentry issue ID and organization slug from a full URL
@@ -141,7 +142,11 @@ export function parseIssueParams({
       );
     }
     return {
-      ...resolved,
+      organizationSlug: resolveScopedOrganizationSlug({
+        resourceLabel: "Issue",
+        scopedOrganizationSlug: organizationSlug,
+        urlOrganizationSlug: resolved.organizationSlug,
+      }),
       issueId: parseIssueId(resolved.issueId),
     };
   }

packages/mcp-core/src/internal/tool-helpers/issue.ts

@@ -2,9 +2,58 @@
  * Re-export of issue parsing utilities for tool modules.
  * These utilities handle flexible input formats for Sentry issues.
  */
+import type { SentryApiService } from "../../api-client";
+import type { Issue } from "../../api-client/types";
+import { assertScopedProjectSlug } from "../url-scope";
+
 export { parseIssueParams } from "../../internal/issue-helpers";
 
 /**
  * Re-export of issue formatting utilities for tool modules.
  */
 export { formatIssueOutput } from "../../internal/formatting";
+
+export function assertIssueWithinProjectConstraint({
+  issue,
+  projectSlug,
+  resourceLabel = "Issue",
+}: {
+  issue: Pick<Issue, "project">;
+  projectSlug?: string | null;
+  resourceLabel?: string;
+}): void {
+  assertScopedProjectSlug({
+    resourceLabel,
+    scopedProjectSlug: projectSlug,
+    actualProjectSlug: issue.project.slug,
+  });
+}
+
+export async function ensureIssueWithinProjectConstraint({
+  apiService,
+  organizationSlug,
+  issueId,
+  projectSlug,
+  resourceLabel = "Issue",
+}: {
+  apiService: SentryApiService;
+  organizationSlug: string;
+  issueId: string;
+  projectSlug?: string | null;
+  resourceLabel?: string;
+}): Promise<void> {
+  if (!projectSlug) {
+    return;
+  }
+
+  const issue = await apiService.getIssue({
+    organizationSlug,
+    issueId,
+  });
+
+  assertIssueWithinProjectConstraint({
+    issue,
+    projectSlug,
+    resourceLabel,
+  });
+}