feat(resource): Add AI conversation retrieval (#993)

Expose AI conversations through get_sentry_resource so agents can fetch
a readable conversation transcript from a conversation ID or Explore
URL. The response is organized by turns, with compact metadata, grouped
tool calls, parsed tool inputs, and a concise structured artifact for
downstream use.

**Conversation Resource Support**

get_sentry_resource now accepts resourceType='ai_conversation' and
resolves /explore/conversations/{conversationId}/ URLs without adding
another public MCP tool.

**Turn-Based Transcript Rendering**

AI client spans are rendered as grouped turns with user, assistant, and
tool sections. Tool calls are associated with the AI turn that triggered
them, including repeated messages and trailing tools after the final AI
client span.

**API Shape Validation**

The Sentry API client now calls
/api/0/organizations/{org}/ai-conversations/{conversation_id}/, handles
cursor pagination, and validates the flat span row shape returned by the
endpoint.

Fixes GH-990

---------

Co-authored-by: Codex <codex@openai.com>

Author: dcramer

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

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import {
   getContinuousProfileUrl as getContinuousProfileUrlUtil,
+  getAIConversationUrl as getAIConversationUrlUtil,
   getIssueUrl as getIssueUrlUtil,
   getMonitorUrl as getMonitorUrlUtil,
   getProfileUrl as getProfileUrlUtil,
@@ -53,6 +54,7 @@ import {
   ReplayListResponseSchema,
   ReplayIdsByResourceSchema,
   ReplayRecordingSegmentsSchema,
+  AIConversationSpanListSchema,
 } from "./schema";
 import { ConfigurationError } from "../errors";
 import { createApiError, ApiNotFoundError, ApiValidationError } from "./errors";
@@ -86,6 +88,7 @@ import type {
   ReplayDetails,
   ReplayList,
   ReplayRecordingSegments,
+  AIConversationSpanList,
 } from "./types";
 // TODO: this is shared - so ideally, for safety, it uses @sentry/core, but currently
 // logger isnt exposed (or rather, it is, but its not the right logger)
@@ -103,6 +106,25 @@ const NETWORK_ERROR_MESSAGES: Record<string, string> = {
   ECONNRESET: "Connection reset. Try again in a moment.",
 };
 
+function getNextCursor(linkHeader: string | null): string | null {
+  if (!linkHeader) {
+    return null;
+  }
+
+  for (const link of linkHeader.split(",")) {
+    if (!link.includes('rel="next"') || !link.includes('results="true"')) {
+      continue;
+    }
+
+    const cursorMatch = link.match(/cursor="([^"]+)"/);
+    if (cursorMatch?.[1]) {
+      return cursorMatch[1];
+    }
+  }
+
+  return null;
+}
+
 /**
  * Custom error class for Sentry API responses.
  *
@@ -645,6 +667,18 @@ export class SentryApiService {
     );
   }
 
+  getAIConversationUrl(
+    organizationSlug: string,
+    conversationId: string,
+  ): string {
+    return getAIConversationUrlUtil(
+      this.host,
+      organizationSlug,
+      conversationId,
+      this.protocol,
+    );
+  }
+
   getProfileUrl(
     organizationSlug: string,
     projectSlug: string,
@@ -2871,6 +2905,56 @@ export class SentryApiService {
     return TraceSchema.parse(body);
   }
 
+  async getAIConversation(
+    {
+      organizationSlug,
+      conversationId,
+      project = "-1",
+      statsPeriod = "30d",
+      perPage = 1000,
+      maxPages = 10,
+    }: {
+      organizationSlug: string;
+      conversationId: string;
+      project?: string | string[];
+      statsPeriod?: string;
+      perPage?: number;
+      maxPages?: number;
+    },
+    opts?: RequestOptions,
+  ): Promise<AIConversationSpanList> {
+    const spans: AIConversationSpanList = [];
+    let cursor: string | null = null;
+
+    for (let page = 0; page < maxPages; page++) {
+      const queryParams = new URLSearchParams();
+      queryParams.set("per_page", String(perPage));
+      queryParams.set("statsPeriod", statsPeriod);
+      const projects = Array.isArray(project) ? project : [project];
+      for (const projectId of projects) {
+        queryParams.append("project", projectId);
+      }
+      if (cursor) {
+        queryParams.set("cursor", cursor);
+      }
+
+      const response = await this.request(
+        `/organizations/${organizationSlug}/ai-conversations/${encodeURIComponent(conversationId)}/?${queryParams.toString()}`,
+        undefined,
+        opts,
+      );
+      const body = await this.parseJsonResponse(response);
+      spans.push(...AIConversationSpanListSchema.parse(body));
+
+      cursor = getNextCursor(response.headers.get("link"));
+      if (!cursor) {
+        break;
+      }
+    }
+
+    return spans;
+  }
+
   /**
    * Retrieves flamegraph data for a transaction.
    *

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

@@ -1049,6 +1049,58 @@ export const TraceSchema = z.array(
   z.union([TraceSpanSchema, TraceIssueSchema]),
 );
 
+const NullableStringOrNumberSchema = z
+  .union([z.string(), z.number()])
+  .nullable()
+  .optional();
+const NullableOptionalStringSchema = z
+  .string()
+  .nullable()
+  .optional()
+  .transform((value) => value ?? undefined);
+
+export const AIConversationSpanSchema = z
+  .object({
+    "gen_ai.conversation.id": z.string(),
+    span_id: z.string(),
+    trace: z.string(),
+    parent_span: z.string().nullable().optional(),
+    "precise.start_ts": z.number(),
+    "precise.finish_ts": z.number(),
+    project: z.string(),
+    "project.id": z.union([z.string(), z.number()]),
+    "span.name": NullableOptionalStringSchema,
+    "span.status": NullableOptionalStringSchema,
+    "span.op": NullableOptionalStringSchema,
+    "span.description": NullableOptionalStringSchema,
+    "span.duration": z.number().optional(),
+    transaction: NullableOptionalStringSchema,
+    is_transaction: z.boolean().optional(),
+    "gen_ai.cost.total_tokens": NullableStringOrNumberSchema,
+    "gen_ai.operation.type": NullableOptionalStringSchema,
+    "gen_ai.input.messages": NullableOptionalStringSchema,
+    "gen_ai.output.messages": NullableOptionalStringSchema,
+    "gen_ai.system_instructions": NullableOptionalStringSchema,
+    "gen_ai.tool.definitions": NullableOptionalStringSchema,
+    "gen_ai.request.messages": NullableOptionalStringSchema,
+    "gen_ai.response.object": NullableOptionalStringSchema,
+    "gen_ai.response.text": NullableOptionalStringSchema,
+    "gen_ai.tool.name": NullableOptionalStringSchema,
+    "gen_ai.tool.call.arguments": NullableOptionalStringSchema,
+    "gen_ai.tool.input": NullableOptionalStringSchema,
+    "gen_ai.usage.total_tokens": NullableStringOrNumberSchema,
+    "gen_ai.request.model": NullableOptionalStringSchema,
+    "gen_ai.response.model": NullableOptionalStringSchema,
+    "gen_ai.agent.name": NullableOptionalStringSchema,
+    "user.id": NullableOptionalStringSchema,
+    "user.email": NullableOptionalStringSchema,
+    "user.username": NullableOptionalStringSchema,
+    "user.ip": NullableOptionalStringSchema,
+  })
+  .passthrough();
+
+export const AIConversationSpanListSchema = z.array(AIConversationSpanSchema);
+
 /**
  * Schema for individual frames in a flamegraph.
  *

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

@@ -41,6 +41,8 @@
 import type { z } from "zod";
 import type {
   AssignedToSchema,
+  AIConversationSpanListSchema,
+  AIConversationSpanSchema,
   AutofixRunSchema,
   AutofixRunStateSchema,
   ClientKeyListSchema,
@@ -138,6 +140,10 @@ export type TraceMeta = z.infer<typeof TraceMetaSchema>;
 export type TraceSpan = z.infer<typeof TraceSpanSchema>;
 export type TraceIssue = z.infer<typeof TraceIssueSchema>;
 export type Trace = z.infer<typeof TraceSchema>;
+export type AIConversationSpan = z.infer<typeof AIConversationSpanSchema>;
+export type AIConversationSpanList = z.infer<
+  typeof AIConversationSpanListSchema
+>;
 
 // Profile types
 export type Flamegraph = z.infer<typeof FlamegraphSchema>;

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

@@ -232,6 +232,43 @@ describe("parseSentryUrl", () => {
     });
   });
 
+  describe("AI conversation URLs", () => {
+    it("parses AI conversation URL with subdomain", () => {
+      expect(
+        parseSentryUrl(
+          "https://my-org.sentry.io/explore/conversations/conv-123/",
+        ),
+      ).toMatchInlineSnapshot(`
+        {
+          "conversationId": "conv-123",
+          "organizationSlug": "my-org",
+          "type": "ai_conversation",
+        }
+      `);
+    });
+
+    it("parses AI conversation URL with organizations path", () => {
+      expect(
+        parseSentryUrl(
+          "https://sentry.io/organizations/my-org/explore/conversations/conv-123/",
+        ),
+      ).toMatchInlineSnapshot(`
+        {
+          "conversationId": "conv-123",
+          "organizationSlug": "my-org",
+          "type": "ai_conversation",
+        }
+      `);
+    });
+
+    it("does not parse unrelated conversations path segments", () => {
+      const result = parseSentryUrl(
+        "https://sentry.io/organizations/my-org/settings/projects/conversations/keys/",
+      );
+      expect(result.type).toBe("unknown");
+    });
+  });
+
   describe("replay URLs", () => {
     it("parses canonical replay URL with subdomain", () => {
       expect(

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

@@ -15,6 +15,7 @@ export type SentryResourceType =
   | "issue"
   | "trace"
   | "profile"
+  | "ai_conversation"
   | "event"
   | "replay"
   | "monitor"
@@ -35,6 +36,8 @@ export interface ParsedSentryUrl {
   issueId?: string;
   /** Trace ID (for trace URLs) */
   traceId?: string;
+  /** AI conversation ID (for Explore conversation URLs) */
+  conversationId?: string;
   /** Span ID (for trace URLs with span focus, from query param) */
   spanId?: string;
   /** Event ID (for event URLs) */
@@ -72,6 +75,7 @@ export interface ParsedSentryUrl {
  * - Trace: `/explore/traces/trace/{traceId}` or `/performance/trace/{traceId}`
  * - Profile: `/explore/profiling/profile/{project}/{profileId}/flamegraph/`
  * - Continuous profile: `/explore/profiling/profile/{project}/flamegraph/` with query params
+ * - AI conversation: `/explore/conversations/{conversationId}/`
  * - Replay: `/explore/replays/{replayId}/` or `/replays/{replayId}/`
  * - Monitor: `/crons/{monitorSlug}/` or `/monitors/{monitorSlug}/`
  * - Release: `/releases/{version}/`
@@ -189,6 +193,28 @@ function extractOrganizationSlug(parsedUrl: URL, pathParts: string[]): string {
   );
 }
 
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function extractPathGroup(
+  pathParts: string[],
+  patterns: RegExp[],
+  groupName: string,
+): string | undefined {
+  const path = pathParts.join("/");
+
+  for (const pattern of patterns) {
+    const match = pattern.exec(path);
+    const value = match?.groups?.[groupName];
+    if (value) {
+      return value;
+    }
+  }
+
+  return undefined;
+}
+
 /**
  * Identifies the resource type and extracts relevant identifiers.
  */
@@ -222,6 +248,26 @@ function identifyResource(
     };
   }
 
+  // AI conversation URL: /explore/conversations/{conversationId}/
+  const conversationId = extractPathGroup(
+    pathParts,
+    [
+      /^explore\/conversations\/(?<conversationId>[^/]+)$/,
+      /^organizations\/[^/]+\/explore\/conversations\/(?<conversationId>[^/]+)$/,
+      new RegExp(
+        `^${escapeRegex(organizationSlug)}\\/explore\\/conversations\\/(?<conversationId>[^/]+)$`,
+      ),
+    ],
+    "conversationId",
+  );
+  if (conversationId) {
+    return {
+      type: "ai_conversation",
+      organizationSlug,
+      conversationId,
+    };
+  }
+
   // Replay URL: /explore/replays/{replayId}/ or /replays/{replayId}/
   const replaysIndex = pathParts.indexOf("replays");
   if (replaysIndex !== -1) {