feat(mcp): Add event stacktrace tool (#1116)

Issue details now surface a compact thread table only when the selected
event has multiple threads, with a hint to fetch a full stacktrace
through the catalog-only `get_event_stacktrace` tool. The new tool
accepts an optional `thread` selector by numeric thread ID or exact
thread name; when omitted, it mirrors Sentry UI selection by choosing
the first crashed thread, then the first thread with a stacktrace, then
the first thread.

The event stacktrace markdown uses the `Event Stacktrace` label and
keeps the stacktrace output focused on actionable selection and frame
details, omitting low-value frame-count/system-frame metadata. Inline
snapshots cover the issue-details hint, selector behavior, default
selection, and rendered tool output, and generated tool definitions are
refreshed.

Fixes #1114

---------

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

Author: dcramer

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

@@ -809,18 +809,28 @@ export const MessageEntrySchema = z
   })
   .partial();
 
+const StacktraceSchema = z
+  .object({
+    frames: z.array(FrameInterface),
+    framesOmitted: z.array(z.unknown()).nullable().optional(),
+    registers: z.record(z.unknown()).nullable().optional(),
+    hasSystemFrames: z.boolean().nullable().optional(),
+  })
+  .partial()
+  .extend({
+    frames: z.array(FrameInterface),
+  });
+
 export const ThreadEntrySchema = z
   .object({
-    id: z.number().nullable(),
+    id: z.union([z.number(), z.string()]).nullable(),
     name: z.string().nullable(),
     current: z.boolean().nullable(),
     crashed: z.boolean().nullable(),
     state: z.string().nullable(),
-    stacktrace: z
-      .object({
-        frames: z.array(FrameInterface),
-      })
-      .nullable(),
+    heldLocks: z.record(z.unknown()).nullable().optional(),
+    stacktrace: StacktraceSchema.nullable(),
+    rawStacktrace: StacktraceSchema.nullable().optional(),
   })
   .partial();
 

packages/mcp-core/src/internal/formatting.ts

@@ -16,8 +16,9 @@ import type {
   MessageEntrySchema,
   RequestEntrySchema,
   SentryApiService,
-  ThreadsEntrySchema,
+  ThreadEntrySchema,
 } from "../api-client";
+import { ThreadsEntrySchema } from "../api-client";
 import type {
   AutofixRunState,
   Event,
@@ -229,6 +230,9 @@ export function formatEventOutput(
     (e) => e.type === "exception",
   );
   const threadsEntry = eventToRender.entries.find((e) => e.type === "threads");
+  const threadsData = threadsEntry
+    ? parseThreadsEntryData(threadsEntry.data)
+    : undefined;
   const requestEntry = eventToRender.entries.find((e) => e.type === "request");
   const spansEntry = eventToRender.entries.find((e) => e.type === "spans");
   const cspEntry = eventToRender.entries.find((e) => e.type === "csp");
@@ -247,11 +251,13 @@ export function formatEventOutput(
       eventToRender,
       exceptionEntry.data as z.infer<typeof ErrorEntrySchema>,
     );
-  } else if (threadsEntry) {
-    output += formatThreadsInterfaceOutput(
-      eventToRender,
-      threadsEntry.data as z.infer<typeof ThreadsEntrySchema>,
-    );
+  } else if (threadsData) {
+    output += formatThreadsInterfaceOutput(eventToRender, threadsData);
+  }
+
+  if (threadsData?.values && threadsData.values.length > 1) {
+    output += formatThreadList(threadsData.values);
+    output += "\n";
   }
 
   // Request info (if HTTP error)
@@ -609,6 +615,160 @@ function formatThreadsInterfaceOutput(
   return parts.join("\n");
 }
 
