feat(mcp): add HTTP Code Mode with explicit API permissions

docs/cloudflare/architecture.md

@@ -96,6 +96,31 @@ const mcpClient = await experimental_createMCPClient({
 - Prompt metadata endpoint
 - Error handling with fallbacks
 
+### Hosted MCP Code Mode
+
+The authenticated hosted MCP also registers `search_sentry_api` and
+`execute_sentry_code` on the fresh server built for each request. The external
+client's model writes the code; a Cloudflare Dynamic Worker executes it. This
+path does not use the chat interface's model or introduce another OAuth flow.
+
+The Worker Loader binding (`LOADER`) creates an isolated execution with all
+network egress disabled. The trusted sandbox wrapper receives an `ApiBroker`
+capability through its `run()` RPC method and uses it for `sentry.request()`;
+raw `fetch()` is blocked. The broker retains the access token and an
+`ApiAuthorization` object in the parent request context. It checks published
+operations and the explicit API read/write MCP grant, enforces
+organization constraints, resolves validated regional routing and forwards
+client attribution. Generated code cannot access the private token or
+authorization context. Upstream 401s use the existing unauthorized callback.
+
+This integration has no beta or opt-in flag. Code Mode is unavailable for
+project-constrained sessions because arbitrary API operations can affect shared
+resources even through project-bearing routes. Existing grants do not acquire
+API permissions automatically. The shared upstream OAuth token remains separate
+from connection permissions; Sentry enforces its scopes and resource access. See [HTTP Code Mode integration](../testing/code-mode.md#authentication-and-scope)
+for the permission policy, fixture limitations and validation status. Source and
+configuration changes alone do not establish that a deployment is active.
+
 ### 4. AI Assistant
 
 GPT-4 integration with Sentry-specific system prompt:

docs/cloudflare/oauth-architecture.md

@@ -308,6 +308,10 @@ const { redirectTo } = await c.env.OAUTH_PROVIDER.completeAuthorization({
 The system only refreshes MCP tokens. It does not rotate upstream Sentry OAuth
 tokens anymore.
 
+Refresh preserves `upstreamScopes` from the original Sentry token response.
+Older grants and responses that omit `scope` leave this metadata unknown;
+refresh does not infer it from MCP skills or the requested scope set.
+
 1. **MCP Token Refresh**: MCP clients exchange an MCP refresh token for a new MCP access token
 2. **Sentry Token Reuse**: The worker keeps reusing the cached Sentry access token while it is still valid
 3. **Stale grant rejection**: Grants missing required stored props like `refreshToken` are treated as stale and revoked
@@ -420,7 +424,17 @@ remains valid RFC 8414 metadata.
 
 When a constrained OAuth request includes `resource=/mcp/{org}` or
 `resource=/mcp/{org}/{project}`, the approval page surfaces that scope to the
-user as a "Session scope" banner before permissions are granted.
+user before permissions are granted. Organization-only and unconstrained
+connections show an "Organization scope" banner; project-constrained
+connections retain the "Session scope" banner. The unconstrained banner
+explicitly covers all organizations authorized by the upstream token.
+
+New consent forms leave API Write unchecked, while signed remembered selections
+remain preselected for the same client. API Write's warning explains that it is
+an independent, additive permission: it allows API writes even when Triage Issues
+or Manage Projects & Teams is unchecked, subject to Sentry permissions and the
+connection's organization scope. Project-constrained sessions do not offer
+Code Mode skills.
 
 Note: These describe the MCP OAuth server, not Sentry's OAuth endpoints.
 

docs/integrations/claude-code-plugin.md

@@ -63,26 +63,28 @@ The body below the frontmatter is the agent's system prompt.
 
 ## Keeping `allowedTools` in Sync
 
-The `allowedTools` list in the agent frontmatter must match the generated default-grant direct MCP surface. The `generate-definitions` script handles this automatically:
+The `allowedTools` list in the agent frontmatter must match the generated default-grant direct MCP surface, including the hosted `search_sentry_api` and `execute_sentry_code` tools. Their availability and write permissions still depend on the connection's existing grant and constraints. The `generate-definitions` script handles this automatically:
 
 ```bash
 pnpm run --filter @sentry/mcp-core generate-definitions
 ```
 
+The public `/.mcp/tools.json` metadata includes the same hosted definitions. Code Mode has no fixed tool-level API scopes (`requiredScopes: []`): each HTTP operation is authorized against the connection's permissions and organization constraint before the request is sent.
+
 This script:
 
 1. Imports all tools from `packages/mcp-core/src/tools/index.ts`
 2. Imports all skills from `packages/mcp-core/src/skills.ts`
 3. Writes `toolDefinitions.json` and `skillDefinitions.json` to `packages/mcp-core/src/`
-4. Updates `allowedTools` in both `plugins/sentry-mcp/agents/sentry-mcp.md` and `plugins/sentry-mcp-experimental/agents/sentry-mcp.md`, using the default-grant direct surface for each plugin mode. Optional-skill tools remain reachable through `search_sentry_tools` and `execute_sentry_tool` when available.
+4. Updates `allowedTools` in both `plugins/sentry-mcp/agents/sentry-mcp.md` and `plugins/sentry-mcp-experimental/agents/sentry-mcp.md`, using the default-grant direct surface for each plugin mode plus hosted Code Mode names from `packages/mcp-cloudflare/src/code-mode/definitions.ts`. These hosted tools are not added to core/stdio JSON definitions. Optional-skill tools remain reachable through `search_sentry_tools` and `execute_sentry_tool` when available.
 
 The script runs automatically as a `prebuild` and `pretest` hook in `packages/mcp-core/package.json`. Run it explicitly after:
 
 - Adding, removing, or renaming tools
 - Changing tool skills assignments
 - Modifying agent prompts (to verify frontmatter stays valid)
 
-The script skips regeneration if all outputs are newer than all inputs (tool source files, `skills.ts`, and the script itself).
+The script skips regeneration if all outputs are newer than all inputs (tool source files, hosted Code Mode definitions, `skills.ts`, and the script itself).
 
 ## Modifying the Agent Prompt
 

docs/mcp/README.md

@@ -17,6 +17,8 @@ them. The [Toolkit index](../README.md) also links the CLI and shared guides.
   [error handling](../contributing/error-handling.md) — MCP client conventions.
 - [Testing](../testing/overview.md), [stdio](../testing/stdio.md), and
   [remote](../testing/remote.md) — tests and transport QA.
+- [HTTP Code Mode](../testing/code-mode.md) — runtime integration, permissions,
+  and safety validation.
 
 ## Run and Release
 

docs/operations/security.md

@@ -104,10 +104,12 @@ Today, runtime authorization for remote HTTP sessions is driven primarily by:
 
 `grantedScopes` still exists on tokens for backward compatibility with older
 clients, but it is transitional. Skills are the primary authorization model.
-Note that `grantedScopes` is derived from the selected skills, not from what
-Sentry granted. The scopes Sentry actually granted on the upstream token (from
-the `scope` field of Sentry's token response) are stored separately as
-`upstreamScopes`. Grants created before `upstreamScopes` existed do not have it.
+`grantedScopes` is derived from selected skills, not from what Sentry granted.
+The token response's actual `scope` is stored separately as `upstreamScopes`.
+Older grants and responses without `scope` leave `upstreamScopes` undefined,
+which means unknown rather than no permissions. MCP refresh preserves that
+metadata without requesting or inferring additional scopes. It does not grant
+the MCP session permission to use every capability of the upstream token.
 
 Direct `Sentry-Bearer` sessions default to all active skills and can be narrowed
 with `skills` or `disable-skills` query parameters. They do not get OAuth