feat(tools): Add issue breadcrumbs catalog tool (#1170)

Add `get_issue_breadcrumbs` as the dedicated catalog-only path for
retrieving breadcrumbs from an issue’s latest event. This removes the
breadcrumbs resource-type override from `get_sentry_resource`, so
callers discover and execute the focused tool through the catalog
instead.

**Catalog-only exposure**

The new tool supports issue IDs and issue URLs, preserves project
constraints and enhanced not-found handling, and is intentionally
omitted from the direct MCP surface.

**Reference migration**

Issue detail guidance, generated definitions, resolver coverage, tool
tests, and eval expectations now use `get_issue_breadcrumbs` rather than
the former `get_sentry_resource(..., resourceType='breadcrumbs')`
workaround.

<!-- junior-request-attribution:start -->
Requested by **David Cramer** via Junior.
<!-- junior-request-attribution:end -->

<!-- junior-session-footer:start -->

--

[View Junior
Session](https://junior-prod.sentry.dev/conversations/slack%3AC08J1NSPU6S%3A1784683235.733369)

<!-- junior-session-footer:end -->

Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com>
Co-authored-by: OpenAI Codex <noreply@openai.com>
Co-authored-by: David Cramer <david@sentry.io>

Author: 3 people

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

@@ -182,6 +182,7 @@ describe("formatIssueOutput", () => {
       experimentalMode: true,
       availableToolNames: new Set([
         "get_sentry_resource",
+        "get_issue_breadcrumbs",
         "search_issue_events",
       ]),
       directToolNames: new Set(["get_sentry_resource", "search_issue_events"]),

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

@@ -2262,7 +2262,18 @@ export function formatIssueOutput({
     output += `- Related log search: ${logSearchInstruction}\n`;
   }
   if (experimentalMode) {
-    output += `- Breadcrumb trail leading up to this error: \`get_sentry_resource(url='${apiService.getIssueUrl(organizationSlug, issue.shortId)}', resourceType='breadcrumbs')\`\n`;
+    const breadcrumbsInstruction = formatToolCallInstruction({
+      toolName: "get_issue_breadcrumbs",
+      arguments: {
+        issueUrl: apiService.getIssueUrl(organizationSlug, issue.shortId),
+      },
+      experimentalMode,
+      availableToolNames,
+      directToolNames,
+      fallbackInstruction:
+        "Issue breadcrumbs are not available in this session",
+    });
+    output += `- Breadcrumb trail leading up to this error: ${breadcrumbsInstruction}\n`;
   }
   return output;
 }

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

@@ -649,6 +649,7 @@ describe("buildServer", () => {
       expect(toolNames).not.toContain("whoami");
       expect(toolNames).toContain("get_sentry_resource");
       expect(toolNames).not.toContain("get_issue_details");
+      expect(toolNames).not.toContain("get_issue_breadcrumbs");
       expect(toolNames).not.toContain("get_trace_details");
       expect(toolNames).not.toContain("get_snapshot");
       expect(toolNames).not.toContain("get_snapshot_image");

packages/mcp-core/src/skillDefinitions.json

@@ -1437,6 +1437,43 @@
     "skills": ["inspect", "triage"],
     "surface": "catalog"
   },
+  {
+    "name": "get_issue_breadcrumbs",
+    "description": "Get the breadcrumb trail from the latest event for a Sentry issue.\n\nUse this tool when you need to:\n- See the user and application actions leading up to an error\n- Inspect navigation, console, HTTP, and other breadcrumb events\n- Reconstruct the immediate context before an issue occurred\n\n<examples>\nget_issue_breadcrumbs(organizationSlug='my-org', issueId='PROJECT-123')\nget_issue_breadcrumbs(issueUrl='https://my-org.sentry.io/issues/PROJECT-123/')\n</examples>",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "organizationSlug": {
+          "type": "string",
+          "description": "The organization's slug. You can find a existing list of organizations you have access to using the `find_organizations()` tool."
+        },
+        "regionUrl": {
+          "default": null,
+          "anyOf": [
+            {
+              "type": "string",
+              "description": "The region URL for the organization you're querying, if known. For Sentry's Cloud Service (sentry.io), this is typically the region-specific URL like 'https://us.sentry.io'. For self-hosted Sentry installations, this parameter is usually not needed and should be omitted. You can find the correct regionUrl from the organization details using the `find_organizations()` tool."
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "issueId": {
+          "type": "string",
+          "description": "The Issue ID. e.g. `PROJECT-1Z43`"
+        },
+        "issueUrl": {
+          "type": "string",
+          "format": "uri",
+          "description": "The URL of the issue. e.g. https://my-organization.sentry.io/issues/PROJECT-1Z43"
+        }
+      }
+    },
+    "requiredScopes": ["event:read"],
+    "skills": ["inspect", "triage"],
+    "surface": "catalog"
+  },
   {
     "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>",
@@ -2001,7 +2038,7 @@
   },
   {
     "name": "get_sentry_resource",
-    "description": "Fetch a Sentry resource by URL, or by resourceType plus resourceId.\nPass a Sentry URL directly when possible; the resource type is auto-detected.\n\nSupports issues, events, traces, spans, AI conversations, breadcrumbs, replays, monitors, preprod snapshots, and snapshot images.\nTrace lookups return a condensed overview by default.\n\nAI Conversations: A conversation is a set of spans sharing the same gen_ai.conversation.id. Use resourceType='ai_conversation' with a conversation ID, or pass a Sentry conversation URL, to fetch the transcript/details. To discover or list conversations, use search_ai_conversations. Conversations are NOT issues — do not use search_issues for conversation queries.\n\nFor preprod snapshot URLs (matching 'sentry.io/preprod/snapshots/'):\n- Without ?selectedSnapshot=: returns the snapshot diff summary (changed, added, removed images)\n- With ?selectedSnapshot=<image_file_name>: returns the image preview and metadata. Use the Sentry tool `get_snapshot_image` for full-resolution image bytes.\n\nResource IDs:\n- span: <traceId>:<spanId>\n- monitor: <monitorSlug>\n- snapshot: <snapshotId>\n- snapshotImage: <snapshotId>:<image_file_name>\n\n<examples>\nget_sentry_resource(url='https://sentry.io/issues/PROJECT-123/')\nget_sentry_resource(resourceType='issue', organizationSlug='my-org', resourceId='PROJECT-123')\nget_sentry_resource(resourceType='span', organizationSlug='my-org', resourceId='<traceId>:<spanId>')\nget_sentry_resource(resourceType='ai_conversation', organizationSlug='my-org', resourceId='conversation-123')\nget_sentry_resource(url='https://sentry.sentry.io/preprod/snapshots/123/')\nget_sentry_resource(url='https://sentry.sentry.io/preprod/snapshots/123/?selectedSnapshot=login_screen.png')\n</examples>",
+    "description": "Fetch a Sentry resource by URL, or by resourceType plus resourceId.\nPass a Sentry URL directly when possible; the resource type is auto-detected.\n\nSupports issues, events, traces, spans, AI conversations, replays, monitors, preprod snapshots, and snapshot images.\nTrace lookups return a condensed overview by default.\n\nAI Conversations: A conversation is a set of spans sharing the same gen_ai.conversation.id. Use resourceType='ai_conversation' with a conversation ID, or pass a Sentry conversation URL, to fetch the transcript/details. To discover or list conversations, use search_ai_conversations. Conversations are NOT issues — do not use search_issues for conversation queries.\n\nFor preprod snapshot URLs (matching 'sentry.io/preprod/snapshots/'):\n- Without ?selectedSnapshot=: returns the snapshot diff summary (changed, added, removed images)\n- With ?selectedSnapshot=<image_file_name>: returns the image preview and metadata. Use the Sentry tool `get_snapshot_image` for full-resolution image bytes.\n\nResource IDs:\n- span: <traceId>:<spanId>\n- monitor: <monitorSlug>\n- snapshot: <snapshotId>\n- snapshotImage: <snapshotId>:<image_file_name>\n\n<examples>\nget_sentry_resource(url='https://sentry.io/issues/PROJECT-123/')\nget_sentry_resource(resourceType='issue', organizationSlug='my-org', resourceId='PROJECT-123')\nget_sentry_resource(resourceType='span', organizationSlug='my-org', resourceId='<traceId>:<spanId>')\nget_sentry_resource(resourceType='ai_conversation', organizationSlug='my-org', resourceId='conversation-123')\nget_sentry_resource(url='https://sentry.sentry.io/preprod/snapshots/123/')\nget_sentry_resource(url='https://sentry.sentry.io/preprod/snapshots/123/?selectedSnapshot=login_screen.png')\n</examples>",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -2011,15 +2048,14 @@
           "format": "uri"
         },
         "resourceType": {
-          "description": "Resource type. With a URL, can override the auto-detected type for breadcrumbs on an issue/event URL or for `trace` on a span-focused trace URL. Use `monitor` with a monitor slug only when inspect monitor tools are available, `snapshot` with a snapshot artifact ID, or `snapshotImage` with `<snapshotId>:<image_file_name>`.",
+          "description": "Resource type. With a URL, can override a span-focused trace URL with `trace`. Use `monitor` with a monitor slug only when inspect monitor tools are available, `snapshot` with a snapshot artifact ID, or `snapshotImage` with `<snapshotId>:<image_file_name>`.",
           "type": "string",
           "enum": [
             "issue",
             "event",
             "trace",
             "span",
             "ai_conversation",
-            "breadcrumbs",
             "replay",
             "monitor",
             "snapshot",

packages/mcp-core/src/toolDefinitions.json

@@ -0,0 +1,107 @@
+import { eventFixture, mswServer } from "@sentry/mcp-server-mocks";
+import { http, HttpResponse } from "msw";
+import { afterEach, describe, expect, it } from "vitest";
+import getIssueBreadcrumbs from "./get-issue-breadcrumbs.js";
+
+const context = {
+  constraints: { organizationSlug: undefined },
+  accessToken: "access-token",
+  userId: "1",
+};
+
+afterEach(() => {
+  mswServer.resetHandlers();
+});
+
+describe("get_issue_breadcrumbs", () => {
+  it("returns breadcrumbs from the latest issue event", async () => {
+    const result = await getIssueBreadcrumbs.handler(
+      {
+        organizationSlug: "sentry-mcp-evals",
+        regionUrl: null,
+        issueId: "CLOUDFLARE-MCP-41",
+      },
+      context,
+    );
+
+    expect(result).toMatchInlineSnapshot(`
+      "# Breadcrumbs for CLOUDFLARE-MCP-41
+
+      **Event ID**: 7ca573c0f4814912aaa9bdc77d1a7d51
+      **Total Breadcrumbs**: 4
+
+      \`\`\`
+      2025-04-08T21:14:50.000Z info    [fetch] GET /api/0/organizations/ [200] {"method":"GET","url":"/api/0/organizations/","status_code":200}
+      2025-04-08T21:14:52.000Z warning [console] Deprecation warning: use v2 endpoint
+      2025-04-08T21:14:55.000Z info    [navigation] {"from":"/dashboard","to":"/settings"}
+      2025-04-08T21:15:04.000Z error   [console] Tool list_organizations is already registered
+      \`\`\`
+
+      Breadcrumbs show the trail of events leading up to the error, in chronological order.
+      Use \`get_sentry_resource(resourceType='issue', organizationSlug='...', resourceId='CLOUDFLARE-MCP-41')\` for full issue details."
+    `);
+  });
+
+  it("accepts an issue URL", async () => {
+    const result = await getIssueBreadcrumbs.handler(
+      {
+        issueUrl:
+          "https://sentry-mcp-evals.sentry.io/issues/CLOUDFLARE-MCP-41/",
+        regionUrl: null,
+      },
+      context,
+    );
+
+    expect(result).toContain("# Breadcrumbs for CLOUDFLARE-MCP-41");
+  });
+
+  it("rejects issues outside the active project constraint", async () => {
+    await expect(
+      getIssueBreadcrumbs.handler(
+        {
+          organizationSlug: "sentry-mcp-evals",
+          issueId: "CLOUDFLARE-MCP-41",
+          regionUrl: null,
+        },
+        {
+          ...context,
+          constraints: {
+            organizationSlug: "sentry-mcp-evals",
+            projectSlug: "frontend",
+          },
+        },
+      ),
+    ).rejects.toThrow(
+      'Issue is outside the active project constraint. Expected project "frontend".',
+    );
+  });
+
+  it("handles an event with no breadcrumbs", async () => {
+    mswServer.use(
+      http.get(
+        "https://sentry.io/api/0/organizations/sentry-mcp-evals/issues/CLOUDFLARE-MCP-41/events/latest/",
+        () =>
+          HttpResponse.json({
+            ...eventFixture,
+            entries: eventFixture.entries.filter(
+              (entry: { type: string }) => entry.type !== "breadcrumbs",
+            ),
+          }),
+        { once: true },
+      ),
+    );
+
+    const result = await getIssueBreadcrumbs.handler(
+      {
+        organizationSlug: "sentry-mcp-evals",
+        regionUrl: null,
+        issueId: "CLOUDFLARE-MCP-41",
+      },
+      context,
+    );
+
+    expect(result).toContain(
+      "No breadcrumbs found in the latest event for this issue.",
+    );
+  });
+});

packages/mcp-core/src/tools/catalog/get-issue-breadcrumbs.test.ts

@@ -0,0 +1,82 @@
+import { setTag } from "@sentry/core";
+import { ApiNotFoundError } from "../../api-client";
+import { apiServiceFromContext } from "../../internal/tool-helpers/api";
+import { fetchAndFormatBreadcrumbs } from "../../internal/tool-helpers/breadcrumbs";
+import { defineTool } from "../../internal/tool-helpers/define";
+import { enhanceNotFoundError } from "../../internal/tool-helpers/enhance-error";
+import {
+  ensureIssueWithinProjectConstraint,
+  parseIssueParams,
+} from "../../internal/tool-helpers/issue";
+import {
+  ParamIssueShortId,
+  ParamIssueUrl,
+  ParamOrganizationSlug,
+  ParamRegionUrl,
+} from "../../schema";
+import type { ServerContext } from "../../types";
+
+export default defineTool({
+  name: "get_issue_breadcrumbs",
+  skills: ["inspect", "triage"],
+  requiredScopes: ["event:read"],
+  description: [
+    "Get the breadcrumb trail from the latest event for a Sentry issue.",
+    "",
+    "Use this tool when you need to:",
+    "- See the user and application actions leading up to an error",
+    "- Inspect navigation, console, HTTP, and other breadcrumb events",
+    "- Reconstruct the immediate context before an issue occurred",
+    "",
+    "<examples>",
+    "get_issue_breadcrumbs(organizationSlug='my-org', issueId='PROJECT-123')",
+    "get_issue_breadcrumbs(issueUrl='https://my-org.sentry.io/issues/PROJECT-123/')",
+    "</examples>",
+  ].join("\n"),
+  inputSchema: {
+    organizationSlug: ParamOrganizationSlug.optional(),
+    regionUrl: ParamRegionUrl.nullable().default(null),
+    issueId: ParamIssueShortId.optional(),
+    issueUrl: ParamIssueUrl.optional(),
+  },
+  annotations: {
+    readOnlyHint: true,
+    openWorldHint: true,
+  },
+  async handler(params, context: ServerContext) {
+    const parsed = parseIssueParams({
+      issueUrl: params.issueUrl,
+      issueId: params.issueId,
+      organizationSlug:
+        params.organizationSlug ?? context.constraints.organizationSlug,
+    });
+    const apiService = apiServiceFromContext(context, {
+      regionUrl: params.regionUrl ?? context.constraints.regionUrl ?? undefined,
+    });
+
+    setTag("organization.slug", parsed.organizationSlug);
+    setTag("issue.id", parsed.issueId);
+
+    try {
+      await ensureIssueWithinProjectConstraint({
+        apiService,
+        organizationSlug: parsed.organizationSlug,
+        issueId: parsed.issueId,
+        projectSlug: context.constraints.projectSlug,
+      });
+      return await fetchAndFormatBreadcrumbs(
+        apiService,
+        parsed.organizationSlug,
+        parsed.issueId,
+      );
+    } catch (error) {
+      if (error instanceof ApiNotFoundError) {
+        throw enhanceNotFoundError(error, {
+          organizationSlug: parsed.organizationSlug,
+          issueId: parsed.issueId,
+        });
+      }
+      throw error;
+    }
+  },
+});