feat(tools): Add onboarding status updates

Expose a directly available onboarding_status_update tool that sends
explicit stage and run state to Sentry. Region-aware routing and org:read
authorization reuse the existing API client path.

The tool treats updates as silent UI bookkeeping, avoids echoing sensitive
context, and returns whether subsequent updates should continue. Generated
definitions document the shared contract.

Author: evanpurkhiser

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

@@ -34,6 +34,7 @@ import { USER_AGENT } from "../version";
 import { apiPath } from "./api-path";
 import { ApiNotFoundError, ApiValidationError, createApiError } from "./errors";
 import {
+  AgenticOnboardingRunSchema,
   AIConversationDetailsResponseSchema,
   AIConversationSummaryListSchema,
   ApiErrorSchema,
@@ -92,6 +93,8 @@ import {
   UserSchema,
 } from "./schema";
 import type {
+  AgenticOnboardingRun,
+  AgenticOnboardingStatusUpdate,
   AIConversationDetails,
   AIConversationSpanList,
   AIConversationSummary,
@@ -1858,6 +1861,28 @@ export class SentryApiService {
    * @param opts Request options
    * @returns Updated project data
    */
+  async updateAgenticOnboardingStatus(
+    {
+      organizationSlug,
+      update,
+    }: {
+      organizationSlug: string;
+      update: AgenticOnboardingStatusUpdate;
+    },
+    opts?: RequestOptions,
+  ): Promise<AgenticOnboardingRun> {
+    const body = await this.requestJSON(
+      `/organizations/${organizationSlug}/onboarding/agent/status/`,
+      {
+        method: "POST",
+        body: JSON.stringify(update),
+      },
+      opts,
+    );
+
+    return AgenticOnboardingRunSchema.parse(body);
+  }
+
   async updateProject(
     {
       organizationSlug,

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

@@ -2076,3 +2076,70 @@ export const TransactionProfileSchema = z
       .optional(),
   })
   .passthrough();
+
+export const AgenticOnboardingStageSchema = z.enum([
+  "connect_mcp",
+  "analyze_project",
+  "create_project",
+  "instrument_app",
+  "plan_test_error",
+  "send_verification_error",
+  "receive_verification_error",
+  "prepare_production",
+  "check_stack_trace_quality",
+]);
+
+export const AgenticOnboardingStageStatusSchema = z.enum([
+  "active",
+  "waiting",
+  "completed",
+  "skipped",
+  "failed",
+]);
+
+export const AgenticOnboardingStageStateSchema = z.object({
+  stage: AgenticOnboardingStageSchema,
+  status: AgenticOnboardingStageStatusSchema.nullable(),
+  eventNote: z.string().nullable(),
+  failureReason: z.string().nullable(),
+});
+
+export const AgenticOnboardingRunStatusSchema = z.enum([
+  "active",
+  "completed",
+  "failed",
+  "cancelled",
+]);
+
+export const AgenticOnboardingRunStatusUpdateSchema = z.enum([
+  "completed",
+  "failed",
+]);
+
+export const AgenticOnboardingStatusUpdateSchema = z.object({
+  schemaVersion: z.literal(1),
+  runToken: z.string().regex(/^[A-Za-z0-9]{10}$/),
+  stage: AgenticOnboardingStageSchema,
+  status: AgenticOnboardingStageStatusSchema,
+  runStatus: AgenticOnboardingRunStatusUpdateSchema.optional(),
+  eventNote: z.string().trim().min(1).max(256).optional(),
+  failureReason: z.string().trim().min(1).max(256).optional(),
+  projectSlug: z.string().trim().min(1).optional(),
+  issueId: z.string().trim().min(1).optional(),
+});
+
+export const AgenticOnboardingRunSchema = z.object({
+  schemaVersion: z.literal(1),
+  runId: z.string(),
+  channelId: z.string(),
+  clientRunId: z.string(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  sequence: z.number().int().nonnegative(),
+  expiresAt: z.string(),
+  continueUpdates: z.boolean(),
+  runStatus: AgenticOnboardingRunStatusSchema,
+  projectSlug: z.string().nullable(),
+  issueId: z.string().nullable(),
+  stages: z.array(AgenticOnboardingStageStateSchema),
+});

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

@@ -40,6 +40,8 @@
  */
 import type { z } from "zod";
 import type {
+  AgenticOnboardingRunSchema,
+  AgenticOnboardingStatusUpdateSchema,
   AssignedToSchema,
   AIConversationSummaryListSchema,
   AIConversationSummarySchema,
@@ -125,6 +127,10 @@ import type {
   UserReportListSchema,
 } from "./schema";
 
+export type AgenticOnboardingRun = z.infer<typeof AgenticOnboardingRunSchema>;
+export type AgenticOnboardingStatusUpdate = z.infer<
+  typeof AgenticOnboardingStatusUpdateSchema
+>;
 export type User = z.infer<typeof UserSchema>;
 export type Organization = z.infer<typeof OrganizationSchema>;
 export type Team = z.infer<typeof TeamSchema>;

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

@@ -3,7 +3,7 @@ import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { McpServer as ModernMcpServer } from "@modelcontextprotocol/server";
 import { type Span, setUser, startSpan } from "@sentry/core";
 import { mswServer } from "@sentry/mcp-server-mocks";
-import { http, HttpResponse } from "msw";
+import { HttpResponse, http } from "msw";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { z } from "zod";
 import { structuredResult } from "./internal/tool-helpers/results";
@@ -109,6 +109,7 @@ const DEFAULT_DIRECT_TOOL_NAMES = [
   "find_organizations",
   "find_projects",
   "get_sentry_resource",
+  "onboarding_status_update",
   "search_events",
   "search_issues",
   "search_sentry_tools",
@@ -732,6 +733,7 @@ describe("buildServer", () => {
             "execute_sentry_tool",
             "find_organizations",
             "find_projects",
+            "onboarding_status_update",
             "search_sentry_tools",
           ],
         },

packages/mcp-core/src/skillDefinitions.json

@@ -5,7 +5,7 @@
     "description": "Read-only access to core Sentry data: issues, events, traces, replays, releases, cron monitors, uptime monitors, profiles, documentation, and project metadata",
     "defaultEnabled": true,
     "order": 1,
-    "toolCount": 37,
+    "toolCount": 38,
     "tools": [
       {
         "name": "find_alert_rules",
@@ -162,6 +162,11 @@
         "description": "Get details for a Sentry uptime monitor, including recent checks.\n\nUse this tool when you need to:\n- Inspect an uptime monitor's URL, interval, thresholds, and status\n- Review recent HTTP check results (success/failure, status code, duration)\n- Debug why an uptime monitor is failing\n\nThis is separate from cron monitors (`get_monitor_details`).\n\nRequest bodies are never returned. Sensitive header values are redacted.\n\n<examples>\nget_uptime_monitor_details(organizationSlug='my-organization', projectSlug='backend', uptimeMonitorId='12345')\nget_uptime_monitor_details(organizationSlug='my-organization', projectSlug='backend', uptimeMonitorId='12345', period='7d', checkLimit=20)\n</examples>",
         "requiredScopes": ["project:read"]
       },
+      {
+        "name": "onboarding_status_update",
+        "description": "Update the progress shown in Sentry's agentic onboarding UI.\n\nUse this tool only when an onboarding workflow provides a run token. Call it at the workflow boundaries described by the onboarding skill.\n\n<hints>\n- Progress updates are operational UI state, not user analytics.\n- Keep eventNote brief and limited to context useful in the progress UI.\n- Do not include source code, repository paths, credentials, error output, or other sensitive data.\n- status is required for every update.\n- Set runStatus to completed or failed only when the entire onboarding run reaches that state.\n- A failed status requires a brief failureReason.\n- failureReason is valid only with status failed.\n</hints>",
+        "requiredScopes": ["org:read"]
+      },
       {
         "name": "search_ai_conversations",
         "description": "Search Sentry AI Conversations and return one summary row per conversation.\n\nUse this tool to find or list AI Conversations. Results are conversation summaries, not raw span rows.\nEach row includes title (when available), cost, tokens, call counts, previews, and other list metadata.\nUse get_ai_conversation_details with a conversationId to fetch the transcript. Use get_sentry_resource for Sentry conversation URLs.\n\n<examples>\nsearch_ai_conversations(organizationSlug='my-org', query='failed conversations', period='7d')\nsearch_ai_conversations(organizationSlug='my-org', query='checkout', project='backend')\n</examples>",
@@ -200,7 +205,7 @@
     "description": "Sentry's AI debugger that helps you analyze, root cause, and fix issues",
     "defaultEnabled": true,
     "order": 2,
-    "toolCount": 11,
+    "toolCount": 12,
     "tools": [
       {
         "name": "analyze_issue_with_seer",
@@ -237,6 +242,11 @@
         "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, 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. Full-resolution snapshot image bytes are not available in this session.\n\nResource IDs:\n- snapshot: <snapshotId>\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='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>",
         "requiredScopes": ["event:read", "project:read"]
       },
+      {
+        "name": "onboarding_status_update",
+        "description": "Update the progress shown in Sentry's agentic onboarding UI.\n\nUse this tool only when an onboarding workflow provides a run token. Call it at the workflow boundaries described by the onboarding skill.\n\n<hints>\n- Progress updates are operational UI state, not user analytics.\n- Keep eventNote brief and limited to context useful in the progress UI.\n- Do not include source code, repository paths, credentials, error output, or other sensitive data.\n- status is required for every update.\n- Set runStatus to completed or failed only when the entire onboarding run reaches that state.\n- A failed status requires a brief failureReason.\n- failureReason is valid only with status failed.\n</hints>",
+        "requiredScopes": ["org:read"]
+      },
       {
         "name": "search_ai_conversations",
         "description": "Search Sentry AI Conversations and return one summary row per conversation.\n\nUse this tool to find or list AI Conversations. Results are conversation summaries, not raw span rows.\nEach row includes title (when available), cost, tokens, call counts, previews, and other list metadata.\nUse get_ai_conversation_details with a conversationId to fetch the transcript. Use get_sentry_resource for Sentry conversation URLs.\n\n<examples>\nsearch_ai_conversations(organizationSlug='my-org', query='failed conversations', period='7d')\nsearch_ai_conversations(organizationSlug='my-org', query='checkout', project='backend')\n</examples>",
@@ -266,7 +276,7 @@
     "defaultEnabled": false,
     "deprecated": true,
     "order": 3,
-    "toolCount": 5,
+    "toolCount": 6,
     "tools": [
       {
         "name": "find_organizations",
@@ -283,6 +293,11 @@
         "description": "Fetch the full markdown content of a Sentry documentation page.\n\nUse this tool when you need to:\n- Read the complete documentation for a specific topic\n- Get detailed implementation examples or code snippets\n- Access the full context of a documentation page\n- Extract specific sections from documentation\n\n<examples>\n### Get the Next.js integration guide\n\n```\nget_doc(path='/platforms/javascript/guides/nextjs.md')\n```\n</examples>\n\n<hints>\n- Use the path from search_docs results for accurate fetching\n- Paths should end with .md extension\n</hints>",
         "requiredScopes": []
       },
+      {
+        "name": "onboarding_status_update",
+        "description": "Update the progress shown in Sentry's agentic onboarding UI.\n\nUse this tool only when an onboarding workflow provides a run token. Call it at the workflow boundaries described by the onboarding skill.\n\n<hints>\n- Progress updates are operational UI state, not user analytics.\n- Keep eventNote brief and limited to context useful in the progress UI.\n- Do not include source code, repository paths, credentials, error output, or other sensitive data.\n- status is required for every update.\n- Set runStatus to completed or failed only when the entire onboarding run reaches that state.\n- A failed status requires a brief failureReason.\n- failureReason is valid only with status failed.\n</hints>",
+        "requiredScopes": ["org:read"]
+      },
       {
         "name": "search_docs",
         "description": "Search Sentry documentation for SDK setup, instrumentation, and configuration guidance.\n\nUse this tool when you need to:\n- Set up Sentry SDK or framework integrations (Django, Flask, Express, Next.js, etc.)\n- Configure features like performance monitoring, error sampling, or release tracking\n- Implement custom instrumentation (spans, transactions, breadcrumbs)\n- Configure data scrubbing, filtering, or sampling rules\n\nReturns snippets only. Use the Sentry tool `get_doc` to fetch full documentation content.\n\n<examples>\n```\nsearch_docs(query='Django setup configuration SENTRY_DSN', guide='python/django')\nsearch_docs(query='source maps webpack upload', guide='javascript/nextjs')\n```\n</examples>\n\n<hints>\n- Use guide parameter to filter to specific technologies (e.g., 'javascript/nextjs')\n- Include specific feature names like 'beforeSend', 'tracesSampleRate', 'SENTRY_DSN'\n</hints>",
@@ -301,7 +316,7 @@
     "description": "Resolve, assign, and update issues",
     "defaultEnabled": false,
     "order": 4,
-    "toolCount": 17,
+    "toolCount": 18,
     "tools": [
       {
         "name": "add_issue_note",
@@ -358,6 +373,11 @@
         "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, 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. Full-resolution snapshot image bytes are not available in this session.\n\nResource IDs:\n- snapshot: <snapshotId>\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='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>",
         "requiredScopes": ["event:read", "project:read"]
       },
+      {
+        "name": "onboarding_status_update",
+        "description": "Update the progress shown in Sentry's agentic onboarding UI.\n\nUse this tool only when an onboarding workflow provides a run token. Call it at the workflow boundaries described by the onboarding skill.\n\n<hints>\n- Progress updates are operational UI state, not user analytics.\n- Keep eventNote brief and limited to context useful in the progress UI.\n- Do not include source code, repository paths, credentials, error output, or other sensitive data.\n- status is required for every update.\n- Set runStatus to completed or failed only when the entire onboarding run reaches that state.\n- A failed status requires a brief failureReason.\n- failureReason is valid only with status failed.\n</hints>",
+        "requiredScopes": ["org:read"]
+      },
       {
         "name": "search_ai_conversations",
         "description": "Search Sentry AI Conversations and return one summary row per conversation.\n\nUse this tool to find or list AI Conversations. Results are conversation summaries, not raw span rows.\nEach row includes title (when available), cost, tokens, call counts, previews, and other list metadata.\nUse get_ai_conversation_details with a conversationId to fetch the transcript. Use get_sentry_resource for Sentry conversation URLs.\n\n<examples>\nsearch_ai_conversations(organizationSlug='my-org', query='failed conversations', period='7d')\nsearch_ai_conversations(organizationSlug='my-org', query='checkout', project='backend')\n</examples>",
@@ -396,7 +416,7 @@
     "description": "Create and modify projects, teams, DSNs, and uptime monitors",
     "defaultEnabled": false,
     "order": 5,
-    "toolCount": 15,
+    "toolCount": 16,
     "tools": [
       {
         "name": "add_team_to_project",
@@ -448,6 +468,11 @@
         "description": "Find teams in an organization in Sentry.\n\nUse this tool when you need to:\n- View teams in a Sentry organization\n- Find a team's slug and numeric ID to aid other tool requests\n- Search for specific teams by name or slug\n\nReturns up to 25 results. When hasMore is true, use the query parameter to narrow down results.",
         "requiredScopes": ["team:read"]
       },
+      {
+        "name": "onboarding_status_update",
+        "description": "Update the progress shown in Sentry's agentic onboarding UI.\n\nUse this tool only when an onboarding workflow provides a run token. Call it at the workflow boundaries described by the onboarding skill.\n\n<hints>\n- Progress updates are operational UI state, not user analytics.\n- Keep eventNote brief and limited to context useful in the progress UI.\n- Do not include source code, repository paths, credentials, error output, or other sensitive data.\n- status is required for every update.\n- Set runStatus to completed or failed only when the entire onboarding run reaches that state.\n- A failed status requires a brief failureReason.\n- failureReason is valid only with status failed.\n</hints>",
+        "requiredScopes": ["org:read"]
+      },
       {
         "name": "remove_team_from_project",
         "description": "Revoke a team's access to an existing Sentry project.\n\nUse this tool when you need to:\n- Remove a team from a project\n- Revoke team access without changing project metadata\n- Check project team assignments before removing access\n\nBe careful when using this tool because it revokes project access.\n\n<examples>\nremove_team_from_project(organizationSlug='my-organization', projectSlug='my-project', teamSlug='my-team')\n</examples>\n\n<hints>\n- The team must already be assigned to the project.\n- This tool will not remove the last team assigned to a project.\n</hints>",