+function getThreadDisplayValue(
+  value: string | number | boolean | null | undefined,
+): string {
+  if (value === null || value === undefined || value === "") {
+    return "-";
+  }
+  return String(value);
+}
+
+function getThreadFlags(thread: z.infer<typeof ThreadEntrySchema>): string {
+  const flags: string[] = [];
+  if (thread.crashed) {
+    flags.push("crashed");
+  }
+  if (thread.current) {
+    flags.push("current");
+  }
+  return flags.length > 0 ? flags.join(", ") : "-";
+}
+
+function formatThreadList(
+  threads: z.infer<typeof ThreadEntrySchema>[],
+): string {
+  return [
+    "### Threads",
+    "",
+    `Found ${threads.length} thread${threads.length === 1 ? "" : "s"} in this event.`,
+    "",
+    ...formatThreadTable(threads),
+    "",
+  ].join("\n");
+}
+
+function formatThreadTable(
+  threads: z.infer<typeof ThreadEntrySchema>[],
+): string[] {
+  return [
+    "| Thread ID | Name | State | Flags | Frames |",
+    "| --- | --- | --- | --- | ---: |",
+    ...threads.map((thread) => {
+      const frameCount = thread.stacktrace?.frames?.length ?? 0;
+      return `| ${getThreadDisplayValue(thread.id)} | ${getThreadDisplayValue(thread.name)} | ${getThreadDisplayValue(thread.state)} | ${getThreadFlags(thread)} | ${frameCount} |`;
+    }),
+  ];
+}
+
+export function formatAvailableThreadList(
+  threads: z.infer<typeof ThreadEntrySchema>[],
+): string {
+  return [
+    "## Available Threads",
+    "",
+    ...formatThreadTable(threads),
+    "",
+    "Pass `thread` as a numeric Thread ID or exact thread Name.",
+  ].join("\n");
+}
+
+function parseThreadsEntryData(
+  data: unknown,
+): z.infer<typeof ThreadsEntrySchema> | undefined {
+  const result = ThreadsEntrySchema.safeParse(data);
+  return result.success ? result.data : undefined;
+}
+
+/**
+ * Formats the selected thread stacktrace using the same frame rendering
+ * conventions as issue event details.
+ */
+export function formatThreadStacktraceOutput({
+  event,
+  thread,
+  selectionReason,
+}: {
+  event: Event;
+  thread: z.infer<typeof ThreadEntrySchema>;
+  selectionReason: string;
+}): string {
+  const parts: string[] = [];
+
+  parts.push("## Selected Thread");
+  parts.push("");
+  parts.push(`**Selection**: ${selectionReason}`);
+  parts.push(`**Thread ID**: ${getThreadDisplayValue(thread.id)}`);
+  parts.push(`**Name**: ${getThreadDisplayValue(thread.name)}`);
+  parts.push(`**State**: ${getThreadDisplayValue(thread.state)}`);
+  parts.push(`**Crashed**: ${getThreadDisplayValue(thread.crashed)}`);
+  parts.push(`**Current**: ${getThreadDisplayValue(thread.current)}`);
+  parts.push("");
+
+  const frames = thread.stacktrace?.frames;
+  if (!frames || frames.length === 0) {
+    parts.push("No stacktrace is available for the selected thread.");
+    parts.push("");
+    return parts.join("\n");
+  }
+
+  parts.push("## Stacktrace");
+  parts.push("");
+  const framesOmitted = formatFramesOmitted(thread.stacktrace?.framesOmitted);
+  if (framesOmitted) {
+    parts.push(`**Frames Omitted**: ${framesOmitted}`);
+    parts.push("");
+  }
+
+  const firstInAppFrame = findFirstInAppFrame(frames);
+  if (
+    firstInAppFrame &&
+    (firstInAppFrame.context?.length || firstInAppFrame.vars)
+  ) {
+    parts.push(renderEnhancedFrame(firstInAppFrame, event));
+    parts.push("");
+    parts.push("**Full Stacktrace:**");
+    parts.push("────────────────");
+  } else {
+    parts.push("**Full Stacktrace:**");
+  }
+
+  parts.push("```");
+  parts.push(
+    frames
+      .map((frame) => {
+        const header = formatFrameHeader(frame, undefined, event.platform);
+        const context = renderInlineContext(frame);
+        return `${header}${context}`;
+      })
+      .join("\n"),
+  );
+  parts.push("```");
+  parts.push("");
+
+  return parts.join("\n");
+}
+
+function formatFramesOmitted(
+  framesOmitted: unknown[] | null | undefined,
+): string | null {
+  if (!framesOmitted?.length) {
+    return null;
+  }
+
+  const [firstOmitted, lastOmitted] = framesOmitted;
+  if (
+    typeof firstOmitted === "number" &&
+    typeof lastOmitted === "number" &&
+    Number.isFinite(firstOmitted) &&
+    Number.isFinite(lastOmitted)
+  ) {
+    return String(Math.max(0, lastOmitted - firstOmitted));
+  }
+
+  return null;
+}
+
 /**
  * Renders surrounding source code context for a stack frame.
  * Shows a window of code lines around the error line with visual indicators.
@@ -1882,6 +2042,33 @@ export function formatIssueOutput({
     fallbackInstruction: "Issue event search is not available in this session",
   });
   output += `- Issue event search: ${issueEventSearchInstruction}\n`;
+  const hasMultipleThreads = event.entries?.some((entry) => {
+    if (entry.type !== "threads") {
+      return false;
+    }
+    const threadsData = parseThreadsEntryData(entry.data);
+    return Boolean(threadsData?.values && threadsData.values.length > 1);
+  });
+  if (hasMultipleThreads) {
+    const stacktraceInstruction = formatToolCallInstruction({
+      toolName: "get_event_stacktrace",
+      arguments: {
+        organizationSlug,
+        issueId: issue.shortId,
+        eventId: event.id,
+        thread: "thread name or numeric thread ID",
+      },
+      experimentalMode: experimentalMode ?? false,
+      availableToolNames,
+      directToolNames,
+      fallbackInstruction: "",
+      purpose:
+        "to fetch a full thread stacktrace by numeric Thread ID or exact thread Name. Omit `thread` to use Sentry's default selected thread",
+    });
+    if (stacktraceInstruction) {
+      output += `- Thread stacktrace lookup: ${stacktraceInstruction}\n`;
+    }
+  }
   if (traceId) {
     const traceDetailsInstruction = formatToolCallInstruction({
       toolName: "get_sentry_resource",

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

@@ -835,6 +835,7 @@ describe("buildServer", () => {
       expect(toolNames).not.toContain("create_project");
       expect(toolNames).not.toContain("find_releases");
       expect(toolNames).not.toContain("get_event_attachment");
+      expect(toolNames).not.toContain("get_event_stacktrace");
 
       const result = await callRegisteredTool(server, "search_sentry_tools", {
         query: "create project",
@@ -1065,18 +1066,19 @@ describe("buildServer", () => {
 
       const toolNames = getRegisteredToolNames(server);
       expect(toolNames).not.toContain("get_issue_details");
+      expect(toolNames).not.toContain("get_event_stacktrace");
 
       const result = await callRegisteredTool(server, "search_sentry_tools", {
-        query: "issue details",
+        query: "event stacktrace",
         limit: 5,
       });
       const payload = getStructuredContent<{
         results: Array<{ name: string }>;
       }>(result);
 
-      expect(payload.results.map((tool) => tool.name)).toContain(
-        "get_issue_details",
-      );
+      const resultNames = payload.results.map((tool) => tool.name);
+      expect(resultNames).toContain("get_issue_details");
+      expect(resultNames).toContain("get_event_stacktrace");
     });
 
     it("search_sentry_tools includes whoami as a catalog-only foundational tool", async () => {
@@ -1257,6 +1259,27 @@ describe("buildServer", () => {
       );
     });
 
+    it("execute_sentry_tool dispatches to catalog-only event stacktrace", async () => {
+      const server = buildServer({
+        context: baseContext,
+      });
+
+      const toolNames = getRegisteredToolNames(server);
+      expect(toolNames).not.toContain("get_event_stacktrace");
+
+      const result = await callRegisteredTool(server, "execute_sentry_tool", {
+        name: "get_event_stacktrace",
+        arguments: {
+          organizationSlug: "sentry-mcp-evals",
+          issueId: "CLOUDFLARE-MCP-41",
+        },
+      });
+
+      expect(getTextContent(result)).toContain(
+        "# Event Stacktrace in **sentry-mcp-evals**",
+      );
+    });
+
     it("execute_sentry_tool dispatches to catalog-only update_dsn", async () => {
       const server = buildServer({
         context: baseContext,

packages/mcp-core/src/skillDefinitions.json

@@ -5,7 +5,7 @@
     "description": "Read-only access to core Sentry data: issues, events, traces, replays, releases, monitors, profiles, documentation, and project metadata",
     "defaultEnabled": true,
     "order": 1,
-    "toolCount": 30,
+    "toolCount": 31,
     "tools": [
       {
         "name": "find_alert_rules",
@@ -67,6 +67,11 @@
         "description": "Download attachments from a Sentry event.\n\nUse this tool when you need to:\n- Download files attached to a specific event\n- Access screenshots, log files, or other attachments uploaded with an error report\n- Retrieve attachment metadata and download URLs\n\n<examples>\n### Download a specific attachment by ID\n\n```\nget_event_attachment(organizationSlug='my-organization', projectSlug='my-project', eventId='c49541c747cb4d8aa3efb70ca5aba243', attachmentId='12345')\n```\n\n### List all attachments for an event\n\n```\nget_event_attachment(organizationSlug='my-organization', projectSlug='my-project', eventId='c49541c747cb4d8aa3efb70ca5aba243')\n```\n\n</examples>\n\n<hints>\n- If `attachmentId` is provided, the specific attachment will be downloaded as an embedded resource\n- If `attachmentId` is omitted, all attachments for the event will be listed with download information\n- The `projectSlug` is required to identify which project the event belongs to\n</hints>",
         "requiredScopes": ["event:read"]
       },
+      {
+        "name": "get_event_stacktrace",
+        "description": "Get a full thread stacktrace from a specific Sentry event.\n\nUse this tool when you need to:\n- Fetch the full stacktrace for a thread listed in issue details\n- Inspect a non-crashed thread from an event with multiple threads\n- Get Sentry's default selected thread stacktrace when no thread is specified\n\n<examples>\nget_event_stacktrace(organizationSlug='my-org', issueId='PROJECT-123')\nget_event_stacktrace(organizationSlug='my-org', issueId='PROJECT-123', eventId='abc123', thread=259)\nget_event_stacktrace(organizationSlug='my-org', issueId='PROJECT-123', thread='main')\n</examples>\n\n<hints>\n- `thread` is optional. If omitted, this returns the same default thread Sentry selects: first crashed thread, then first thread with a stacktrace, then first thread.\n- Pass `thread` as a numeric Thread ID or exact thread Name from the issue details thread list.\n- If the issue details show only one useful thread, omit `thread`.\n</hints>",
+        "requiredScopes": ["event:read"]
+      },
       {
         "name": "get_issue_activity",
         "description": "Get the activity feed and comments for a Sentry issue.\n\nUse this tool when you need to:\n- Review prior comments before triaging an issue\n- Understand who resolved, ignored, assigned, or commented on an issue\n- See recent issue activity that is not included in `get_issue_details`\n\n<examples>\nget_issue_activity(organizationSlug='my-organization', issueId='PROJECT-123')\nget_issue_activity(issueUrl='https://my-organization.sentry.io/issues/PROJECT-123/')\n</examples>",
@@ -165,7 +170,7 @@
     "description": "Sentry's AI debugger that helps you analyze, root cause, and fix issues",
     "defaultEnabled": true,
     "order": 2,
-    "toolCount": 9,
+    "toolCount": 10,
     "tools": [
       {
         "name": "analyze_issue_with_seer",
@@ -187,6 +192,11 @@
         "description": "Fetch all spans for an AI conversation by its gen_ai.conversation.id.\n\nA conversation is a set of spans sharing the same gen_ai.conversation.id. To discover conversation IDs, use search_events with dataset='spans' and query='has:gen_ai.conversation.id'.",
         "requiredScopes": ["event:read", "project:read"]
       },
+      {
+        "name": "get_event_stacktrace",
+        "description": "Get a full thread stacktrace from a specific Sentry event.\n\nUse this tool when you need to:\n- Fetch the full stacktrace for a thread listed in issue details\n- Inspect a non-crashed thread from an event with multiple threads\n- Get Sentry's default selected thread stacktrace when no thread is specified\n\n<examples>\nget_event_stacktrace(organizationSlug='my-org', issueId='PROJECT-123')\nget_event_stacktrace(organizationSlug='my-org', issueId='PROJECT-123', eventId='abc123', thread=259)\nget_event_stacktrace(organizationSlug='my-org', issueId='PROJECT-123', thread='main')\n</examples>\n\n<hints>\n- `thread` is optional. If omitted, this returns the same default thread Sentry selects: first crashed thread, then first thread with a stacktrace, then first thread.\n- Pass `thread` as a numeric Thread ID or exact thread Name from the issue details thread list.\n- If the issue details show only one useful thread, omit `thread`.\n</hints>",
+        "requiredScopes": ["event:read"]
+      },
       {
         "name": "get_issue_details",
         "description": "Get detailed information about a specific Sentry issue by ID.\n\nUSE THIS TOOL WHEN USERS:\n- Provide a specific issue ID (e.g., 'CLOUDFLARE-MCP-41', 'PROJECT-123')\n- Ask to 'explain [ISSUE-ID]', 'tell me about [ISSUE-ID]'\n- Want details/stacktrace/analysis for a known issue\n- Provide a Sentry issue URL\n\nDO NOT USE for:\n- General searching or listing issues (use search_issues)\n\nTRIGGER PATTERNS:\n- 'Explain ISSUE-123' → use get_issue_details\n- 'Tell me about PROJECT-456' → use get_issue_details\n- 'What happened in [issue URL]' → use get_issue_details\n\n<examples>\n### With Sentry URL (recommended - simplest approach)\n```\nget_issue_details(issueUrl='https://sentry.sentry.io/issues/6916805731/?project=4509062593708032&query=is%3Aunresolved')\n```\n\n### With issue ID and organization\n```\nget_issue_details(organizationSlug='my-organization', issueId='CLOUDFLARE-MCP-41')\n```\n\n### With event ID and organization\n```\nget_issue_details(organizationSlug='my-organization', eventId='c49541c747cb4d8aa3efb70ca5aba243')\n```\n</examples>\n\n<hints>\n- **IMPORTANT**: If user provides a Sentry URL, pass the ENTIRE URL to issueUrl parameter unchanged\n- When using issueUrl, all other parameters are automatically extracted - don't provide them separately\n- If using issueId (not URL), then organizationSlug is required\n</hints>",
@@ -256,7 +266,7 @@
     "description": "Resolve, assign, and update issues",
     "defaultEnabled": false,
     "order": 4,
-    "toolCount": 13,
+    "toolCount": 14,
     "tools": [
       {
         "name": "add_issue_note",
@@ -283,6 +293,11 @@
         "description": "Fetch all spans for an AI conversation by its gen_ai.conversation.id.\n\nA conversation is a set of spans sharing the same gen_ai.conversation.id. To discover conversation IDs, use search_events with dataset='spans' and query='has:gen_ai.conversation.id'.",
         "requiredScopes": ["event:read", "project:read"]
       },
+      {
+        "name": "get_event_stacktrace",
+        "description": "Get a full thread stacktrace from a specific Sentry event.\n\nUse this tool when you need to:\n- Fetch the full stacktrace for a thread listed in issue details\n- Inspect a non-crashed thread from an event with multiple threads\n- Get Sentry's default selected thread stacktrace when no thread is specified\n\n<examples>\nget_event_stacktrace(organizationSlug='my-org', issueId='PROJECT-123')\nget_event_stacktrace(organizationSlug='my-org', issueId='PROJECT-123', eventId='abc123', thread=259)\nget_event_stacktrace(organizationSlug='my-org', issueId='PROJECT-123', thread='main')\n</examples>\n\n<hints>\n- `thread` is optional. If omitted, this returns the same default thread Sentry selects: first crashed thread, then first thread with a stacktrace, then first thread.\n- Pass `thread` as a numeric Thread ID or exact thread Name from the issue details thread list.\n- If the issue details show only one useful thread, omit `thread`.\n</hints>",
+        "requiredScopes": ["event:read"]
+      },
       {
         "name": "get_issue_activity",
         "description": "Get the activity feed and comments for a Sentry issue.\n\nUse this tool when you need to:\n- Review prior comments before triaging an issue\n- Understand who resolved, ignored, assigned, or commented on an issue\n- See recent issue activity that is not included in `get_issue_details`\n\n<examples>\nget_issue_activity(organizationSlug='my-organization', issueId='PROJECT-123')\nget_issue_activity(issueUrl='https://my-organization.sentry.io/issues/PROJECT-123/')\n</examples>",