From a10f9a4090571f9d1ce38f85161554c833b3b409 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 26 Jun 2026 12:05:36 +0000 Subject: [PATCH 1/2] docs: add Sentry managed MCP server page Document the new read-only Sentry managed MCP server (per-user OAuth, 16 read tools, optional organization scoping) introduced in cloudv2. Add a setup how-to page, a catalog row under Utility, and a nav entry. Listed as beta: the server is not alpha-gated in register_mcp.go. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01FJBbvNLBEJyx7BZZYYJ6Me --- modules/ROOT/nav.adoc | 1 + .../pages/managed/managed-catalog.adoc | 5 + modules/connect/pages/managed/sentry.adoc | 264 ++++++++++++++++++ 3 files changed, 270 insertions(+) create mode 100644 modules/connect/pages/managed/sentry.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 31bb54e..c2154c8 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -30,6 +30,7 @@ **** xref:connect:managed/openapi.adoc[OpenAPI] **** xref:connect:managed/ramp.adoc[Ramp] **** xref:connect:managed/salesforce.adoc[Salesforce] +**** xref:connect:managed/sentry.adoc[Sentry] **** xref:connect:managed/servicenow.adoc[ServiceNow] **** xref:connect:managed/sharepoint.adoc[SharePoint] **** xref:connect:managed/slack.adoc[Slack] diff --git a/modules/connect/pages/managed/managed-catalog.adoc b/modules/connect/pages/managed/managed-catalog.adoc index 00bb077..5971c5b 100644 --- a/modules/connect/pages/managed/managed-catalog.adoc +++ b/modules/connect/pages/managed/managed-catalog.adoc @@ -6,6 +6,7 @@ Managed MCP servers are in-process implementations Redpanda hosts for you. Each type has a fixed set of glossterm:tool[,tools] and a type-specific configuration schema. To create one, open *MCP Servers > Create Server* in Redpanda ADP and pick the type from the marketplace picker. See xref:connect:create-server.adoc[Create an MCP Server] for the full create flow. // Source: `cloudv2` `apps/aigw/internal/mcp/managed/defaults.go` and managed type registration files on `origin/main`, verified at 6565ccaaa7, 2026-06-10. Gmail (google_gmail, ungated) added in this sweep. AWS S3 and SharePoint are alpha-gated in source but listed as beta by docs-team decision. neo4j and neo4j_aura are registered but alpha-gated and intentionally not listed. +// Sentry (utility, ungated read-only MCP, per-user OAuth) added 2026-06-26 from cloudv2 f7121d02d (catalogue) + bcdaea997 (16 read tools); not alpha-gated in register_mcp.go, listed as beta. This catalog lists the managed MCP server types Redpanda registers by default, grouped by category. == Choosing managed vs. self-managed @@ -237,6 +238,10 @@ If any of these answers are "no," prefer xref:connect:register-remote.adoc[a sel |Query, create, update, and delete Salesforce CRM records using SOQL and the REST API, and run and inspect saved Salesforce reports. |xref:connect:managed/salesforce.adoc[Setup guide] +|*Sentry* badge:beta[label=beta] +|Read-only access to Sentry organizations, projects, issues, events, and releases for diagnosing and fixing errors. +|xref:connect:managed/sentry.adoc[Setup guide] + |*SharePoint* badge:beta[label=beta] |Access SharePoint sites, document libraries, lists, and files through the Microsoft Graph API. |xref:connect:managed/sharepoint.adoc[Setup guide] diff --git a/modules/connect/pages/managed/sentry.adoc b/modules/connect/pages/managed/sentry.adoc new file mode 100644 index 0000000..6f96d34 --- /dev/null +++ b/modules/connect/pages/managed/sentry.adoc @@ -0,0 +1,264 @@ += Sentry Managed MCP Server +:page-beta: true +:description: Give an agent read-only access to Sentry organizations, projects, issues, events, and releases through per-user OAuth, so it can read a stack trace, scope an error's impact, and localize the fix. +:page-topic-type: how-to +:personas: agent_builder, platform_engineer +:learning-objective-1: Configure the Sentry managed MCP server with per-user OAuth +:learning-objective-2: Optionally confine the server to a single Sentry organization +:learning-objective-3: Diagnose an issue from the Inspector or an agent, from discovery through to the suspect commit + +The *Sentry* managed MCP server gives agents read-only access to a Sentry instance: discover organizations and projects, list and read issues, read the events (with stack traces) behind them, scope an error's impact across releases and tags, and surface the commits most likely responsible. The intended use is an agent that reads a Sentry issue and its stack trace to diagnose a bug, then fixes it in the codebase. + +After reading this page, you will be able to: + +* [ ] {learning-objective-1} +* [ ] {learning-objective-2} +* [ ] {learning-objective-3} + +== What this MCP server does + +Wraps the Sentry REST API and exposes 16 read-only tools grouped by the diagnose-and-fix flow: discover orgs and projects, read the error and its stack trace, scope the impact across tags and releases, and localize the fix to a suspect commit. + +Authentication is *per-user OAuth only*. Every tool call runs as the authenticated user against a Sentry OAuth token resolved from the gateway's glossterm:token vault[], so there is no shared service account and each action is attributed to the calling end-user. The server requests only read scopes (`org:read`, `project:read`, `event:read`, `project:releases`). + +The server is read-only by design: resolving or ignoring issues, commenting, and any other write operation is deliberately absent. Use the Sentry UI or its API directly for those. + +[NOTE] +==== +Tool output is developer-facing observability data, not PII-safe. The curated event shape omits Sentry's `user` and `request` context, but event `tags` are forwarded verbatim and can carry user-supplied values (for example `user`, `url`, `server_name`, or custom tags), and suspect-commit and release-commit output includes commit author names and email addresses. +==== + +This MCP server connects to `sentry.io` only. Self-hosted Sentry is not supported. + +== Prerequisites + +Before you create the server, make sure you have: + +* A Sentry account on `sentry.io` with access to the organizations and projects you want the agent to read. +* A Sentry OAuth application and a matching glossterm:OAuth provider[,OAuth Provider] configured in Redpanda ADP. See xref:connect:oauth-providers.adoc[Configure an OAuth Provider]. + +== Get Sentry credentials + +Sentry MCP uses per-user OAuth, so you register an OAuth application on Sentry and a matching OAuth Provider in ADP: + +. In Sentry, go to *Settings > Account > API > Applications* and create a new application. Set the authorized redirect URI to your ADP gateway's OAuth callback. +. Copy the *Client ID* and *Client Secret*, and store the client secret in the ADP secret store. +. Register a matching OAuth Provider in ADP. See xref:connect:oauth-providers.adoc[Configure an OAuth Provider]. Use Sentry's authorize endpoint (`https://sentry.io/oauth/authorize/`) and token endpoint (`https://sentry.io/oauth/token/`). +. Each end-user authenticates once through the OAuth flow; tokens are stored in the gateway's token vault. + +*Required scopes*: `org:read`, `project:read`, `event:read`, and `project:releases` cover all tools. `org:read` lists organizations and projects and resolves event IDs; `project:read` lists issues and reads project events and suspect commits; `event:read` reads issue events, tags, and hashes (the stack trace); and `project:releases` reads releases and their commits. All scopes are read-only. + +== Configure + +Create a new Sentry MCP server in ADP: + +. Open *MCP Servers > Create Server*. +. Pick `Sentry` from the marketplace picker. +. Fill in identity fields (`name`, `description`). +. In the Sentry configuration form: ++ +[cols="1,3"] +|=== +|Field |Notes + +|`organization_slug` +|Optional. Confines the server to a single Sentry organization. When set, every tool that takes an `organization_slug` is forced to this value and a request targeting a different organization is rejected; `list_organizations` stays unrestricted so it can still be used for discovery. Leave empty for unrestricted access, bounded only by the OAuth token. The slug is the URL segment at `sentry.io/organizations/`, not the display name. + +|`user_oauth` +|`provider_name` (the Sentry OAuth Provider you configured) and the minimum required scopes (`org:read`, `project:read`, `event:read`, `project:releases` covers all tools). +|=== ++ +. Click *Create*. + +=== Configure from the CLI + +For a managed server, set the OAuth provider and scopes inside the `--managed-config` JSON. Per-user OAuth is the only supported authentication method. + +[tabs] +====== +Unrestricted:: ++ +The caller supplies the organization on each call, bounded only by the OAuth token's access. ++ +[source,bash] +---- +rpk ai mcp create --name acme-sentry --managed-config '{ + "@type": "type.googleapis.com/redpanda.mcps.sentry.v1.SentryMCPConfig", + "user_oauth": { + "provider_name": "sentry-prod", + "required_scopes": ["org:read", "project:read", "event:read", "project:releases"] + } +}' +---- + +Confined to one organization:: ++ +Pin the server to a single organization with `organization_slug`. ++ +[source,bash] +---- +rpk ai mcp create --name acme-sentry --managed-config '{ + "@type": "type.googleapis.com/redpanda.mcps.sentry.v1.SentryMCPConfig", + "organization_slug": "my-org", + "user_oauth": { + "provider_name": "sentry-prod", + "required_scopes": ["org:read", "project:read", "event:read", "project:releases"] + } +}' +---- +====== + +== Tools + +The Sentry MCP exposes 16 read-only tools, grouped by the diagnose-and-fix flow: + +[cols="1,2"] +|=== +|Tool |Description + +|`list_organizations` +|List the Sentry organizations the token can access. Used for discovery; never restricted by `organization_slug`. + +|`list_projects` +|List the projects within an organization. + +|`list_issues` +|List a project's issues, filtered by a Sentry search query (for example, `is:unresolved`). + +|`get_issue` +|Fetch issue detail by numeric ID or short ID (for example, `WEB-1`). + +|`get_issue_latest_event` +|The most recent event for an issue, including its exception stack trace. + +|`list_issue_events` +|The individual occurrences of an issue (compare a failing against a passing event). + +|`get_issue_event` +|One event of an issue with a full stack trace, by ID or the alias `latest`, `oldest`, or `recommended` (`oldest` is the regression boundary). + +|`get_event` +|Fetch an event by ID within a project, plus the issue ID it belongs to. + +|`resolve_event_id` +|Resolve a bare event ID to its issue and project at organization scope. + +|`get_issue_tag` +|The distribution of one tag (for example, release, environment, browser, or OS) for an issue. + +|`list_issue_tag_values` +|The full set of values behind a tag's capped top values. + +|`list_issue_hashes` +|The issue's grouping hashes. More than one hash means several crash signatures. + +|`get_event_committers` +|The commits and authors Sentry deems most likely responsible (suspect commits). Requires a source-code integration; returns empty when none is configured. + +|`list_releases` +|An organization's releases. Line an issue's first-seen date up against a deploy. + +|`get_release` +|A single release's detail by version. + +|`list_release_commits` +|The commits that shipped in a release (the candidate changes behind a regression). +|=== + +=== Example: List the organizations you can read + +[source,bash] +---- +curl -s https://aigw..clusters.rdpa.co/mcp/v1/acme-sentry \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "jsonrpc": "2.0", + "id": 1, + "method": "tools/call", + "params": { "name": "list_organizations", "arguments": {} } + }' +---- + +Replace `` with your cluster ID and `$TOKEN` with a gateway access token. + +=== Example: Find unresolved issues in a project + +[source,bash] +---- +curl -s https://aigw..clusters.rdpa.co/mcp/v1/acme-sentry \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "jsonrpc": "2.0", + "id": 2, + "method": "tools/call", + "params": { + "name": "list_issues", + "arguments": { + "organization_slug": "my-org", + "project_slug": "web", + "query": "is:unresolved", + "stats_period": "24h" + } + } + }' +---- + +=== Example: Read an issue's latest event and stack trace + +This is the diagnostic step: the latest event carries the exception stack trace the agent reasons over. + +[source,bash] +---- +curl -s https://aigw..clusters.rdpa.co/mcp/v1/acme-sentry \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "jsonrpc": "2.0", + "id": 3, + "method": "tools/call", + "params": { + "name": "get_issue_latest_event", + "arguments": { + "organization_slug": "my-org", + "issue_id": "WEB-1" + } + } + }' +---- + +== Troubleshooting + +Common symptoms and fixes: + +[cols="1,2"] +|=== +|Symptom |What to check + +|`OAuthConnectionRequired` +|First call from a user with no stored token. The user completes Sentry's OAuth consent flow, the token lands in the vault, and subsequent calls reuse it. See xref:connect:user-delegated-oauth.adoc[User-delegated OAuth]. + +|`scope_upgrade_required` +|The server's `required_scopes` was extended after users had already consented. Users re-consent with the higher scope. + +|A request is rejected naming two organization slugs +|The server is confined with `organization_slug` and the call targeted a different organization. Target the pinned organization, or use an unrestricted server. + +|`get_event_committers` returns empty +|Sentry has no source-code integration configured for the project, so it cannot attribute suspect commits. Configure a source-code integration in Sentry. +|=== + +== Limitations + +This page does not cover: + +* *Write operations*: Resolving or ignoring issues, commenting, and managing alerts are deliberately absent. The server is read-only. +* *Self-hosted Sentry*: The server connects to `sentry.io` only. + +== Next steps + +* xref:connect:oauth-providers.adoc[Configure an OAuth Provider] +* xref:connect:user-delegated-oauth.adoc[User-delegated OAuth] +* xref:connect:create-server.adoc[Create an MCP Server] +* xref:connect:test-tools.adoc[Test an MCP Server's Tools with the Inspector] From b22c55c40096e2a53ed8fcc9ac7e3049b03871fb Mon Sep 17 00:00:00 2001 From: micheleRP Date: Fri, 26 Jun 2026 09:03:59 -0600 Subject: [PATCH 2/2] docs(sentry): apply docs-team-standards review fixes Address review suggestions on the Sentry managed MCP server page: drop changeable tool counts, fix orgs->organizations, unbold non-click-target emphasis, make Tools-table descriptions parallel (imperative), reword learning objective 2, expand PII on first use, add a UI-label TODO, link rpk ai in the CLI section, and restructure tool examples under a single H2. Co-Authored-By: Claude Opus 4.8 (1M context) --- modules/connect/pages/managed/sentry.adoc | 48 ++++++++++++----------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/modules/connect/pages/managed/sentry.adoc b/modules/connect/pages/managed/sentry.adoc index 6f96d34..700e3d6 100644 --- a/modules/connect/pages/managed/sentry.adoc +++ b/modules/connect/pages/managed/sentry.adoc @@ -4,7 +4,7 @@ :page-topic-type: how-to :personas: agent_builder, platform_engineer :learning-objective-1: Configure the Sentry managed MCP server with per-user OAuth -:learning-objective-2: Optionally confine the server to a single Sentry organization +:learning-objective-2: Confine the server to a single Sentry organization (optional) :learning-objective-3: Diagnose an issue from the Inspector or an agent, from discovery through to the suspect commit The *Sentry* managed MCP server gives agents read-only access to a Sentry instance: discover organizations and projects, list and read issues, read the events (with stack traces) behind them, scope an error's impact across releases and tags, and surface the commits most likely responsible. The intended use is an agent that reads a Sentry issue and its stack trace to diagnose a bug, then fixes it in the codebase. @@ -17,15 +17,15 @@ After reading this page, you will be able to: == What this MCP server does -Wraps the Sentry REST API and exposes 16 read-only tools grouped by the diagnose-and-fix flow: discover orgs and projects, read the error and its stack trace, scope the impact across tags and releases, and localize the fix to a suspect commit. +Wraps the Sentry REST API and exposes read-only tools grouped by the diagnose-and-fix flow: discover organizations and projects, read the error and its stack trace, scope the impact across tags and releases, and localize the fix to a suspect commit. -Authentication is *per-user OAuth only*. Every tool call runs as the authenticated user against a Sentry OAuth token resolved from the gateway's glossterm:token vault[], so there is no shared service account and each action is attributed to the calling end-user. The server requests only read scopes (`org:read`, `project:read`, `event:read`, `project:releases`). +Authentication is per-user OAuth only. Every tool call runs as the authenticated user against a Sentry OAuth token resolved from the gateway's glossterm:token vault[], so there is no shared service account and each action is attributed to the calling end-user. The server requests only read scopes (`org:read`, `project:read`, `event:read`, `project:releases`). The server is read-only by design: resolving or ignoring issues, commenting, and any other write operation is deliberately absent. Use the Sentry UI or its API directly for those. [NOTE] ==== -Tool output is developer-facing observability data, not PII-safe. The curated event shape omits Sentry's `user` and `request` context, but event `tags` are forwarded verbatim and can carry user-supplied values (for example `user`, `url`, `server_name`, or custom tags), and suspect-commit and release-commit output includes commit author names and email addresses. +Tool output is developer-facing observability data and is not guaranteed to be free of personally identifiable information (PII). The curated event shape omits Sentry's `user` and `request` context, but event `tags` are forwarded verbatim and can carry user-supplied values (for example `user`, `url`, `server_name`, or custom tags), and suspect-commit and release-commit output includes commit author names and email addresses. ==== This MCP server connects to `sentry.io` only. Self-hosted Sentry is not supported. @@ -42,11 +42,11 @@ Before you create the server, make sure you have: Sentry MCP uses per-user OAuth, so you register an OAuth application on Sentry and a matching OAuth Provider in ADP: . In Sentry, go to *Settings > Account > API > Applications* and create a new application. Set the authorized redirect URI to your ADP gateway's OAuth callback. -. Copy the *Client ID* and *Client Secret*, and store the client secret in the ADP secret store. +. Copy the Client ID and Client Secret, and store the client secret in the ADP secret store. . Register a matching OAuth Provider in ADP. See xref:connect:oauth-providers.adoc[Configure an OAuth Provider]. Use Sentry's authorize endpoint (`https://sentry.io/oauth/authorize/`) and token endpoint (`https://sentry.io/oauth/token/`). . Each end-user authenticates once through the OAuth flow; tokens are stored in the gateway's token vault. -*Required scopes*: `org:read`, `project:read`, `event:read`, and `project:releases` cover all tools. `org:read` lists organizations and projects and resolves event IDs; `project:read` lists issues and reads project events and suspect commits; `event:read` reads issue events, tags, and hashes (the stack trace); and `project:releases` reads releases and their commits. All scopes are read-only. +Required scopes: `org:read`, `project:read`, `event:read`, and `project:releases` cover all tools. `org:read` lists organizations and projects and resolves event IDs; `project:read` lists issues and reads project events and suspect commits; `event:read` reads issue events, tags, and hashes (the stack trace); and `project:releases` reads releases and their commits. All scopes are read-only. == Configure @@ -70,9 +70,11 @@ Create a new Sentry MCP server in ADP: + . Click *Create*. +// TODO: confirm the exact UI field labels after an authenticated UI walkthrough; the form may not use the proto field names shown above. + === Configure from the CLI -For a managed server, set the OAuth provider and scopes inside the `--managed-config` JSON. Per-user OAuth is the only supported authentication method. +Use xref:reference:rpk/rpk-ai/rpk-ai.adoc[`rpk ai`] to create the server with a managed config. Set the OAuth provider and scopes inside the `--managed-config` JSON. Per-user OAuth is the only supported authentication method. [tabs] ====== @@ -110,7 +112,7 @@ rpk ai mcp create --name acme-sentry --managed-config '{ == Tools -The Sentry MCP exposes 16 read-only tools, grouped by the diagnose-and-fix flow: +The Sentry MCP exposes read-only tools, grouped by the diagnose-and-fix flow: [cols="1,2"] |=== @@ -129,13 +131,13 @@ The Sentry MCP exposes 16 read-only tools, grouped by the diagnose-and-fix flow: |Fetch issue detail by numeric ID or short ID (for example, `WEB-1`). |`get_issue_latest_event` -|The most recent event for an issue, including its exception stack trace. +|Return the most recent event for an issue, including its exception stack trace. |`list_issue_events` -|The individual occurrences of an issue (compare a failing against a passing event). +|List the individual occurrences of an issue (compare a failing against a passing event). |`get_issue_event` -|One event of an issue with a full stack trace, by ID or the alias `latest`, `oldest`, or `recommended` (`oldest` is the regression boundary). +|Return one event of an issue with a full stack trace, by ID or the alias `latest`, `oldest`, or `recommended` (`oldest` is the regression boundary). |`get_event` |Fetch an event by ID within a project, plus the issue ID it belongs to. @@ -144,28 +146,30 @@ The Sentry MCP exposes 16 read-only tools, grouped by the diagnose-and-fix flow: |Resolve a bare event ID to its issue and project at organization scope. |`get_issue_tag` -|The distribution of one tag (for example, release, environment, browser, or OS) for an issue. +|Return the distribution of one tag (for example, release, environment, browser, or OS) for an issue. |`list_issue_tag_values` -|The full set of values behind a tag's capped top values. +|List the full set of values behind a tag's capped top values. |`list_issue_hashes` -|The issue's grouping hashes. More than one hash means several crash signatures. +|List the issue's grouping hashes. More than one hash means several crash signatures. |`get_event_committers` -|The commits and authors Sentry deems most likely responsible (suspect commits). Requires a source-code integration; returns empty when none is configured. +|Return the commits and authors Sentry deems most likely responsible (suspect commits). Requires a source-code integration; returns empty when none is configured. |`list_releases` -|An organization's releases. Line an issue's first-seen date up against a deploy. +|List an organization's releases. Line an issue's first-seen date up against a deploy. |`get_release` -|A single release's detail by version. +|Return a single release's detail by version. |`list_release_commits` -|The commits that shipped in a release (the candidate changes behind a regression). +|List the commits that shipped in a release (the candidate changes behind a regression). |=== -=== Example: List the organizations you can read +== Tool examples + +List the organizations you can read: [source,bash] ---- @@ -182,7 +186,7 @@ curl -s https://aigw..clusters.rdpa.co/mcp/v1/acme-sentry \ Replace `` with your cluster ID and `$TOKEN` with a gateway access token. -=== Example: Find unresolved issues in a project +Find unresolved issues in a project: [source,bash] ---- @@ -205,9 +209,7 @@ curl -s https://aigw..clusters.rdpa.co/mcp/v1/acme-sentry \ }' ---- -=== Example: Read an issue's latest event and stack trace - -This is the diagnostic step: the latest event carries the exception stack trace the agent reasons over. +Read an issue's latest event and stack trace. This is the diagnostic step: the latest event carries the exception stack trace the agent reasons over. [source,bash] ----