diff --git a/openspec/changes/cli-first-mcp/.openspec.yaml b/openspec/changes/cli-first-mcp/.openspec.yaml
new file mode 100644
index 000000000..ac359ee85
--- /dev/null
+++ b/openspec/changes/cli-first-mcp/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-11-03
diff --git a/openspec/changes/cli-first-mcp/design.md b/openspec/changes/cli-first-mcp/design.md
new file mode 100644
index 000000000..9c88b5d99
--- /dev/null
+++ b/openspec/changes/cli-first-mcp/design.md
@@ -0,0 +1,466 @@
+# Design
+
+## Context
+
+- The CLI's command tree is introspectable at runtime (`lib/introspect.ts`,
+  `sentry help --json`) and at build time (`generate-skill.ts`,
+  `generate-command-api.ts`). `src/generated/command-api.json` records which
+  API operations each command calls, and commands declare `destructive`
+  (`lib/command.ts`).
+- `createSentrySDK()` (`src/index.ts`, `lib/sdk-invoke.ts`) calls command
+  handlers directly with typed flags and returns their data, buffering
+  commands that yield more than once. It takes a token, URL, org, project,
+  and `cwd` per instance, and scopes the environment per call with
+  `AsyncLocalStorage` (`lib/env.ts`).
+- The CLI's local state goes through one synchronous SQLite adapter
+  (`lib/db/sqlite.ts`: `node:sqlite` `DatabaseSync`, or a WASM fallback),
+  opened as a module-level singleton by `getDatabase()` in 23 files. A
+  `detached` mode already uses an in-memory database.
+- In `commands/` and `lib/`, 156 files import `node:` modules. The most
+  common are `path`, `fs`, `fs/promises`, `os`, `child_process` (23 files),
+  `tty` (14), and `crypto`.
+- `sentry schema` (`commands/schema.ts`, `lib/api-schema.ts`) searches the
+  published API index from `@sentry/api`, and `sentry api` sends any
+  request.
+- Shell completion is declared for every positional and flag (#1751, #1759)
+  and completes dataset fields and aggregates (#1782). Completers read the
+  SQLite completion cache, warmed at login (#1788, #1789).
+- HTTP Code Mode (#1670, evals in #1675) runs agent JavaScript in a
+  Cloudflare Dynamic Worker with no token and no network. A broker in the
+  parent Worker checks each request against the shipped operation list and
+  the connection's API Read or API Write grant.
+- The hosted MCP runs on Cloudflare Workers (`compatibility_date`
+  2025-03-21, with KV and no Durable Objects or D1 today). CLI command
+  handlers do not run there yet.
+
+## Goals / Non-Goals
+
+Goals:
+
+- One product surface: CLI commands. The MCP adds no Sentry logic of its own.
+- Agents can do anything a command can, plus any published API operation.
+- The same discovery, completion, and permission rules on stdio and hosted.
+
+Non-goals:
+
+- Running commands that need the user's machine on Workers: local files,
+  child processes, the terminal.
+- Changing the hosted MCP's OAuth flow or moving it off Workers.
+- A code-execution sandbox. Code Mode (#1670) can come later as an extra
+  tool over the same SDK.
+- Keeping the catalog's agent-tuned output formats. Commands return data,
+  and can return their own markdown rendering where that helps.
+
+## Decisions
+
+### Commands are the only product surface
+
+A capability an agent needs is a CLI command, built on `@sentry/api`. The
+MCP gets no new hand-written tools; pending tool PRs (for example #1846,
+#1837, #1517) become commands. Fixes to existing catalog tools are fine until
+the cutover, since they ship to users now.
+
+### CLI parity inventory
+
+From a listing of `mcp-core/src/tools/catalog/` against
+`cli/src/commands/` (by name and brief, not by behavior; each row is checked
+when its command lands):
+
+| MCP catalog tools                                                                                    | CLI today                                                          | Gap                                                            |
+| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------- |
+| `whoami`, `find_organizations`, `find_projects`, `find_teams`, `find_dsns`                           | `auth whoami`, `org list`, `project list`, `team list`, `dsn list` | none                                                           |
+| `create_project`                                                                                     | `project create`                                                   | none                                                           |
+| `update_project`                                                                                     | none                                                               | `project edit`                                                 |
+| `create_team`, `add_team_to_project`, `remove_team_from_project`                                     | none                                                               | `team create`, `project team add/remove`                       |
+| `create_dsn`, `update_dsn`                                                                           | none                                                               | `dsn create`, `dsn edit`                                       |
+| `search_issues`, `get_issue_details`, `search_issue_events`, `get_issue_tag_values`                  | `issue list/view/events/tags`                                      | none                                                           |
+| `update_issue`                                                                                       | `issue resolve/unresolve/archive`                                  | assignment: `issue assign`                                     |
+| `add_issue_note`, `get_issue_activity`                                                               | none                                                               | `issue comment`, `issue activity`                              |
+| `get_issue_breadcrumbs`, `get_issue_user_reports`                                                    | partly in `event view`, `feedback list`                            | check, then flags or commands                                  |
+| `link_issue`, `unlink_issue`, `analyze_issue_with_seer`                                              | `issue link/unlink/explain/plan`                                   | none                                                           |
+| `get_event_stacktrace`                                                                               | `event view`                                                       | none                                                           |
+| `get_event_attachment`                                                                               | none                                                               | `event attachment list/download`                               |
+| `search_events`, `search_errors`, `search_logs`, `search_traces`, `search_metrics`, `search_replays` | `event list`, `explore`, `log list`, `trace list`, `replay list`   | metrics dataset to check; no natural-language mode (see below) |
+| `get_trace_details`, `get_span_details`, `get_replay_details`                                        | `trace view`, `span view`, `replay view`                           | none                                                           |
+| `search_profiles`, `get_profile`, `get_profile_details`                                              | none                                                               | `profile list/view`                                            |
+| `search_attributes`                                                                                  | `attribute list`                                                   | none                                                           |
+| `search_agent_conversations`, `get_agent_conversation_details`                                       | `agent-conversation list/view`                                     | none                                                           |
+| `find_dashboards`, `get_dashboard_details`                                                           | `dashboard list/view`                                              | none                                                           |
+| `find_releases`, `get_release_details`                                                               | `release list/view`                                                | none                                                           |
+| alert rule and metric monitor CRUD, `get_alert_options`                                              | `alert issues ...`, `alert metrics ...`                            | `get_alert_options` to check                                   |
+| `find_monitors`, `get_monitor_details`, `delete_monitor_environment`                                 | `monitor list`                                                     | `monitor view`, `monitor env delete`                           |
+| uptime monitor CRUD (5 tools)                                                                        | none                                                               | `monitor uptime list/view/create/edit/delete`                  |
+| `find_dropped_events`                                                                                | none                                                               | `event dropped` or similar (#1812 open)                        |
+| `get_snapshot`, `get_latest_base_snapshot`, `get_snapshot_image`                                     | `snapshots download/diff`                                          | read commands to check                                         |
+| `get_sentry_resource`                                                                                | URL positionals on most commands                                   | a generic `sentry open <url>` resolver                         |
+| `search_docs`, `get_doc`, `submit_feedback_to_sentry_team`                                           | `docs list/query`, `cli feedback`                                  | none                                                           |
+| `get_sentry_mcp_info`, `onboarding_status_update`                                                    | MCP-specific                                                       | keep as host functions or drop                                 |
+
+About 20 tools have no command yet, and a few more are partial. Each gap
+is a command PR, grouped by domain.
+
+### One tool per command
+
+Each exposed command is its own MCP tool, named from its path
+(`sentry issue list` → `sentry_issue_list`). Its description is the
+command's brief and examples, and its input schema is the catalog's
+`{ positional, flags }` JSON Schema. There is no `search_sentry` and no
+`execute_*` meta-tool: the CLI has well over 100 leaf commands, and the
+harnesses we target search large tool lists themselves (deferred loading,
+native tool search; see `docs/mcp/harnesses.md`). A search tool of our own
+would duplicate that search and put a dispatch hop in front of every call.
+
+Each tool:
+
+1. validates its arguments against the command's schema; an invalid slug,
+   enum value, flag, or query key fails with the allowed values or
+   completion candidates in the error;
+2. checks the session's constraints and, for `sentry api`, the permission
+   class of the call;
+3. calls the command through `createSentrySDK()` and returns its JSON data,
+   size-capped (still valid JSON when cut), with the next cursor for
+   paginated commands. A `format: "markdown"` argument can return the
+   command's plain markdown output instead, for commands whose terminal
+   rendering already summarizes well, such as `issue view` or
+   `trace view` (#1892).
+
+Commands that yield more than once are buffered into one result, as the
+SDK does today. Streaming flags (`--follow`, tail) are rejected, and so are
+flags that take a local path and `--web`.
+
+**Annotations come from the permission class.** MCP hosts allowlist and
+render approvals by tool name (#1254), so per-command tools give hosts the
+finest grain there is: read commands carry `readOnlyHint: true`, write and
+destructive commands carry `destructiveHint: true`, and a host can auto-run
+`sentry_issue_list` and ask before `sentry_project_delete`. `sentry api`
+takes its class from each call's `--method`, and no per-call hint exists, so
+it is one tool marked destructive; splitting it into GET and non-GET tools
+would add a tool without changing what a host can allowlist. A read-only
+connection (`--read-only`, hosted API Read) lists no write tools, and marks
+`sentry api` read-only while refusing every method but GET, HEAD, and
+OPTIONS.
+
+The schema is listed as is: the tools attach it as metadata to permissive
+Zod types, so `tools/list` shows the catalog's JSON Schema, the MCP SDK
+fills in no defaults, and the tool's own validator returns the errors.
+
+#### How this differs from Code Mode
+
+Code Mode (Cloudflare's term, and #1670) hides tools behind search and
+execute, and its execute tool takes a program: the model writes JavaScript
+that calls several operations, loops, and filters, and only the program's
+result goes back into context. That code is arbitrary, so it needs a sandbox.
+
+The command tools run one known command per call. The agent cannot
+run anything that is not a command, and the parameters are validated data,
+so there is nothing to sandbox. The cost is that multi-step work takes one
+model turn per call, and intermediate results pass through context. Command
+flags (`--limit`, `--fields`, queries) and `format` keep results small.
+If evals show multi-step tasks need it, Code Mode can be added later as a
+tool whose `sentry` object calls the same execution path, permission checks
+included.
+
+### What is exposed
+
+Every command declares how agents may use it, and a lint check fails when a
+command has no declaration:
+
+- **exposed**: available on stdio and hosted, once the hosted SDK build can
+  run it.
+- **stdio-only**: needs the user's machine: local files (uploads,
+  `sourcemap inject`, `debug-files`, `init`), DSN detection from the `cwd`,
+  or the terminal.
+- **hidden**: never exposed: session management (`auth login`,
+  `auth logout`), CLI maintenance (`cli upgrade`, `cli setup`,
+  `cli uninstall`), `local`, and `monitor run`, which runs an arbitrary
+  child process.
+
+### The CLI SDK on Workers, without persistence
+
+The hosted MCP runs commands through `createSentrySDK()` too, rather than
+through a second, portable copy of each command. The hosted MCP's Hono app
+creates one SDK instance per request, with the token from the OAuth grant
+and the org and project from the session constraints.
+
+**No persistence.** Everything the CLI persists is for a long-lived,
+single-user install: stored accounts and tokens, defaults, release channel
+and version checks, pagination cursor stacks, and caches (projects, DSNs,
+aliases, regions, repos, issue orgs, completion values, project roots, the
+response cache). A server needs none of it. The SDK already takes a token
+(`createSentrySDK({ token })` sets `SENTRY_AUTH_TOKEN` and
+`SENTRY_FORCE_ENV_TOKEN` for that invocation), and with an env token the
+auth code never reads the `accounts` table. So hosted runs the SDK with
+persistence off:
+
+- `getDatabase()` callers (23 files, 20 of them in `lib/db/`) get a null
+  store: reads miss and writes do nothing. An in-memory SQLite database is
+  not an option, since workerd has no SQLite driver for the CLI's adapter.
+- The response cache, `.sentryclirc` and config-directory reads, custom CA
+  and header files, version checks, and telemetry state are off.
+- Pagination is stateless. List commands already return `nextCursor` in
+  their JSON envelope and accept a raw cursor, so hosted rejects the
+  `next`/`prev` keywords, which need the stored cursor stack, and the
+  agent passes the cursor it got back.
+- Org-to-region lookups happen on every call that needs them. If that
+  latency matters, an in-memory cache keyed by token fingerprint comes
+  later, measured first.
+
+D1, R2, and Durable Object storage are not needed. Commands that read or
+write local files are stdio-only.
+
+**Per-request state.** One SDK instance per request isolates what lives in
+the instance and in `withEnv()`'s `AsyncLocalStorage`, but not module
+scope: a Workers isolate reuses its modules across concurrent requests. The
+auth path is already per invocation (token memos are keyed by the
+invocation's env, and env tokens skip stored accounts). Some module-level
+state is not, for example `regionCache` in `lib/region.ts` (keyed by org
+slug only), `loginTrustAnchor` in `lib/token-host.ts`, and the cached
+headers in `lib/custom-headers.ts`. With persistence off, the work is to
+audit module-level state on the exposed commands' import graph and either
+scope each item to the invocation or turn it off on hosted. The
+sequential token reuse in #1391 is already fixed on `main` (token memos
+are keyed by the invocation's env); #1427 gives the remaining state
+invocation, request, and session lifetimes and is the starting point. A test runs
+two identities concurrently in one isolate and checks that neither sees
+the other's credentials, constraints, or results.
+
+**Node built-ins.** `nodejs_compat` provides `path`, `crypto`, `util`,
+`zlib`, `async_hooks`, and timers. It does not provide `child_process`,
+`tty`, or an HTTP server, and its `fs` is an in-memory file system that
+needs a newer compatibility date than the hosted MCP uses (see the spike
+results below). What matters is
+what the exposed commands import transitively, which only a build answers.
+So the first task is a spike: bundle the SDK for workerd with the exposed
+commands, and list what fails to bundle or run, and the bundle size against
+the Workers script limit.
+
+Commands whose imports cannot be made Workers-safe are marked stdio-only
+until fixed. If a whole domain is blocked, that domain's commands split into
+input resolution and a portable operation (the old
+`unify-sentry-api-layer` 11.1), for that domain only.
+
+#### Spike results (#1882)
+
+A throwaway worker imported `createSentrySDK()` and ran 12 command calls
+against a mocked Sentry API with a synthetic token, under `wrangler dev`
+(wrangler 4.151.3, workerd 1.20261019.1, `nodejs_compat` and
+`nodejs_compat_populate_process_env`). SQLite was swapped for a null store
+at bundle time. The same harness passes every call on Node.
+
+**It runs.** With the small fixes in the table, `org list`, `project list`,
+`issue list`, `issue view`, `event view`, `trace view`, `api`, `schema`,
+`issue resolve`, and `run("issue", "list")` all pass, on a fresh isolate
+and on a warm one.
+
+**Bundling.** wrangler alone fails on one module: `lib/init/ui/ink-ui.ts`
+imports the Ink sidecar `with { type: "file" }`, which esbuild rejects.
+`ROUTE_LOADERS` imports every command, so `init` is in the graph even when
+only `issue list` is called. Bundling first with the CLI's esbuild plugins
+(text imports, `_require` aliasing, zod stubs) and then with wrangler works.
+The result is the whole CLI.
+
+**Size.** 6,971 KiB raw, 1,989 KiB gzip (`wrangler deploy --dry-run
+--minify`). The hosted MCP today is 5,092 KiB raw, 975 KiB gzip. The
+Workers limit is 64 MiB uncompressed, with no compressed limit, so size is
+not a blocker. Code hosted never runs is about half the bundle:
+highlight.js and parse5 (~1.2 MB), `sentry mcp`'s server stack (~1.2 MB,
+partly shared with the hosted worker), `init` (Mastra, AI SDK, Clack,
+~0.75 MB), and `@sentry/node` with its dependencies (~0.5 MB).
+
+**Startup.** `wrangler check startup` measured about 65 ms of startup CPU
+locally, mostly parse and compile; the limit is 1 s. Modules initialize on
+first use, so the first call in a fresh isolate took 155-215 ms against the
+mock, and the same calls warm took 6-28 ms.
+
+**Compatibility date.** Every call fails on 2025-03-21 (hosted today) and on
+every date tried up to 2026-01-01: pngjs, reached from `lib/sixel-image.ts`
+through the chart formatters, calls `util.inherits` on a `stream` class the
+older polyfills lack. Calls pass from 2026-01-28 on. Hosted moves to a 2026
+compatibility date, or the image code loads lazily.
+
+| Failure                                                                             | Where                                                                                                 | Hit by                                     | Fix                                                              | Size  |
+| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------- | ----- |
+| `createRequire(import.meta.url)` throws; workerd leaves `import.meta.url` undefined | 11 modules at load (`db/*`, `telemetry`, `custom-ca`, `formatters/*`, `dif`, `sea-assets`, `init/ui`) | every call                                 | define `import.meta.url` at build                                | small |
+| `Dynamic require of "util" is not supported`                                        | CommonJS dependencies in the ESM output                                                               | every call                                 | a `createRequire` banner, as the npm ESM bundle has              | small |
+| top-level `readFileSync` of `assets/spleen-8x16.bin`                                | `formatters/spleen-font.ts`                                                                           | every call                                 | load the glyphs on first use, or embed them                      | small |
+| a null store whose reads return `null` breaks schema setup (`row.count`)            | `db/schema.ts` through `getDatabase()`                                                                | calls that open the database (`api` first) | no-persistence mode skips database setup, not only reads (#1897) | small |
+| `superCtor.prototype` must be an object                                             | pngjs on dates before 2026                                                                            | every call                                 | 2026 compatibility date, or lazy image code                      | small |
+
+**Other findings.**
+
+- `withEnv()`'s `AsyncLocalStorage` works on workerd. Two tokens, three
+  concurrent `issue list` calls each, in one isolate: every request
+  carried only its own token.
+- Environment inheritance is a correctness bug on hosted.
+  `buildIsolatedEnv()` copies `process.env`, which on Workers holds the
+  worker's vars and secrets (`SENTRY_DSN`, `SENTRY_CLIENT_SECRET`,
+  `COOKIE_SECRET`, provider keys). With the worker's `SENTRY_DSN` set,
+  `issue list` with no target resolved to that DSN's org and project. The
+  SDK needs an option to start from an empty env; small.
+- Library-mode telemetry initializes `@sentry/node` and posts envelopes to
+  the CLI's own DSN (18 for 12 calls). Hosted turns it off; small.
+- `node:fs` is workerd's virtual file system. `homedir()` and `tmpdir()`
+  are `/tmp`, which lasts one request, so config-directory writes succeed
+  and vanish. The current directory is `/bundle`, the worker's own code:
+  `api --input /bundle/<script> --dry-run` returns the bundle as the
+  request body. Hosted rejects path-taking flags.
+- `node:sqlite` exists, but `DatabaseSync` is not constructible, so there
+  is no SQLite on workerd. `child_process` throws
+  `ERR_METHOD_NOT_IMPLEMENTED`; `tty.isatty()` returns `false`.
+- `issue resolve --in @commit` fails cleanly (it runs `git`); the explicit
+  `@commit:<repo>@<sha>` form does not need it.
+- `trace view` fetches span details one request per span (853 for the
+  largest fixture, on Node). That stays under the 10,000-subrequest limit,
+  but with 6 connections per request, large traces are slow on hosted.
+
+**Stdio-only, from the spike.** In addition to the list in "What is
+exposed": `react-native xcode` (it spawns processes), the `api --input`
+flag, and the bare `--in @commit` value of `issue
+resolve`. Commands that fall back to DSN detection need an explicit org
+and project on hosted, from the session constraints.
+
+**What is left, ranked.**
+
+- Small: the five fixes in the table, an SDK option for an empty env,
+  telemetry off on hosted, rejecting path-taking flags, and the
+  compatibility date bump (check the rest of the hosted worker on it).
+- Structural: a hosted entry point whose route loaders cover only exposed
+  commands, which drops the Ink import (so wrangler bundles it directly)
+  and about half the bundle; the no-persistence mode (#1897); and the
+  module-level state audit (#1427), of which the spike checked only the
+  token.
+
+### One introspection source
+
+The build generates the route tree's metadata (`lib/introspect.ts`) as JSON
+(`command-catalog.json`: commands, JSON Schema for parameters, completion
+kinds, examples, output fields, the API operations from `command-api.json`,
+the permission class, and the exposure). Both `sentry mcp` and the hosted
+MCP build their tools from it, so `sentry mcp` never loads the whole command
+tree to list tools (#1918). A test fails when the catalog and the route
+tree differ.
+
+### API routes through `sentry api` and `sentry schema`
+
+`sentry schema` and `sentry api` are exposed commands, so agents search the
+published API with `sentry_schema` and call any published operation with
+`sentry_api`. The permission class of a
+`sentry api` call comes from its method, and hosted checks the path against
+the published operation list with #1807's shared matcher, as #1670's broker
+does. `sentry schema`'s index moves onto `@sentry/api`'s operation catalog
+(`@sentry/api/operations`). Endpoints missing from the published schema
+are the main gap, and `unify-sentry-api-layer` 8.8 handles them.
+
+### Completion for agents
+
+Completers in `lib/complete.ts` read the SQLite completion cache. They are
+split into completers over a data source:
+
+- **stdio:** the SQLite cache, as for the shell, with a live API fallback.
+- **hosted:** the live API, uncached.
+
+There is no completion tool. Completion reaches agents two ways:
+
+- **Schema `examples`.** The catalog puts static suggestions (sort orders,
+  datasets, cursor keywords) in each parameter's JSON Schema `examples`,
+  which every tool lists.
+- **Validation errors.** A call with an invalid value fails with candidates
+  for the parameter in question: the allowed values or flags today, and,
+  once the completers are wired in (#1895), slugs, issue IDs, dataset fields
+  and aggregates, and search query keys and values, with descriptions.
+
+This is how agents build valid queries without the catalog's embedded
+search agents.
+
+### Embedded natural-language search agents are dropped
+
+`search_events`, `search_issues`, and `search_issue_events` translate
+natural language with a second model call. Under this plan the calling agent
+writes the query itself, using the query syntax in the command tool's
+description and completion for keys and values. Dropping them
+removes the MCP's OpenAI and Anthropic provider configuration (#1754 becomes
+moot).
+
+### Permissions are command metadata
+
+Each command gets a permission class from its API operations in
+`command-api.json`: **read** if it calls only GET, HEAD, or OPTIONS;
+otherwise **write**; and **destructive** if it declares `destructive`. A
+lint check fails when the class is missing or disagrees with the operations.
+
+- Hosted consent keeps #1670's API Read and API Write grants. API Read
+  allows read commands; API Write allows write and destructive commands.
+  The existing skill checkboxes (Triage Issues, Manage Projects & Teams, and
+  so on) map to command groups until consent is simplified.
+- Organization and project constraints from the session (`sentry mcp
+  <org>/[<project>]`, hosted URL constraints) fill and pin command
+  parameters; a call for another organization is refused.
+- stdio adds `--read-only`, matching hosted API Read.
+
+### `@sentry/mcp-server` needs the exposed commands
+
+The slim bundle (#1731) bans command handlers and has a 3.75 MB budget.
+Under this plan it must carry the exposed command handlers, since that is
+what its tools run. It bundles them with the SDK and keeps banning the
+stdio-only and hidden commands, Ink, the terminal markdown renderer, and
+SQLite WASM. The budget is re-measured. The package stays; whether installs
+move to `npx sentry mcp` later is out of scope here.
+
+### Eval-gated cutover
+
+The command surface ships next to the catalog:
+
+1. Extend #1675's harness to run the full `mcp-server-evals` suite on the
+   catalog and the command tools.
+2. Make the command surface the default when it matches or beats the
+   catalog on task success, and record token cost and turn count next to
+   it. Run more than one client and model.
+3. Keep the catalog behind a flag (`--catalog`, a hosted skill) for one
+   release.
+4. Delete the catalog tools, their `SentryApiService` endpoint wrappers,
+   the search agents, and the provider configuration from `mcp-core`.
+
+## Risks / Trade-offs
+
+- **More turns than Code Mode** for multi-step tasks. The evals record turn
+  count; Code Mode stays available as a later addition.
+- **Output quality.** Catalog tools format stack traces, traces, and issue
+  summaries for agents. `format: "markdown"` reuses the CLI's renderers; the
+  evals check the gap.
+- **Cross-user leaks on hosted.** With persistence off, the remaining risk
+  is module-level state shared by concurrent requests in one isolate. The
+  concurrent two-identity test is required before hosted serves any
+  command.
+- **Extra round trips on hosted.** Without caches, region and slug
+  resolution hit the API on every call. Measure before adding a cache.
+- **Workers compatibility.** Unknown until the spike. Commands that fail
+  stay stdio-only, so hosted coverage can lag stdio.
+- **Harnesses without tool search.** Every exposed command is listed:
+  81 tools and about 35,500 tokens of definitions today (#1890), against
+  about 46,900 for the catalog's 73 tools. Harnesses that load every tool
+  pay that up front; `--read-only` cuts it to 49 tools.
+- **Tool descriptions come from CLI help text.** Weak help text makes weak
+  tools. Improving it improves both the CLI and the MCP.
+- **Unpublished endpoints.** Commands and `sentry api` can only reach what
+  `@sentry/api` covers. See `unify-sentry-api-layer`.
+
+## Migration Plan
+
+0. Move the shared client into `@sentry/api` and switch toolkit to it
+   (`unify-sentry-api-layer` 8.5, 8.6), then release (8.10).
+1. Command metadata (permission class, exposure, generated catalog) and the
+   parity commands, by domain.
+2. Command tools on stdio over `createSentrySDK()`, behind a flag, with
+   completion through validation errors.
+3. The Workers spike, then a no-persistence mode and the module-state
+   audit, then hosted on the SDK.
+4. Eval gate, default flip, catalog deletion.
+
+**Rollback:** until the catalog is deleted, the flag switches back. After
+that, a revert of the deletion PR restores it.
+
+## Open Questions
+
+- Whether `get_sentry_mcp_info` and `onboarding_status_update` survive.
+- When to simplify hosted consent from skill checkboxes to API Read, API
+  Write, and destructive.
diff --git a/openspec/changes/cli-first-mcp/proposal.md b/openspec/changes/cli-first-mcp/proposal.md
new file mode 100644
index 000000000..814965a65
--- /dev/null
+++ b/openspec/changes/cli-first-mcp/proposal.md
@@ -0,0 +1,88 @@
+# Proposal
+
+## Why
+
+Sentry's product logic for agents lives in two places. The CLI has about 40
+command groups built on `@sentry/api`. The MCP server has 75 hand-written
+catalog tools in `mcp-core/src/tools/catalog/`, with their own endpoint
+wrappers (`mcp-core/src/api-client/client.ts`, about 5,000 lines), their own
+Zod output formatting, and embedded natural-language search agents that need
+an OpenAI or Anthropic key. Every capability is built twice, or exists in
+only one product.
+
+The earlier plan (`unify-sentry-api-layer`, group 11) kept both surfaces and
+moved each MCP tool into the CLI as a portable tool definition. That still
+means one hand-written MCP tool per command.
+
+If the CLI is the only product surface, the MCP can be a thin layer that
+exposes the CLI's commands as tools, found through the CLI's own
+introspection and run through the CLI SDK.
+
+## What Changes
+
+1. **CLI parity.** Every MCP catalog tool gets a CLI command. New Sentry
+   capabilities are added as CLI commands only; no new hand-written MCP
+   tools. Commands call the API through `@sentry/api`
+   (`unify-sentry-api-layer`).
+2. **The MCP exposes the CLI's commands.** Each exposed command is its own
+   tool (`sentry_issue_list`), run with JSON parameters through
+   `createSentrySDK()`. There are no search or execute meta-tools:
+   harnesses search large tool lists themselves. Each tool carries its
+   command's permission class as hints, so MCP hosts can allowlist reads
+   and ask before writes (#1254). No sandbox is involved: the agent can
+   only run commands that exist, with parameters their schema accepts.
+3. **One introspection source.** Tool names, descriptions, and input schemas
+   come from metadata generated from the CLI's route tree
+   (`lib/introspect.ts`) at build time, on stdio and hosted.
+4. **Every published API route.** `sentry api` and `sentry schema` are
+   commands like any other, so their tools reach every published
+   `@sentry/api` operation with no extra tool.
+5. **Completion for agents.** The shell completion system
+   (`lib/complete.ts`, `lib/completion-target.ts`) suggests values when a
+   parameter fails validation, next to the static suggestions in each
+   parameter's schema `examples`: organization and project slugs, issue IDs, dataset fields
+   and aggregates, and search query terms.
+6. **The CLI SDK runs on the hosted MCP.** Hosted creates one SDK instance
+   per request with the OAuth grant's token and runs it with persistence
+   off: no SQLite, no config directory, no caches. Module-level state on
+   the exposed commands' import graph becomes per-request. The hosted MCP
+   then runs commands through the same SDK as `sentry mcp`.
+7. **The catalog goes away after an eval gate.** The command surface ships
+   next to the catalog. When the MCP eval suite shows it matching the
+   catalog, it becomes the default, and the catalog tools, their endpoint
+   wrappers, and the embedded search agents are deleted from `mcp-core`.
+
+HTTP Code Mode (#1670), where the agent writes JavaScript that a sandbox
+runs, is not part of this plan's critical path. It can be added later as a
+tool over the same SDK, for multi-step work that benefits from code.
+
+## Capabilities
+
+### New Capabilities
+
+- `mcp-command-surface`: The MCP's tool surface: discovery, execution,
+  permissions, and completion over the CLI's commands.
+
+### Modified Capabilities
+
+None. The project-management tool contract in
+`refine-project-management-tools` is superseded: those operations become CLI
+commands.
+
+## Impact
+
+- `packages/cli`: new commands for the parity gaps; agent metadata on
+  commands (permission class, hosted availability); a no-persistence
+  mode; per-request SDK state; a Workers build of the SDK.
+- `packages/mcp-core`: keeps MCP plumbing (registration, transports,
+  constraints, the command tool definitions). Loses the catalog tools, the
+  `SentryApiService` endpoint wrappers they use, the search agents, and the
+  agent provider configuration.
+- `packages/mcp-cloudflare`: runs commands through the CLI SDK, one
+  instance per request, with persistence off. OAuth consent maps to command permission classes.
+- `packages/mcp-server`: the slim bundle needs the command handlers it
+  exposes; its module guard and size budget change.
+- `packages/mcp-server-evals`: command-surface and catalog runs of the full
+  suite, then the command surface only.
+- Docs: mcp.sentry.dev setup, `docs/` architecture pages, and the agent
+  skills (#1357 skills audit).
diff --git a/openspec/changes/cli-first-mcp/specs/mcp-command-surface/spec.md b/openspec/changes/cli-first-mcp/specs/mcp-command-surface/spec.md
new file mode 100644
index 000000000..fd58b3cc2
--- /dev/null
+++ b/openspec/changes/cli-first-mcp/specs/mcp-command-surface/spec.md
@@ -0,0 +1,120 @@
+# Spec Delta
+
+## Purpose
+
+Defines the MCP's tool surface as the CLI's commands: one tool per exposed
+command, how a call runs, what each connection may do, and how completion
+helps agents build valid calls.
+
+## ADDED Requirements
+
+### Requirement: Commands are the product surface
+
+Every Sentry capability the MCP offers SHALL be a CLI command. The MCP SHALL
+NOT define Sentry operations of its own.
+
+#### Scenario: A new capability
+
+- **WHEN** a Sentry capability is added for agents
+- **THEN** it is added as a CLI command
+- **THEN** it is listed as an MCP tool with no MCP code change
+
+### Requirement: One tool per exposed command
+
+The MCP SHALL list one tool per exposed command, named from the command's
+path, with the command's brief and examples as its description and the
+command's parameters as its input schema, from the CLI's introspection
+metadata. It SHALL NOT add search or execute meta-tools; harnesses search
+the tool list themselves. The hosted server SHALL read the generated
+catalog, and SHALL list only commands its build can run.
+
+#### Scenario: Tool list matches the catalog
+
+- **WHEN** a connection lists tools
+- **THEN** the list has one tool per exposed command, such as `sentry_issue_list` for `sentry issue list`
+- **THEN** each tool's input schema is the command's `{ positional, flags }` JSON Schema
+- **THEN** the list has no `search_sentry`, `execute_sentry_read`, or `execute_sentry_write`
+
+### Requirement: Execution runs only exposed commands
+
+Command tools SHALL run only commands marked exposed, with parameters that
+validate against the command's schema, through the CLI SDK. They SHALL NOT
+run arbitrary code.
+
+#### Scenario: Hidden command
+
+- **WHEN** a connection lists tools
+- **THEN** there is no tool for `monitor run`, a hidden command
+
+#### Scenario: Invalid parameter value
+
+- **WHEN** an agent passes an organization slug that does not exist
+- **THEN** the call fails with the allowed values or completion candidates for that parameter
+
+### Requirement: Annotations from the permission class
+
+Each command tool SHALL carry hints from its command's permission class:
+read commands `readOnlyHint`, write and destructive commands
+`destructiveHint`. `sentry api`, whose class comes from each call's method,
+SHALL be marked destructive, and read-only on a read-only connection. A
+read-only connection SHALL NOT list write tools.
+
+#### Scenario: A host allowlists reads
+
+- **WHEN** a host allowlists the read-only tools
+- **THEN** read commands such as `sentry_issue_list` run without approval
+- **THEN** `sentry_issue_resolve` still asks for approval
+
+#### Scenario: Read-only connection lists tools
+
+- **WHEN** a read-only connection lists tools
+- **THEN** the list has the read command tools and `sentry_api`, and no write tools
+
+### Requirement: Permission classes
+
+Every command SHALL have a permission class (read, write, or destructive)
+that agrees with the API operations it calls. A read-only connection SHALL
+run only read commands, and `sentry api` calls only with read methods.
+Session constraints SHALL pin organization and project parameters.
+
+#### Scenario: Read-only connection runs a write command
+
+- **WHEN** a read-only connection calls `issue resolve`
+- **THEN** the call is refused without sending an API request
+
+#### Scenario: Constrained session
+
+- **WHEN** a session is constrained to an organization and a call names another organization
+- **THEN** the call is refused
+
+### Requirement: Isolation on the hosted server
+
+When the hosted server runs the CLI SDK, no user's credentials,
+constraints, or cached data SHALL be visible to another user's request.
+
+#### Scenario: Concurrent identities
+
+- **WHEN** two identities run commands concurrently in one isolate
+- **THEN** each call uses only its own credentials, constraints, and cache entries
+
+### Requirement: Completion for agents
+
+Completion SHALL reach agents through parameter schema `examples` and
+validation errors, with no completion tool. A call with an invalid value
+SHALL fail with completion candidates for that parameter, from the same
+completers as shell completion, with a data source suited to the host.
+
+#### Scenario: Dataset field completion
+
+- **WHEN** an agent calls `sentry_explore` with `--dataset spans` and a `--field` that does not exist, such as `span.dur`
+- **THEN** the error includes span attribute keys close to `span.dur`
+
+### Requirement: Eval-gated catalog removal
+
+The catalog tools SHALL NOT be removed until the MCP eval suite shows the
+command surface matching the catalog on task success.
+
+#### Scenario: Default flip
+
+- **WHEN** the command surface matches the catalog on the eval suite
+- **THEN** it becomes the default and the catalog stays behind a flag for one release
diff --git a/openspec/changes/cli-first-mcp/tasks.md b/openspec/changes/cli-first-mcp/tasks.md
new file mode 100644
index 000000000..59306c918
--- /dev/null
+++ b/openspec/changes/cli-first-mcp/tasks.md
@@ -0,0 +1,69 @@
+# Tasks
+
+The API work these tasks build on is `unify-sentry-api-layer`. New commands
+use `@sentry/api` operations and do not wait for the shared client to move
+there.
+
+## 1. Command metadata for agents
+
+- [ ] 1.1 (#1880) Add a permission class (read, write, destructive) to every command, derived from its operations in `command-api.json` and its `destructive` flag, with a lint check that fails when a class is missing or disagrees with the operations. Verify the check fails on a planted GET-only command marked write and a write command marked read.
+- [ ] 1.2 (#1880) Add an exposure (exposed, stdio-only, hidden) to every command, with a lint check that fails when one is missing. Mark session management, CLI maintenance, `local`, and `monitor run` hidden, and local-file commands stdio-only.
+- [ ] 1.3 (#1881) Generate `command-catalog.json` from the route tree: path, brief, JSON Schema for parameters, completion kinds, examples, output fields, API operations, permission class, and exposure. Verify a test that it matches `lib/introspect.ts` output for the full tree.
+
+## 2. CLI parity with the MCP catalog
+
+One PR per domain. Each adds the commands from the parity table in design.md, on `@sentry/api` operations, with unit tests, and ticks its rows. Pending MCP tool PRs for the same capability are redirected here.
+
+- [ ] 2.1 (#1883) Projects and teams: `project edit`, `team create`, `project team add/remove`. Supersedes `refine-project-management-tools`.
+- [ ] 2.2 (#1884) DSNs: `dsn create`, `dsn edit`.
+- [ ] 2.3 (#1885) Issues: `issue assign`, `issue comment`, `issue activity`; breadcrumbs and user reports where `event view` and `feedback list` fall short.
+- [ ] 2.4 (#1886) Events: `event attachment list/download`; dropped events (#1812).
+- [ ] 2.5 (#1887) Monitors: `monitor view`, `monitor env delete`, `monitor uptime list/view/create/edit/delete` (the detectors work in #1837 moves here).
+- [ ] 2.6 (#1381) Profiles: `profile list/view`.
+- [ ] 2.7 (#1888) Snapshots, alert options, and the metrics dataset in `explore`: check against the MCP tools and fill the gaps.
+- [ ] 2.8 (#1889) `sentry open <url>`: resolve any Sentry URL to the matching resource and command.
+- [ ] 2.9 (#1382) Mark every row in the parity table done or dropped, with the reason.
+
+## 3. The command surface on stdio
+
+- [ ] 3.1 (#1890) Add per-command tools to `mcp-core`: one MCP tool per exposed command in `command-catalog.json`, named from its path (`sentry issue list` → `sentry_issue_list`), with the catalog's brief, examples, and `{ positional, flags }` JSON Schema. Annotations from the permission class (read → `readOnlyHint`, write and destructive → `destructiveHint`; `sentry api` is one tool marked destructive, classed per call by `--method`). No `search_sentry` or `execute_*` meta-tools; harnesses search tools themselves (#1891 is folded in). Each call gets schema validation, session constraints, a result size cap that keeps JSON valid, and cursors. Verify `pnpm run measure-tokens` for the full list.
+- [ ] 3.2 (#1890) Serve them from `sentry mcp --commands`, next to the catalog, running commands through `createSentrySDK()` with the session's credentials. Refuse hidden and stdio-only commands, local-path flags, and `--web`; reject streaming flags; buffer multi-yield commands. Add `--read-only`, which drops the write tools and limits `sentry api` to GET, HEAD, and OPTIONS. Verify tests for each permission class, constraint pinning, an invalid parameter returning the allowed values, a hidden or stdio-only command not listed, write tools absent under `--read-only`, the tool list matching the catalog's exposed commands, and `/mcp-qa` over stdio.
+- 3.3 (#1891) Folded into 3.1 and 3.2: every exposed command is its own tool, and there is no separate search mode.
+- [ ] 3.4 (#1892) Add `format: "markdown"` for commands with a plain markdown renderer. Verify a test for `issue view` and `trace view`.
+
+## 4. API routes
+
+- [ ] 4.1 (#1893) Expose `sentry api` and `sentry schema`. A `sentry api` call's permission class comes from its method, and hosted checks the path against the published operation list with #1807's shared matcher. Verify a raw read, a raw write denied under `--read-only`, and an unpublished path refused on hosted.
+- [ ] 4.2 (#1894) Move `sentry schema`'s index onto `@sentry/api`'s operation catalog. Verify `sentry schema` output is unchanged.
+
+## 5. Completion for agents
+
+- [ ] 5.1 (#1895) Split the completers in `lib/complete.ts` into completers over a data source: the SQLite cache with a live API fallback on stdio, the live API, uncached, on hosted. Verify the shell completion tests pass unchanged.
+- [ ] 5.2 (#1895) Wire them into the command tools' validation errors, returning candidates with descriptions; static suggestions stay in each parameter's schema `examples`. There is no completion tool. Verify tests for slugs, issue IDs, dataset fields and aggregates, and query keys and values.
+- [ ] 5.3 (#1896) Document the query syntax in the tool descriptions of the search commands, replacing the embedded search agents' prompts.
+
+## 6. The CLI SDK on the hosted MCP
+
+- [ ] 6.1 (#1882) Spike: bundle `createSentrySDK()` with the exposed commands for workerd under `nodejs_compat` and a current compatibility date. Record what fails to bundle or run, by module and command, and the bundle size against the Workers script limit, in design.md. Mark blocked commands stdio-only.
+- [ ] 6.2 (#1897) Add a no-persistence mode to the SDK: `getDatabase()` callers get a null store (reads miss, writes do nothing), and the response cache, `.sentryclirc` and config-directory reads, custom CA and header files, version checks, and telemetry state are off. Hosted rejects the `next`/`prev` cursor keywords; agents pass the raw `nextCursor`. Verify tests that run an exposed read command, a write command, and a paginated list with persistence off and no config directory.
+- [ ] 6.3 (#1898) Audit module-level state on the exposed commands' import graph (for example `regionCache` in `lib/region.ts`, `loginTrustAnchor` in `lib/token-host.ts`, cached headers in `lib/custom-headers.ts`), and scope each item to the invocation or turn it off with persistence. Verify a test that runs two identities concurrently in one isolate and checks that neither sees the other's credentials, constraints, or results.
+- [ ] 6.4 (#1899) In `mcp-cloudflare`'s Hono app, create one SDK instance per request with the OAuth grant's token and the session constraints, persistence off. Verify Workers tests for an exposed read command, a write command, and constraint pinning.
+- [ ] 6.5 (#1899) Serve the command tools from `mcp-cloudflare` on the SDK, next to the catalog, listing only commands the hosted build can run. Verify the Workers tests and the #1675 harness against the command surface.
+- [ ] 6.6 (#1907) Map hosted consent to permission classes: API Read, API Write, and the existing skills as command groups. Verify a test per grant.
+- [ ] 6.7 For any domain the spike blocks entirely, split its commands into input resolution and a portable operation (formerly `unify-sentry-api-layer` 11.1), for that domain only.
+- [ ] 6.8 (#1908) Compare the CLI's OAuth scopes with the MCP `SCOPES` and widen the CLI's if needed. Verify a test that the CLI's scopes cover every exposed command's operations. (Formerly 11.5.)
+
+## 7. Slim stdio bundle
+
+- [ ] 7.1 (#1909) Bundle the exposed command handlers and the SDK into `@sentry/mcp-server`, keeping the guard against stdio-only and hidden commands, Ink, the terminal renderer, and SQLite WASM. Re-measure the size budget. The package stays. Verify the bundle test (`initialize`, `tools/list`, a `sentry_issue_list` call against mocks).
+
+## 8. Eval gate and cutover
+
+- [ ] 8.1 (#1910) Run the full `mcp-server-evals` suite on the catalog and the command tools, with at least two clients or models. Record task success, tokens, and turns in `docs/testing/`.
+- [ ] 8.2 (#1911) Make the command surface the default on stdio and hosted once it matches the catalog. Keep the catalog behind `--catalog` and a hosted skill for one release.
+- [ ] 8.3 (#1911) Delete the catalog tools, their `SentryApiService` endpoint wrappers, the embedded search agents, and the agent provider configuration from `mcp-core`. Verify `pnpm run tsc && pnpm run lint && pnpm run test`.
+- [ ] 8.4 (#1911) Update mcp.sentry.dev setup, `docs/` architecture and operations pages, and the agent skills for the command surface.
+
+## 9. Later: Code Mode over the SDK (optional)
+
+- [ ] 9.1 If 8.1 shows multi-step tasks losing to Code Mode (#1670), add `execute_sentry_code` whose `sentry` object calls the same execution path, permission checks included, in #1670's sandbox on hosted. Decide the stdio sandbox then.
diff --git a/openspec/changes/unify-sentry-api-layer/.openspec.yaml b/openspec/changes/unify-sentry-api-layer/.openspec.yaml
new file mode 100644
index 000000000..d58ba0232
--- /dev/null
+++ b/openspec/changes/unify-sentry-api-layer/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-26
diff --git a/openspec/changes/unify-sentry-api-layer/design.md b/openspec/changes/unify-sentry-api-layer/design.md
new file mode 100644
index 000000000..8d172a04a
--- /dev/null
+++ b/openspec/changes/unify-sentry-api-layer/design.md
@@ -0,0 +1,602 @@
+# Design
+
+## Context
+
+See proposal.md for motivation. Current state that shapes the approach:
+
+- **Dependency direction.** `packages/cli` depends on `@sentry/mcp-server`
+  (`workspace:*`), and its build compiles `mcp-core` and `mcp-server` first.
+  `cli/src/lib/mcp.ts` already passes credentials into `runMcpServer()`
+  through `resolveAccessToken` and `onUpstreamUnauthorized`. Shared code
+  must therefore live below both products, in `toolkit-core`.
+  The stdio server is moving into the CLI as `sentry mcp`, after which the
+  CLI depends on `mcp-core` directly and `@sentry/mcp-server` becomes a
+  dependency-free bundle of that same server, built from CLI source.
+- **CLI request stack.**
+  - `sentry-client.ts` handles auth, refresh on 401, timeouts, GET retries,
+    redirect validation, and custom headers.
+  - `response-cache.ts` caches responses as JSON files under
+    `~/.sentry/cache/responses/`, using `http-cache-semantics`, an HMAC
+    identity key, TTL tiers, and a 500-entry cap. Its 24-hour "immutable"
+    tier matches any `/events/<id>/`, `/trace/<32 hex>/`, or
+    `/trace-items/<id>/` URL, and is checked before the `/issues/` volatile
+    pattern, so `/issues/<id>/events/latest/` is cached for 24 hours too.
+  - `api/infrastructure.ts` has `paginate()` and `fetchAllPages()`, with
+    mid-page skip counts encoded in the cursor's `is_prev` field.
+- **MCP request stack.** `mcp-core/src/api-client/client.ts` has about 105
+  methods and hits 91 distinct endpoint paths. It owns its own
+  `request`/`requestOnce`, does GET-only gateway retries, validates with Zod,
+  and has no response cache. Against `@sentry/api@0.404.0`, about 67 of
+  those paths have generated operations; the rest are missing, mainly
+  legacy alert rules, uptime, monitor stats, issue activities/notes/user
+  reports, the search agent, and event committers.
+- **Workers runtime.**
+  - 128 MB memory per isolate, and one isolate serves many users at once.
+  - No persistent filesystem.
+  - `nodejs_compat` is enabled: `AsyncLocalStorage`, `node:crypto`, and
+    `node:zlib` are available.
+  - `node:zlib` zstd works under the current compatibility date
+    (`2025-03-21`) in local workerd, verified with `wrangler dev` 4.151.3.
+    Cloudflare's docs list only gzip, deflate, and brotli, so this must be
+    confirmed on a deployed preview.
+  - `CompressionStream` has no zstd.
+- **`@sentry/api` already has** `fetchPage_*`, `paginateAll_*`, and
+  `paginateUpTo_*` helpers, plus `./zod`, `./valibot`, and `./browser`
+  entry points. Its `paginateUpTo` drops `nextCursor` when trimming a page
+  would make continuing unsafe. The CLI's skip-count cursor closes exactly
+  that gap.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- One implementation of pagination, cache policy, and transport, used by
+  the CLI, `sentry mcp`, and the hosted MCP.
+- One Sentry API client, with endpoint wrappers, errors, and validation, in
+  place of the MCP's `SentryApiService` and the CLI's API modules. It lives
+  in `toolkit-core` first and in `@sentry/api` after step 2.
+- Shared modules run unchanged in Node, Workers, and browsers, using only
+  web-standard APIs, so the Sentry frontend can use the published client.
+- No CLI behavior change while its internals move, apart from the cache
+  tier correction, which lands first as its own PR.
+
+**Non-Goals:**
+
+- Client-side caching in the Sentry frontend. Browser HTTP caching driven
+  by server headers covers that (getsentry/sentry#128818).
+- Calling `createSentrySDK()` from the hosted MCP. `cli-first-mcp` takes
+  that on, running the SDK with persistence off.
+- Moving the hosted MCP off Cloudflare Workers, or making the CLI serve
+  more than one user.
+- Replacing every hand-written response schema with a generated one, or
+  moving either product to the other's validation library.
+
+## Decisions
+
+### Narrow the CLI's cache tiers before moving them
+
+The getsentry/sentry#128818 spike (findings in
+[this comment](https://github.com/getsentry/sentry/issues/128818#issuecomment-6426889162),
+checked against sentry `06a3bc41dda`) found that none of the "immutable"
+endpoints are safe to mark `immutable`:
+
+- **Project and issue event details** embed `nextEventID`,
+  `previousEventID`, user reports, and release data, all of which change
+  later. Reprocessing and issue merges can change the response for the same
+  event ID. `latest`, `oldest`, and `recommended` resolve to different events
+  over time.
+- **Full traces** gain spans as they arrive.
+- **Organization event details** (excluding `?averageColumn`, which reads
+  live aggregates) and **project trace-item details** (excluding
+  superuser/staff requests and `?debug`) are stable enough for
+  `Cache-Control: private, max-age=300`. The prototype in
+  getsentry/sentry#128828 sends exactly that, off by default, with
+  `Vary: Origin, Cookie, Authorization`.
+- Every endpoint can still change visibility: deletion and access
+  revocation are not reflected until the entry expires. That bounds the TTL,
+  not just the tier.
+
+So the CLI drops `immutable` (getsentry/toolkit#1681):
+
+| Tier     | TTL  | Matches                                                                                                                                 |
+| -------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| no-cache | 0    | autofix and root-cause polling                                                                                                          |
+| volatile | 60 s | `/issues/` (including issue events), `/projects/{org}/{project}/events/{id}/`, `/organizations/{org}/trace/{id}/`, log and span queries |
+| stable   | 5 m  | everything else, including organization event details and trace-item details                                                            |
+
+- No separate tier for the safe detail endpoints. In the CLI it would have
+  the same TTL as `stable`, so it was folded in during review. Which
+  responses the hosted MCP may persist to R2 is a decision for that store,
+  made with its own allowlist (see the R2 backend below), not a TTL tier.
+- When server headers are present they still win. The CLI keeps honoring
+  `max-age`, so if the server later extends it, the CLI follows without a
+  release.
+- Classification stays URL-regex based for now. A TODO in
+  `response-cache.ts` tracks moving it to generated `@sentry/api` operation
+  metadata (getsentry/sentry-api-schema#81, #102).
+- This landed as its own CLI PR before the move into `toolkit-core`, so the
+  move itself stays a no-behavior-change refactor.
+
+The cost is more API calls for repeated event and trace reads. A 24-hour
+window was a correctness bug, not a tunable: an agent re-reading an issue's
+latest event an hour later got the wrong event.
+
+### Shared code lives in `toolkit-core`, behind injected dependencies
+
+New `toolkit-core` modules:
+
+- `pagination`: `paginate`, `fetchAllPages`, cursor encode/decode, and page
+  sizing. Pure logic. Errors come back as typed results, and the host maps
+  them to its own error classes.
+- `response-cache`: the cache policy. Covers tier classification, key
+  derivation, invalidation prefixes (from `cli/src/lib/cache-keys.ts`), and
+  freshness through `http-cache-semantics`. Storage sits behind a
+  `CacheStore` interface.
+- `api-retry`: the retry policy. Pure logic with no Node APIs, so Workers
+  can use it. It lands first, ahead of the transport, so the MCP can fix
+  its 429 handling now.
+- `api-transport`: a fetch wrapper that takes a `CredentialProvider` (get the
+  token, refresh on 401), an optional `CacheStore`, a logger, a span hook,
+  and retry/timeout options. Retries go through `api-retry`. Redirect
+  validation and region routing move with it.
+
+Product code keeps credential storage, error classes, user-facing
+messages, and telemetry setup.
+
+_Alternative: a new package._ Rejected for now. `toolkit-core` is already
+the bundled-private shared package, and a split can come later when moving
+code into `@sentry/api`.
+
+### Retries replay only requests that cannot repeat a write, and honor rate-limit headers
+
+Neither product handles 429s well today. The CLI retries every method on
+408, 429, and 5xx, POSTs included, and ignores rate-limit headers. The MCP
+retries only GETs on 502, 503, and 504, so a 429 fails at once. In 7 days
+the hosted MCP saw about 32,600 429s from the Sentry API, nearly all on GETs
+("Limit is 40 requests in 1 seconds").
+
+Sentry's 429 body is only `{"detail": ...}`. The timing is in headers:
+`X-Sentry-Rate-Limit-Reset` is the Unix second the next window starts, with
+`-Remaining`, `-Limit`, `-ConcurrentRemaining`, and `-ConcurrentLimit`
+alongside (`src/sentry/middleware/ratelimit.py`). Sentry sends no
+`Retry-After`, but a proxy in front of it can.
+
+`api-retry` decides whether and how long to wait:
+
+- The retried statuses are 429, 500, 502, 503, and 504. The other 5xx codes,
+  such as 501 and 505, are deterministic, so they are not retried.
+- A 429 is retried for any method. `RatelimitMiddleware.process_request`
+  rejects it before the view runs, so replaying it cannot repeat a write.
+- A 5xx, a timeout, or a network error may come after the endpoint ran. Those
+  are retried only for GET, HEAD, and OPTIONS, unless a request opts in with
+  `idempotent: true`. A replayed write can duplicate a comment or an alert.
+- `Retry-After` wins when present. Otherwise a 429 waits until
+  `X-Sentry-Rate-Limit-Reset`. The delay is kept within the range the response
+  `Date` allows, so a skewed local clock moves it by at most a second.
+- A concurrency-limit 429 (`ConcurrentRemaining: 0`) and a response with no
+  usable header fall back to jittered exponential backoff.
+- Each product sets a per-wait and a total-wait cap. When the header asks for
+  longer, the request fails at once with a rate-limit error that says when
+  to retry, rather than holding a Worker request open.
+- Sleeps take an `AbortSignal`.
+
+The 401 refresh is not a retry in this sense. It replays any method once,
+because the request never reached the endpoint.
+
+### `CacheStore` is three byte-based operations
+
+```ts
+interface CacheStore {
+  get(key: string): Promise<CacheEntry | undefined>;
+  set(key: string, entry: CacheEntry, ttlMs: number): Promise<void>;
+  deleteMatching(identity: string, urlPrefix: string): Promise<void>;
+}
+```
+
+`CacheEntry` stores the compressed body bytes plus metadata: URL, identity,
+tier, encoding, serialized cache policy, and size. Every backend enforces a
+byte budget and a per-entry cap, not an entry count.
+
+Backends:
+
+- **Filesystem (CLI).** Keeps today's on-disk layout and adds compression.
+  It moves from a 500-entry cap to a byte budget, with the default set so
+  current users see a similar footprint.
+- **Memory (hosted MCP, tests).**
+  - LRU limited by bytes, counted over compressed bytes.
+  - Default budget 24 MB per isolate and a 1 MB per-entry cap on compressed
+    size, configurable by env.
+  - Module-scoped, so it lives as long as the isolate. `deleteMatching`
+    scans the in-memory index.
+- **R2 (hosted MCP, allowlisted detail endpoints only).**
+  - Persists an entry only when its URL matches the store's explicit
+    allowlist _and_ the response carries `Cache-Control: private` with a
+    positive `max-age`. The allowlist holds exact path shapes:
+    `/organizations/{org}/events/{project}:{event_id}/` without
+    `averageColumn`, and `/projects/{org}/{project}/trace-items/{id}/`
+    without `debug`. The server header is the opt-in: until
+    getsentry/sentry#128828 ships and is enabled, R2 stores nothing.
+  - Today the CLI and MCP read events through project and issue endpoints,
+    which are not on the allowlist. So in practice R2 covers trace items
+    until a caller moves to the organization event endpoint, which is worth
+    doing per call site only where the response has every field the caller
+    uses.
+  - Object key is `<identity>/<sha256(normalized URL)>`, with the expiry,
+    the lesser of the server `max-age` and 5 minutes, in custom metadata and
+    checked on read.
+  - A bucket lifecycle rule deletes objects after 1 day, the shortest rule
+    R2 supports. It is garbage collection only; reads enforce the expiry.
+  - Writes happen in `ctx.waitUntil()`, so they never delay a response.
+  - Allowlisted entries are never targeted by mutation invalidation, so R2
+    never needs `deleteMatching`. The short expiry bounds how long a revoked or
+    deleted item can still be served.
+
+_Alternatives:_
+
+- **Workers KV.** Rejected because it is eventually consistent, which
+  breaks invalidation after mutations.
+- **D1.** A good fit for prefix deletes, but it has a single primary region,
+  is single-threaded, and limits rows to 2 MB. Deferred until hit-rate data
+  says stable-tier sharing across isolates is worth it.
+- **Durable Objects per user.** Deferred for the same reason.
+
+### Composite store for hosted
+
+`TieredStore(memory, r2)`:
+
+- `get` checks memory first, then R2 for allowlisted URLs, and copies R2
+  hits into memory with the remaining expiry.
+- `set` writes to memory, and also to R2 when the entry is R2-eligible (see
+  above).
+- `deleteMatching` only touches memory, since only volatile and stable
+  entries are ever invalidated.
+
+### Identity
+
+The identity string is an HMAC input. It is never a raw token, and it stays
+stable across token refresh.
+
+- **CLI:** keeps `getIdentityFingerprint()`, which hashes the refresh token
+  for OAuth logins.
+- **Hosted:** hashes the user ID and grant ID taken from the MCP wrapper
+  bearer token (`userId:grantId:secret`, parsed in
+  `mcp-cloudflare/src/server/lib/mcp-handler.ts`).
+- **Standalone MCP with a static token:** hashes the token.
+
+Key derivation uses WebCrypto (`crypto.subtle`) HMAC-SHA256 instead of
+`node:crypto`, so the module also runs in browsers. This makes key
+derivation async. The cache API is already async, so no call sites change
+shape.
+
+### Compression: plain zstd now, trained dictionary as a follow-up
+
+Benchmarked on Node 22 with real API responses from Sentry's own
+organization. The samples were kept in the sandbox and not committed:
+
+- 255 responses from one project (events, issue details, issue lists,
+  traces, logs, spans, projects, teams), split 70/30 into training and test
+  sets.
+- 90 responses from five other projects (Android, Node, Next.js, Rust,
+  Python) as a cross-project check.
+
+Ratios are total raw bytes divided by total compressed bytes, with each
+response compressed on its own, the way the cache stores entries:
+
+| Codec                              | Same project, ≤1 MB | Other projects | >256 KB (traces) | Compress, ms/MB | Decompress, ms/MB |
+| ---------------------------------- | ------------------- | -------------- | ---------------- | --------------- | ----------------- |
+| zstd-3                             | 8.7x                | 6.3x           | 37x              | 1.6             | 1.2               |
+| zstd-9                             | —                   | —              | 45x              | 5.6             | 0.9               |
+| zstd-3 + trained 110 KB dictionary | 17.0x               | 7.6x           | 37x              | 2.0             | 0.8               |
+| brotli-4                           | 9.3x                | 6.6x           | 42x              | 3.0             | 0.6               |
+| brotli-6                           | —                   | —              | 45x              | 5.7             | 0.8               |
+| brotli-11                          | —                   | —              | 49x              | 775             | 2.3               |
+| gzip-6                             | —                   | —              | 30x              | 3.9             | 0.8               |
+
+Findings:
+
+- **Brotli is not the better target.**
+  - At the same CPU, zstd-9 and brotli-6 tie.
+  - brotli-4 beats zstd-3 by 5–12% but costs about 2x the compression CPU.
+  - Brotli's best ratio, quality 11, costs about 500x the CPU of zstd-3.
+  - `node:zlib` brotli has no custom dictionary support.
+- **A trained dictionary is the big lever for small and medium responses,
+  which are most entries by count.** On the same project it doubled the
+  overall ratio (8.7x → 17.0x), and below 16 KB it went from 3.4x to 9.8x.
+  On other projects the gain shrank to about 20% (6.3x → 7.6x). The
+  dictionary had learned project-specific values (paths, function names,
+  slugs), not just JSON keys. It did nothing for large traces.
+- **Dictionaries built from public data did not help.** One trained on the
+  repo's mock fixtures, and one trained on response skeletons with all values
+  blanked, stayed at about 3.4–3.8x for small responses. The gain comes from
+  real values.
+- **Workers ignores `dictionary`.** Local workerd (`wrangler dev` 4.151.3)
+  accepts the `dictionary` option on `zstdCompressSync` but silently ignores
+  it: output is byte-for-byte the same size as without a dictionary. Node 22
+  honors it (5.3 KB issue: 1,819 → 632 bytes).
+- **The per-entry cap must apply to compressed size.** Traces in this
+  sample had a median of 1.5 MB raw (max 14 MB), but compress 37–45x. A cap on
+  raw size would make most traces impossible to cache.
+
+Decisions:
+
+- **zstd level 3 everywhere, no dictionary.** One codec setting for the
+  CLI disk, the hosted memory tier, and R2.
+  - It runs on the response path and is charged as Worker CPU time.
+  - zstd-9 only helps large traces (37x → 45x) at 3.5x the compression
+    CPU. With R2 entries now living at most 5 minutes, an entry is read
+    only a few times, so the extra CPU does not pay back.
+  - A single level keeps entries portable between tiers: an R2 hit is
+    copied into memory without recompressing.
+- **Fallback: brotli quality 4 via `node:zlib`, then uncompressed.** The CLI
+  supports Node.js 20+, which lacks zstd, so the codec is detected at
+  runtime, the way `api/infrastructure.ts` already detects `zstdCompress`.
+- **Small bodies:** stored uncompressed below 256 bytes.
+- **Per-entry cap on compressed size**, plus a raw-size ceiling (default
+  32 MB) that bounds memory spikes during decompression.
+- **Encoding recorded per entry.** `encoding` and `dictId` are recorded per
+  entry, so mixed entries stay readable after upgrades and dictionary
+  rotations.
+- **Dictionary support is a follow-up (task group 10), gated on three
+  checks:**
+  1. **Training data safety.** A dictionary embeds verbatim strings from its
+     training data, so one trained on customer or internal data must never
+     ship in a public package (`sentry`, `@sentry/mcp-server`). Options:
+     - train on a public demo organization
+     - train per deployment, for example the hosted MCP from its own cache
+       contents within an organization
+  2. **Workers support.** Use a WASM zstd build for dictionary compression,
+     or wait for workerd to honor the option. A startup self-test compresses
+     a known sample and checks that the dictionary took effect, so a silently
+     ignored option is caught.
+  3. **A broader benchmark** across many organizations and projects before
+     committing to dictionary size and rotation.
+
+Compression saves memory and storage, not CPU. A cache hit costs
+decompression instead of JSON from the network, and on Workers the network
+wait is not billed CPU. Its job is to fit more entries into the budget.
+
+### Into `@sentry/api` directly, from here on
+
+Everything `SentryApiService`-like ends up in `@sentry/api`, so the CLI,
+both MCP servers, and the Sentry frontend share one client. The first part
+was built in `toolkit-core/src/api-client/` with the layout it will have in
+`@sentry/api` (task group 8: #1732, #1736, #1737, #1741, #1820), so moving
+it is a copy plus reconciliation with the errors and pagination
+sentry-api-schema already has (`lib/sentry-errors.ts`,
+`lib/sentry-pagination.ts`, `lib/browser-client.ts`).
+
+The rest no longer stages in `toolkit-core`. Under
+`cli-first-mcp`, the MCP's catalog tools and their endpoint
+wrappers are deleted at the cutover to the command surface, so the only long-term caller
+of endpoint wrappers is the CLI, and the MCP reaches the API through CLI
+operations. Building shared MCP wrappers first would be thrown away. The
+order is:
+
+1. Move `toolkit-core/src/api-client/` into `@sentry/api`, publish, switch
+   toolkit, and delete the copies (8.5, 8.6).
+2. Move the CLI's endpoint wrappers onto the `@sentry/api` client, domain
+   by domain (8.7). A wrapper that only reshapes one generated operation is
+   replaced by the operation.
+3. Get every endpoint still called by raw path into the published schema
+   (8.8). `sentry api`, `sentry schema`, and so the MCP only reach published
+   operations, so this also widens what agents can call.
+
+The cost is a publish round trip for client fixes. Develop against a local
+sentry-api-schema checkout through a pnpm override, and release
+`@sentry/api` as often as toolkit needs it.
+
+### The shared client
+
+`toolkit-core/src/api-client/` holds:
+
+- **Core:** building URLs for a region, setting headers, reading responses,
+  and mapping error responses to errors. Requests go through the shared
+  transport, so there is one retry layer.
+- **Errors:** `ApiError` with the status and the server's detail, and the
+  rate-limit error with `retryAfterMs` from `Retry-After` or
+  `X-Sentry-Rate-Limit-Reset`. Hosts map them to their own presentation:
+  CLI exit codes and messages, MCP tool results.
+- **Validation:** library-agnostic, through the
+  [Standard Schema](https://standardschema.dev) interface
+  (`@standard-schema/spec`), which Zod and valibot both implement. Shared
+  code depends only on that interface's types, vendored or type-only, and
+  never on Zod or valibot at runtime. Each wrapper validates with a schema
+  the host passes in, so the host's schema decides the result type: the
+  MCP keeps Zod (`@sentry/api/zod` where it covers the endpoint), which
+  suits long-running servers and is the more widespread library, and the
+  CLI keeps valibot (`@sentry/api/valibot`), which suits short-lived
+  processes where startup and bundle size matter. Validation failures
+  surface as one shared error type with the issues from the Standard
+  Schema result.
+- **Pagination, cache policy, retry policy, and transport:** the existing
+  `pagination`, `response-cache` policy, `api-retry`, and `api-transport`
+  modules, which move with it in step 2.
+- **Endpoints by domain:** organizations, projects, teams, issues, events,
+  explore, traces, logs, releases, replays, monitors, alerts, and so on, on
+  top of `@sentry/api` operations where they exist and the shared transport
+  otherwise. Where both products call the same endpoint, they call the same
+  wrapper.
+
+Hosts keep:
+
+- **CLI:** credential storage and refresh, the SQLite and filesystem cache
+  store, region lookup storage, telemetry spans, and mapping errors to exit
+  codes.
+- **MCP:** the session's access token, its Zod-to-tool output formatting, and
+  the request-scoped `fresh` flag.
+- **Browser:** session credentials, and no cache store, since browser HTTP
+  caching driven by server headers covers it.
+
+### Portable shared code, enforced
+
+The shared client imports only `@sentry/api` and the toolkit-core modules
+that move with it. It uses only web-standard APIs (`fetch`, `Request`,
+`Response`, `Headers`, `URL`, `AbortSignal`, `crypto.subtle`,
+`TextEncoder`), so it runs in Node, Workers, and browsers. It never imports
+`node:*` or uses `Buffer`, `fs`, `process`, or `AsyncLocalStorage`.
+
+Credentials, cache storage, the fresh-read scope, logging, and telemetry are
+interfaces. Each host passes its own implementation.
+
+Two checks keep it that way:
+
+- A lint rule on the shared modules bans `node:*` imports and Node globals.
+- A typecheck of the shared modules against the DOM library, with no Node
+  types, catches the rest, such as `NodeJS.Timeout` types.
+
+The cache codec uses `node:zlib`, which Node and Workers have and browsers do
+not. It is storage, so it stays a host-side module outside the guarded set
+and does not move in step 2.
+
+### MCP tools: replaced by the CLI's commands
+
+This section planned to move each MCP tool into the CLI as a portable
+`sentry/mcp` tool definition. `cli-first-mcp` replaces it: the
+MCP exposes the CLI's commands through search and execute tools,
+discovered through CLI introspection, and the hosted MCP runs the CLI SDK
+with persistence off. The resolve/operate/render split survives
+there only as a fallback for domains Workers cannot run.
+
+### `@sentry/mcp-server` is a slim bundle of `sentry mcp`
+
+`@sentry/mcp-server` is kept, not retired. The CLI has grown large, and a
+client that only needs Sentry's tools over stdio should not have to
+download it. The package ships the same server as `sentry mcp`, bundled
+from CLI source into one file with no runtime dependencies (#1731):
+
+- One implementation serves both, so the package keeps the same flags,
+  tools, CLI session, and self-hosted support as `sentry mcp`.
+- The bundle leaves out what does not serve the MCP server: CLI commands,
+  the markdown renderer, agent skills, completions, terminal images, the
+  Ink UI, debug-file processing, and the SQLite WASM fallback. Without the
+  fallback, the package requires Node.js 22.15 or later. The bundle script
+  fails if any of these reach the output or the file grows past its size
+  budget.
+- `sentry-mcp auth login` runs the CLI's device flow with plain-text
+  output. Other account management stays in `sentry auth`, which reads the
+  same session.
+- Under `cli-first-mcp` the bundle carries the exposed command handlers
+  instead of catalog tools (`cli-first-mcp`).
+- `@sentry/mcp-server` stays the recommended stdio install and keeps the
+  MCP registry entry (`server.json`). `sentry mcp` runs the same server for
+  people who already use the CLI.
+
+A stdio proxy to the hosted MCP was considered and rejected (#1743): it
+cannot reach self-hosted Sentry, and it would be a second implementation
+to keep in step.
+
+### `fresh` is a shared read-tool input
+
+Read-only tools gain an optional `fresh: boolean`, defined once in the
+shared tool schema helpers. The MCP tool handler sets a request-scoped
+bypass with `AsyncLocalStorage`, and the shared transport reads it only
+through its `fresh()` callback. The flag is host state: shared code never
+touches `AsyncLocalStorage`, which browsers lack. The tool count does not
+change. Token cost is checked with `pnpm run measure-tokens`, and the
+description stays short.
+
+### Endpoints move in stacked PRs by layer, not by domain
+
+The earlier plan moved MCP methods onto `@sentry/api` one domain per PR.
+Issues and events landed that way (#1713). The rest moves in a stack of
+step 1 PRs split by layer instead:
+
+1. The foundation: errors, `apiPath`, validation, and response reading
+   (#1732).
+2. Pagination, cache policy, retry, and transport moved under
+   `api-client/`.
+3. Endpoint wrappers by domain, with the MCP switched onto them.
+4. The CLI host seam, with the CLI switched.
+5. One wrapper for each endpoint both products call.
+
+Each PR switches every caller of the layer it moves, so neither product is
+left half on the old layer for that layer. Endpoints that `@sentry/api` lacks
+call the shared transport directly, and hosts keep their own schemas for
+them. Endpoint
+behavior is checked against `~/src/sentry`, as `AGENTS.md` requires.
+
+### Version alignment first
+
+Add `@sentry/api` to the pnpm catalog at `0.400.0`, which is already in
+`minimumReleaseAgeExclude`, and point both packages at `catalog:`. Later
+bumps move both products together.
+
+## Risks / Trade-offs
+
+- **Cross-user leakage on the shared Worker.** Every key includes an
+  identity HMAC. There is a test that two identities never share entries
+  for the same URL, and R2 keys are prefixed by identity.
+- **Stale data in agent answers.** Volatile entries last 60 s, and no entry
+  lasts longer than 5 minutes without a server header. There is
+  invalidation after mutations, and `fresh` for explicit bypass. The tool
+  description tells agents when to use it.
+- **Revoked access or deleted data served from cache.** A user who loses
+  access to a project, or whose event is deleted, can still get a cached
+  copy until it expires: up to 5 minutes for stable entries, including
+  from R2 on the hosted MCP. Enabling R2 in production needs a privacy and
+  security sign-off on that window, alongside the server-side headers in
+  getsentry/sentry#128828.
+- **Worker OOM.** The memory store has a byte budget and a per-entry cap.
+  Compressed size is what counts. A load test fills the store with many
+  identities and checks its peak memory.
+- **zstd unavailable in production Workers.** Confirm on a preview deploy
+  before relying on it. The brotli fallback keeps caching working either
+  way.
+- **Transport move regresses the CLI.** The CLI's existing tests run against
+  the shared modules unchanged. The move happens one module at a time, and
+  each step has no behavior change.
+- **Generated `@sentry/api` types disagree with responses.** Keep Zod
+  validation at the MCP boundary. Pin and bump `@sentry/api` through the
+  catalog.
+- **A long stack of PRs.** Each PR waits on the one below it and needs a
+  rebase when that one merges. Splitting by layer keeps each PR coherent,
+  both products' test suites run against every PR, and each PR body lists
+  its intentional behavior changes.
+- **Two validation libraries.** The MCP's Zod schemas and the CLI's valibot
+  schemas for the same endpoint can drift apart. Standard Schema keeps the
+  shared client out of that choice, so neither product pays for the other's
+  library, and the CLI keeps valibot off Zod's startup cost. Where
+  `@sentry/api` generates both (`./zod` and `./valibot`), hosts use the
+  generated schemas, which come from one OpenAPI source.
+- **Node-only APIs creep into shared code.** The lint rule and the
+  browser-target typecheck fail CI.
+- **CLI-issued tokens lack MCP scopes.** The MCP and CLI use different OAuth
+  client IDs and scope lists today. When the deferred `sentry mcp` phase is
+  picked up, compare them before relying on the CLI session for MCP tools. If they
+  differ, widen the CLI's requested scopes.
+
+## Migration Plan
+
+1. Land the catalog alignment (#1672), the CLI cache tier correction, and
+   `api-retry` with the MCP 429 fix, each as its own PR.
+2. Land the pure `toolkit-core` modules (pagination, cache policy, codecs),
+   with the CLI switched over and no behavior change.
+3. Land `api-transport` and the CLI switch-over.
+4. Land the MCP on the shared transport (#1722), then the hosted memory
+   store behind a flag (`MCP_RESPONSE_CACHE=memory`).
+5. Enable the hosted memory cache. Add the R2 binding and its allowlist
+   behind `MCP_RESPONSE_CACHE=tiered`, and enable it only after the server
+   headers ship and the security sign-off.
+6. Step 1: land the stacked PRs by layer: the foundation with the
+   portability guard, the transport-layer move, the endpoint wrappers with
+   the MCP switch, the CLI switch, and the merged shared wrappers.
+7. Step 2: copy the client into getsentry/sentry-api-schema, publish
+   `@sentry/api`, switch toolkit to it, and delete the toolkit-core copies.
+8. Move the shared client into `@sentry/api`, then the CLI's wrappers, then
+   the endpoints missing from the published schema. The MCP side continues
+   in `cli-first-mcp`.
+
+**Rollback:** the hosted cache is gated by an env flag, and setting it to
+`off` restores today's uncached behavior. Each CLI step is a refactor that
+can be reverted on its own.
+
+## Open Questions
+
+- The exact byte budgets (CLI disk, Worker memory) and the per-entry cap.
+  To be tuned with hit-rate and memory metrics after launch.
+- Whether R2 pays off with a 5-minute window. Cross-isolate hits only help
+  when the same identity re-reads the same event or span within minutes,
+  which agents often do, but metrics will decide whether the R2 tier stays.
+- Whether the server should send `private, max-age` on more endpoints
+  later, such as stable organization and project metadata. The CLI follows
+  server headers automatically; R2 eligibility stays an explicit allowlist.
diff --git a/openspec/changes/unify-sentry-api-layer/proposal.md b/openspec/changes/unify-sentry-api-layer/proposal.md
new file mode 100644
index 000000000..b38074306
--- /dev/null
+++ b/openspec/changes/unify-sentry-api-layer/proposal.md
@@ -0,0 +1,148 @@
+# Proposal
+
+## Why
+
+The CLI and the MCP server talk to the same Sentry API through two separate
+request layers. The CLI has resume-safe pagination, an identity-scoped
+response cache, 401 refresh, timeouts, and validated redirects. The MCP has
+its own transport in `mcp-core/src/api-client/client.ts` (about 6,000 lines),
+uses `@sentry/api` for only three operations, and caches nothing. Fixes and
+features land in one product and not the other, and the two pin different
+`@sentry/api` versions (`0.337.0` and `^0.400.0`).
+
+`createSentrySDK()` cannot be the shared API layer:
+
+- The CLI depends on `@sentry/mcp-server` for `sentry mcp`.
+- The SDK needs SQLite and a filesystem, which Cloudflare Workers lack.
+- SDK errors flatten HTTP status into exit codes.
+
+The shared API layer must therefore sit below both products, on
+`@sentry/api`. (`cli-first-mcp` separately makes the SDK's storage
+pluggable so the hosted MCP can run commands; the SDK still calls the API
+through this client.)
+Its end state is inside `@sentry/api` itself, so every consumer, including
+the Sentry frontend in the browser, gets one Sentry API client.
+
+The plan had two steps: build the shared client in `@sentry/toolkit-core`,
+structured the way it will live in `@sentry/api`, then copy it there. The
+transport, retry, cache policy, pagination, request core, and organizations
+domain landed in `toolkit-core` that way (#1719, #1722, #1732, #1736, #1737,
+#1741, #1820).
+
+**Updated 2026-11-03.** The MCP is becoming a search-and-execute surface
+over the CLI's commands (`cli-first-mcp`), so its catalog tools and their
+endpoint wrappers will be deleted rather than shared. The remaining plan
+therefore goes straight to `@sentry/api`:
+
+1. Move what `toolkit-core/src/api-client/` holds into
+   getsentry/sentry-api-schema now, reconciled with the errors and
+   pagination that package already ships, and switch toolkit to it.
+2. Move the CLI's endpoint wrappers onto that client.
+3. Get the endpoints the CLI and MCP still call by raw path into the
+   published schema, so they generate as `@sentry/api` operations.
+
+## What Changes
+
+- Move the CLI's pagination into `@sentry/toolkit-core` and use it from both
+  products: limit-bounded walks, even page sizing, and cursors that resume
+  mid-page.
+- **Behavior change (landed in #1681):** drop the CLI's 24-hour
+  "immutable" cache tier. It matched every `/events/<id>/` and
+  `/trace/<id>/` URL, but issue events, project events, and full traces
+  change after they are first read (getsentry/sentry#128818). Issue events,
+  project events, and full traces drop to 60 seconds; organization event
+  details and trace-item details fall to the default 5 minutes.
+- Move the CLI's response-cache policy into `@sentry/toolkit-core`. That
+  covers TTL tiers, identity-scoped keys, invalidation after mutations, and
+  bypass. Storage becomes a pluggable backend with a byte budget and
+  compression.
+- Add a shared retry policy to `@sentry/toolkit-core`: 429s are retried for
+  any method and wait for Sentry's rate-limit reset header within a cap, while
+  5xx responses and timeouts are retried only for idempotent requests. The MCP adopts it first, so rate-limited GETs retry instead of
+  failing.
+- Move the CLI's request transport into `@sentry/toolkit-core`, with
+  credentials, storage, and telemetry injected by the host. It covers retries
+  through the shared policy, timeouts, redirect validation, and region
+  routing.
+- The MCP's `SentryApiService` sends every request through the shared
+  transport and drops its own retry loop.
+- **Step 1 (stopped early, see Why):** add a shared API client to
+  `@sentry/toolkit-core`, in stacked PRs by layer that also switch both
+  products and delete the code they replace. It
+  covers endpoint wrappers by domain on top of `@sentry/api` operations,
+  the error types (`ApiError`, rate limits, `retryAfterMs`), response
+  validation through the Standard Schema interface (the MCP keeps Zod and
+  the CLI keeps valibot; shared code depends on neither), pagination,
+  the cache policy, the retry policy, and the transport.
+- **Portability rule:** the shared client imports only `@sentry/api` and
+  toolkit-core modules that move with it, and uses only web-standard APIs,
+  so it runs in Node, Workers, and browsers. No `node:*` imports, `Buffer`,
+  `fs`, `process`, or `AsyncLocalStorage`. Credentials, storage, the
+  fresh-read scope, and telemetry are interfaces each host provides. A lint
+  rule and a browser-target typecheck enforce it.
+- **Step 2, now next:** move the shared client into `@sentry/api`, publish
+  it, and switch toolkit over. The CLI's endpoint wrappers then move onto
+  it, and endpoints missing from the published schema are added there.
+- The hosted MCP on Cloudflare uses a tiered cache:
+  - an in-memory LRU, limited by bytes, for every tier
+  - R2 for an allowlist of organization event details and project
+    trace-item details, only when the server marks them `private, max-age`,
+    for at most 5 minutes
+  - zstd level 3 compression on both
+- MCP read tools accept a `fresh` parameter that bypasses the cache, matching
+  the CLI's `--fresh` flag. The request-scoped flag lives in the MCP host,
+  not in shared code.
+- Shared endpoint wrappers use `@sentry/api` operations where they exist. The
+  endpoints `@sentry/api` lacks go through the same shared transport.
+- Both products use one `@sentry/api` version from the pnpm catalog.
+
+Out of scope, tracked separately:
+
+- Server-side `Cache-Control` for event and trace-item detail responses
+  (getsentry/sentry#128818, prototype in getsentry/sentry#128828).
+- The MCP tool surface: replaced by `cli-first-mcp`, which exposes the
+  CLI's commands through search and execute tools. `@sentry/mcp-server` stays a
+  dependency-free bundle built from CLI source (#1731).
+
+## Capabilities
+
+### New Capabilities
+
+- `sentry-api-pagination`: Limit-bounded, resume-safe pagination over Sentry
+  list endpoints, shared by the CLI and MCP.
+- `sentry-api-response-cache`: Identity-scoped caching of Sentry API GET
+  responses. Covers TTL tiers, bypass, invalidation after mutations, and
+  bounded, compressed storage.
+- `sentry-api-transport`: When a Sentry API request is retried, how long it
+  waits, and what a caller sees when it gives up.
+- `sentry-api-client`: One portable Sentry API client, shared by the CLI and
+  MCP from `toolkit-core` and later from `@sentry/api`, with host-injected
+  credentials, storage, and telemetry.
+
+### Modified Capabilities
+
+None.
+
+## Impact
+
+- `packages/toolkit-core`: new `pagination`, `response-cache`, retry, and
+  transport modules, then the `api-client` module, with tests, a lint guard
+  against Node-only APIs, and a browser-target typecheck.
+- `packages/cli/src/lib/api/infrastructure.ts`,
+  `packages/cli/src/lib/response-cache.ts`,
+  `packages/cli/src/lib/sentry-client.ts`: switch to the shared modules.
+  Apart from the narrower cache tiers, CLI behavior does not change.
+- `packages/mcp-core/src/api-client/`: the transport is replaced, then the
+  endpoints, schemas, and errors move to the shared client. The MCP keeps
+  its Zod-to-tool output formatting.
+- `packages/cli/src/lib/api/`: endpoint wrappers, API errors, and
+  pagination move to the shared client. The CLI keeps credential storage,
+  the cache store, region storage, telemetry, and exit-code mapping.
+- `packages/mcp-core` read tools gain a `fresh` input, and generated tool
+  definitions change.
+- `packages/mcp-cloudflare`: in-memory cache, an R2 bucket binding for
+  allowlisted detail responses, and a wrangler config change.
+- `pnpm-workspace.yaml`: a catalog entry for `@sentry/api`, bumped in step 2
+  to the release that contains the shared client.
+- getsentry/sentry-api-schema: receives the shared client in step 2.
+- Snapshot and eval churn in `mcp-core` and `mcp-server-evals`.
diff --git a/openspec/changes/unify-sentry-api-layer/specs/sentry-api-client/spec.md b/openspec/changes/unify-sentry-api-layer/specs/sentry-api-client/spec.md
new file mode 100644
index 000000000..f6a4fa646
--- /dev/null
+++ b/openspec/changes/unify-sentry-api-layer/specs/sentry-api-client/spec.md
@@ -0,0 +1,115 @@
+# Spec Delta
+
+## Purpose
+
+Defines the shared Sentry API client: one implementation of endpoint
+wrappers, errors, response validation, pagination, cache policy, retries,
+and transport, used by the CLI and MCP from `@sentry/toolkit-core` first and
+from `@sentry/api` once it moves there. It runs unchanged in Node,
+Cloudflare Workers, and browsers.
+
+## ADDED Requirements
+
+### Requirement: One API client for every host
+
+The CLI, the stdio MCP server, and the hosted MCP SHALL call the Sentry API
+through the shared client. Neither product SHALL keep its own endpoint
+wrappers, API error classes, retry loop, or pagination for an endpoint the
+shared client covers.
+
+#### Scenario: Same endpoint from both products
+
+- **WHEN** the CLI and an MCP tool fetch the same resource
+- **THEN** both call the same shared endpoint wrapper
+- **THEN** both get the same error classes, and each gets the result type of the schema it passed
+
+### Requirement: Library-agnostic validation
+
+The shared client SHALL validate responses through the Standard Schema
+interface with a schema the host supplies. It SHALL NOT depend on Zod,
+valibot, or another validation library at runtime.
+
+#### Scenario: MCP with Zod
+
+- **WHEN** the MCP calls a shared wrapper with a Zod schema
+- **THEN** the response is validated with it and the result has the schema's output type
+
+#### Scenario: CLI with valibot
+
+- **WHEN** the CLI calls the same wrapper with a valibot schema
+- **THEN** the response is validated with it and Zod is not loaded
+
+#### Scenario: Invalid response
+
+- **WHEN** a response fails the host's schema
+- **THEN** the shared client throws its validation error with the schema's issues
+
+#### Scenario: Endpoint without a generated operation
+
+- **WHEN** `@sentry/api` has no generated operation for an endpoint
+- **THEN** the shared wrapper calls it through the shared transport and validates the response with the host's schema
+
+### Requirement: Portable shared code
+
+The shared client SHALL import only `@sentry/api` and other shared modules
+that move with it, and SHALL use only web-standard APIs. It SHALL NOT import
+`node:*` modules or use `Buffer`, `fs`, `process`, or `AsyncLocalStorage`. A
+check in CI SHALL fail when shared code breaks this rule.
+
+#### Scenario: Browser typecheck
+
+- **WHEN** the shared modules are typechecked against the DOM library with no Node types
+- **THEN** the typecheck passes
+
+#### Scenario: Node-only API added
+
+- **WHEN** a change imports a `node:*` module or uses a Node global in a shared module
+- **THEN** lint fails on that change
+
+### Requirement: Hosts inject their environment
+
+The shared client SHALL take credentials, cache storage, a fresh-read scope,
+logging, and telemetry as injected interfaces. Each host SHALL provide its
+own implementation.
+
+#### Scenario: CLI host
+
+- **WHEN** the CLI creates the client
+- **THEN** it passes its stored credentials with refresh, its on-disk cache store, and its telemetry spans
+
+#### Scenario: MCP host
+
+- **WHEN** the MCP creates the client for a tool call
+- **THEN** it passes the session's access token, and its request-scoped fresh flag through `fresh()`
+
+#### Scenario: Browser host
+
+- **WHEN** a browser app creates the client with session credentials and no cache store
+- **THEN** requests go through `fetch` with the browser's own HTTP caching
+
+### Requirement: Errors keep their API meaning
+
+Shared API errors SHALL carry the HTTP status, the server's detail, and, for
+a 429, `retryAfterMs` from `Retry-After` or `X-Sentry-Rate-Limit-Reset`.
+Hosts SHALL map them to their own presentation, such as CLI exit codes or
+MCP tool messages, without losing those fields.
+
+#### Scenario: Rate limited
+
+- **WHEN** a request is still rate limited after the transport stops retrying
+- **THEN** the shared client throws a rate-limit error with `retryAfterMs`
+- **THEN** the CLI and MCP each report when to retry
+
+### Requirement: Moves into @sentry/api unchanged
+
+The shared client's file layout SHALL match its planned layout inside
+`@sentry/api`, so step 2 copies the modules into
+getsentry/sentry-api-schema without restructuring them. After a published
+`@sentry/api` contains them, toolkit SHALL import them from `@sentry/api`
+and delete its copies.
+
+#### Scenario: Switch to the published package
+
+- **WHEN** a `@sentry/api` release contains the shared client
+- **THEN** the CLI and MCP import it from `@sentry/api`
+- **THEN** the toolkit-core copies are deleted in the same change
diff --git a/openspec/changes/unify-sentry-api-layer/specs/sentry-api-pagination/spec.md b/openspec/changes/unify-sentry-api-layer/specs/sentry-api-pagination/spec.md
new file mode 100644
index 000000000..cbcb7e147
--- /dev/null
+++ b/openspec/changes/unify-sentry-api-layer/specs/sentry-api-pagination/spec.md
@@ -0,0 +1,72 @@
+# Spec Delta
+
+## Purpose
+
+Lets the CLI and MCP fetch a bounded number of rows from any Sentry list
+endpoint and resume exactly where the previous call stopped.
+
+## ADDED Requirements
+
+### Requirement: Limit-bounded walks
+
+A list operation SHALL return at most the requested number of rows. It SHALL
+use the fewest requests that can hold them, with page sizes spread as evenly
+as possible and no page larger than the API maximum of 100.
+
+#### Scenario: Limit above one page
+
+- **WHEN** a caller requests 201 rows from an endpoint with more than 201 rows
+- **THEN** the walk makes three requests of 67 rows each and returns 201 rows
+
+#### Scenario: Limit within one page
+
+- **WHEN** a caller requests 25 rows
+- **THEN** the walk makes one request with a page size of 25
+
+### Requirement: Resume-safe cursors
+
+A walk that stops before the end of the results SHALL return a cursor that
+resumes at the first row the caller has not received, including when it
+stopped inside a page.
+
+#### Scenario: Stop inside a page
+
+- **WHEN** a walk returns 30 rows of a 67-row page and the caller passes the returned cursor back
+- **THEN** the next walk starts at row 31 of that page without repeating or skipping rows
+
+#### Scenario: Cursor accepted by the API and older clients
+
+- **WHEN** a caller sends a returned cursor directly to the Sentry API, or to an older CLI
+- **THEN** the request succeeds and returns rows at or before the resume point, never after it
+
+### Requirement: Page-number cursors keep their page size
+
+Resuming a page-number cursor SHALL reuse the page size encoded in that
+cursor, whatever the new limit.
+
+#### Scenario: Resume with a different limit
+
+- **WHEN** a page-number cursor produced with a page size of 50 is resumed with a limit of 10
+- **THEN** the walk requests pages of 50 and returns the first 10 unseen rows
+
+### Requirement: Bounded page count
+
+A walk SHALL stop after a fixed maximum number of pages. It SHALL return
+the rows collected so far, a resume cursor, and an indication that the page
+cap stopped it.
+
+#### Scenario: Page cap reached
+
+- **WHEN** an endpoint keeps returning next pages beyond the page cap
+- **THEN** the walk stops at the cap and returns a cursor that resumes after the last returned row
+
+### Requirement: Complete walks fail loudly
+
+A walk that must see every row, such as one whose result a mutation depends
+on, SHALL fail rather than return partial results. That applies when a page
+is invalid, a cursor repeats, or the page cap is reached.
+
+#### Scenario: Repeated cursor
+
+- **WHEN** an endpoint returns a next cursor it already returned during the same walk
+- **THEN** the walk fails with an error naming the operation
diff --git a/openspec/changes/unify-sentry-api-layer/specs/sentry-api-response-cache/spec.md b/openspec/changes/unify-sentry-api-layer/specs/sentry-api-response-cache/spec.md
new file mode 100644
index 000000000..b515ce78f
--- /dev/null
+++ b/openspec/changes/unify-sentry-api-layer/specs/sentry-api-response-cache/spec.md
@@ -0,0 +1,171 @@
+# Spec Delta
+
+## Purpose
+
+Lets the CLI and MCP reuse Sentry API GET responses without one user or
+server ever seeing another's data, and without holding more memory or
+storage than the host allows.
+
+## ADDED Requirements
+
+### Requirement: Identity-scoped entries
+
+Every cache entry SHALL be keyed by the requesting identity, the request
+method, and the full request URL including host and normalized query. The
+identity SHALL stay stable across access-token rotation of the same login.
+
+#### Scenario: Different users, same URL
+
+- **WHEN** two identities request the same URL
+- **THEN** neither receives the other's cached response
+
+#### Scenario: Different servers, same path
+
+- **WHEN** one identity requests the same path on two Sentry hosts
+- **THEN** the responses are cached separately
+
+#### Scenario: Token refresh
+
+- **WHEN** an OAuth access token is refreshed for the same login
+- **THEN** entries cached under the previous access token remain usable
+
+### Requirement: Server cache headers take precedence
+
+When a response carries HTTP caching headers, the cache SHALL follow them
+(RFC 9111). Only responses without such headers SHALL use the TTL tiers.
+
+#### Scenario: Server sends no-store
+
+- **WHEN** a response carries `Cache-Control: no-store`
+- **THEN** the response is not cached
+
+#### Scenario: Server sends a validator
+
+- **WHEN** a stale entry has an `ETag` and the server answers the revalidation with 304
+- **THEN** the cached body is served and its freshness is renewed
+
+### Requirement: Fallback TTL tiers
+
+Responses without caching headers SHALL use a TTL by URL class:
+
+- volatile: 60 seconds (issue endpoints, project event details, full
+  traces, log and span queries)
+- no-cache: never cached (autofix and root-cause polling)
+- stable: 5 minutes (everything else, including organization event details
+  and trace-item details)
+
+#### Scenario: Organization event lookup
+
+- **WHEN** `/organizations/{org}/events/{project}:{event_id}/` is fetched without caching headers
+- **THEN** the response is reused for up to 5 minutes
+
+#### Scenario: Issue event lookup
+
+- **WHEN** an issue's latest, oldest, recommended, or specific event is fetched without caching headers
+- **THEN** the response is reused for at most 60 seconds
+
+#### Scenario: Full trace lookup
+
+- **WHEN** a full trace is fetched by trace ID without caching headers
+- **THEN** the response is reused for at most 60 seconds, since spans can still arrive
+
+#### Scenario: Polling endpoint
+
+- **WHEN** autofix state is fetched
+- **THEN** the response is never served from cache
+
+### Requirement: No immutable fallback
+
+No URL class SHALL treat a response as immutable. Without server caching
+headers, no response SHALL be reused for longer than 5 minutes.
+
+#### Scenario: Event re-read after an hour
+
+- **WHEN** any event or trace URL was cached without server headers more than 5 minutes ago
+- **THEN** the next read fetches from the API
+
+### Requirement: Mutations invalidate related entries
+
+A successful non-GET request SHALL invalidate the requesting identity's
+cached entries whose URLs fall under the mutated resource's prefixes. Other
+identities' entries SHALL be unaffected.
+
+#### Scenario: Resolve then list
+
+- **WHEN** an identity updates an issue and then lists issues within the volatile TTL
+- **THEN** the list is fetched from the API, not from cache
+
+### Requirement: Fresh reads bypass the cache
+
+A caller SHALL be able to request a fresh read. A fresh read SHALL fetch
+from the API and replace the cached entry. The CLI exposes this as `--fresh`
+/ `-f`, and MCP read tools as a `fresh` input.
+
+#### Scenario: MCP fresh read
+
+- **WHEN** an MCP read tool is called with `fresh: true`
+- **THEN** every API request made by that call bypasses cached entries
+
+#### Scenario: Fresh scope is host state
+
+- **WHEN** a host marks a scope fresh, such as one MCP tool call
+- **THEN** the host tracks the scope with its own request-scoped state, such as `AsyncLocalStorage`
+- **THEN** the shared client reads it only through an injected `fresh()` callback
+
+### Requirement: Bounded storage
+
+Each storage backend SHALL enforce a byte budget over stored bytes. It SHALL
+enforce a per-entry cap on stored (compressed) size and a ceiling on raw
+size. Entries over either limit SHALL not be stored. When the budget is
+exceeded, the least recently used entries SHALL be evicted first.
+
+#### Scenario: Oversized response
+
+- **WHEN** a response's compressed size is larger than the per-entry cap
+- **THEN** it is returned to the caller and not stored
+
+#### Scenario: Large but compressible response
+
+- **WHEN** a 5 MB trace compresses below the per-entry cap and its raw size is under the ceiling
+- **THEN** it is stored
+
+#### Scenario: Shared Worker isolate
+
+- **WHEN** many identities fill the in-memory cache of one Cloudflare Worker isolate
+- **THEN** total cache memory stays within the configured budget and the isolate does not run out of memory
+
+### Requirement: Compressed entries
+
+Stored entries SHALL be compressed with zstd at level 3 when the runtime
+supports it, and otherwise stored with a supported fallback. Each entry SHALL record its
+encoding. Reading an entry SHALL return a body identical to the original
+response body.
+
+#### Scenario: Runtime without zstd
+
+- **WHEN** the CLI runs on a Node.js version without zstd support
+- **THEN** caching still works using the fallback encoding
+
+### Requirement: Hosted tiers
+
+The hosted MCP SHALL cache every tier in memory. It SHALL persist an entry
+to durable object storage shared across isolates only when its URL matches
+an explicit allowlist of detail endpoints and the response carries a server
+`Cache-Control` with `private` and a positive `max-age`. A persisted entry SHALL expire at the
+lesser of the server `max-age` and 5 minutes. Entries outside the
+allowlist SHALL never be persisted outside the isolate.
+
+#### Scenario: Allowlisted hit in another isolate
+
+- **WHEN** an identity fetches an organization event detail that carries `Cache-Control: private, max-age=300` in one isolate, and fetches it again in another isolate within 5 minutes
+- **THEN** the second fetch is served from durable storage without calling the API
+
+#### Scenario: Allowlisted response without server headers
+
+- **WHEN** an allowlisted response carries no server caching headers
+- **THEN** it is cached in that isolate's memory only
+
+#### Scenario: Volatile entry
+
+- **WHEN** an issue list is cached on the hosted MCP
+- **THEN** it exists only in that isolate's memory
diff --git a/openspec/changes/unify-sentry-api-layer/specs/sentry-api-transport/spec.md b/openspec/changes/unify-sentry-api-layer/specs/sentry-api-transport/spec.md
new file mode 100644
index 000000000..e2c0529ef
--- /dev/null
+++ b/openspec/changes/unify-sentry-api-layer/specs/sentry-api-transport/spec.md
@@ -0,0 +1,114 @@
+# Spec Delta
+
+## Purpose
+
+Defines when a Sentry API request from the CLI or MCP is retried, how long
+it waits first, and what the caller sees when it gives up.
+
+## ADDED Requirements
+
+### Requirement: Retried statuses
+
+The transport SHALL retry only 429, 500, 502, 503, and 504 responses, plus
+timeouts and network errors where the product enables them. Other 5xx codes,
+such as 501 and 505, are deterministic, so retrying them only adds latency.
+
+#### Scenario: Deterministic 5xx
+
+- **WHEN** a GET gets a 501
+- **THEN** the transport returns the failure without retrying
+
+### Requirement: Rate-limited requests are retried for any method
+
+The transport SHALL retry a 429 for any method. Sentry's
+`RatelimitMiddleware` rejects the request in `process_request`, before the
+view runs (`src/sentry/middleware/ratelimit.py`), so replaying it cannot
+repeat a write.
+
+#### Scenario: Rate-limited POST
+
+- **WHEN** a POST without the `idempotent` opt-in gets a 429 whose reset is within the cap
+- **THEN** the transport waits for the reset and sends the POST again
+
+### Requirement: Other failures are retried only for idempotent requests
+
+A 5xx, a timeout, or a network error may come after the endpoint ran. The
+transport SHALL NOT retry one unless the method is GET, HEAD, or OPTIONS, or
+the caller marks the request `idempotent`. A 401 that leads to a successful
+credential refresh SHALL be replayed once for any method.
+
+#### Scenario: POST without the opt-in
+
+- **WHEN** a POST without the `idempotent` opt-in gets a 5xx, a timeout, or a network error
+- **THEN** the transport returns that failure without sending the request again
+
+#### Scenario: POST with the opt-in
+
+- **WHEN** a POST marked `idempotent`, such as a content-addressed chunk upload, gets a 503
+- **THEN** the transport retries it like a GET
+
+#### Scenario: Token refresh
+
+- **WHEN** any request, of any method, gets a 401 and the credential provider refreshes the token
+- **THEN** the transport sends the request once more with the new token
+
+### Requirement: Rate-limited requests wait for the reset
+
+On a 429, the transport SHALL wait for `Retry-After` (seconds or an
+HTTP-date) when present, otherwise for `X-Sentry-Rate-Limit-Reset`. It SHALL
+keep that delay within the range the response `Date` allows, so a skewed
+local clock moves it by at most one second.
+
+#### Scenario: Reset header within the cap
+
+- **WHEN** a GET gets a 429 whose `X-Sentry-Rate-Limit-Reset` is 1 second away and the per-wait cap is 2 seconds
+- **THEN** the transport waits about 1 second and retries the GET
+
+#### Scenario: Skewed local clock
+
+- **WHEN** the local clock is 10 minutes behind the response `Date` and the reset is 1 second after that `Date`
+- **THEN** the transport waits about 1 second, not 10 minutes
+
+### Requirement: Backoff without a usable delay
+
+When a retryable response gives no usable delay, or a 429 is for
+concurrency (`X-Sentry-Rate-Limit-ConcurrentRemaining: 0`), the transport
+SHALL wait a jittered exponential backoff delay.
+
+#### Scenario: Concurrency limit
+
+- **WHEN** a GET gets a 429 with `X-Sentry-Rate-Limit-ConcurrentRemaining: 0`
+- **THEN** the transport retries after a jittered backoff delay, not at the window reset
+
+### Requirement: Retry waits are capped
+
+Each product SHALL set a maximum number of retries, a per-wait cap, and a
+total-wait cap. When the next wait would exceed either cap, the transport
+SHALL stop retrying and return a rate-limit error that says how many seconds
+to wait before trying again. An aborted request SHALL stop waiting at once.
+
+#### Scenario: Reset beyond the cap
+
+- **WHEN** a GET gets a 429 whose reset is 30 seconds away and the per-wait cap is 2 seconds
+- **THEN** the transport does not wait and returns a rate-limit error saying to retry in 30 seconds
+
+#### Scenario: Retries exhausted
+
+- **WHEN** a GET is still rate limited after the last allowed retry
+- **THEN** the caller gets a rate-limit error with the delay from the last response
+
+#### Scenario: Aborted during a wait
+
+- **WHEN** the caller aborts a request while it waits to retry
+- **THEN** the wait ends and the request fails with the abort reason
+
+### Requirement: Retries do not stack
+
+A request SHALL be retried by one layer only. When the MCP sends its
+requests through the shared transport, `SentryApiService` SHALL not retry
+them again.
+
+#### Scenario: MCP on the shared transport
+
+- **WHEN** an MCP tool's GET is rate limited on every attempt through the shared transport
+- **THEN** the Sentry API receives at most `maxRetries + 1` requests for that call
diff --git a/openspec/changes/unify-sentry-api-layer/tasks.md b/openspec/changes/unify-sentry-api-layer/tasks.md
new file mode 100644
index 000000000..0ea075541
--- /dev/null
+++ b/openspec/changes/unify-sentry-api-layer/tasks.md
@@ -0,0 +1,92 @@
+# Tasks
+
+## 1. Version alignment
+
+- [x] 1.1 Add `@sentry/api: 0.400.0` to the pnpm catalog and point `packages/cli` and `packages/mcp-core` at `catalog:`. Verify `pnpm install --frozen-lockfile` succeeds and the lockfile has one `@sentry/api` version.
+- [x] 1.2 Fix any `mcp-core` breakage from the `0.337.0` → `0.400.0` bump. Verify `pnpm --filter @sentry/mcp-core run tsc` and `pnpm --filter @sentry/mcp-core run test` pass.
+
+## 2. CLI cache tier correction
+
+- [x] 2.1 Remove the CLI's `immutable` tier in `packages/cli/src/lib/response-cache.ts`. Move issue events (including `latest`, `oldest`, `recommended`), project event details, and full traces to `volatile`; organization event and trace-item details fall to `stable`. Verify with classifier and fake-clock expiry tests for each `Fallback TTL tiers` scenario.
+- [x] 2.2 Ship it as its own PR (#1681). Verify the CLI unit tests pass.
+
+## 3. Shared pagination
+
+- [x] 3.1 Move `paginate`, `fetchAllPages`, page sizing, and cursor encode/decode from `cli/src/lib/api/infrastructure.ts` into `toolkit-core/src/pagination.ts`. Failures are returned as typed results, and the host supplies the logger. Verify with toolkit-core unit tests that cover each `sentry-api-pagination` scenario.
+- [x] 3.2 Switch the CLI to the shared module, mapping errors to `ApiError` and keeping the `sentry-cli/no-manual-pagination` lint rule. Verify the CLI unit tests pass with no snapshot changes.
+- [x] 3.3 Document the module in `packages/toolkit-core/README.md`, and verify `pnpm run docs:check` passes. Shipped in #1683.
+
+## 4. Shared cache policy and codecs
+
+- [x] 4.1 Move tier classification, key derivation (moved to WebCrypto HMAC), URL normalization, and invalidation prefixes into `toolkit-core/src/response-cache/`. Verify with unit tests for the tier, identity-scoping, and invalidation scenarios. Shipped in #1688.
+- [x] 4.2 Add a codec module (zstd level 3 for every tier, brotli-4 fallback, raw below 256 bytes, `encoding` and `dictId` recorded per entry) with runtime detection. Verify round-trip tests in Node 22, and a test with zstd stubbed out. Shipped in #1695.
+- [x] 4.3 Define the `CacheStore` interface and add the byte-budgeted memory store. Verify tests for LRU eviction, the per-entry cap, and the budget staying within its bound under many identities. Shipped in #1696.
+- [x] 4.4 Re-implement the CLI filesystem store on `CacheStore`, with compressed entries and a byte budget, while reading existing uncompressed entries. Verify the CLI cache tests pass and an old-format entry is still served. Shipped in #1697.
+- [x] 4.5 Add conditional revalidation: send `If-None-Match` for stale entries that have an `ETag`, and treat a 304 as a hit. Verify with a test against a mocked `ETag` endpoint. Shipped in #1698.
+- [x] 4.6 Move the cache policy from `packages/cli/src/lib/response-cache.ts` into `toolkit-core/src/response-cache/`: freshness checks (server cache directives win, the URL tier is the fallback), stale lookup and 304 revalidation, retention (the freshness lifetime plus a 24-hour revalidation window for entries with an `ETag`), response header rebuild, and cache-entry construction. `http-cache-semantics` becomes a `toolkit-core` dependency. The CLI keeps the filesystem store, cache directory, identity fingerprint, env kill switches, telemetry, and the cache-age hint. Verify with toolkit-core unit tests for the moved logic, and the CLI cache tests passing unchanged. Shipped in #1704.
+
+## 5. Shared transport
+
+- [x] 5.0 Add a pure, Workers-safe retry policy in `toolkit-core/src/api-retry.ts`: retryable statuses (429, 500, 502, 503, and 504, not every 5xx, since 501, 505, and the rest are deterministic); a 429 retried for any method, because Sentry's `RatelimitMiddleware` rejects it before the view runs; 5xx, timeouts, and network errors retried only for GET, HEAD, and OPTIONS, or for an explicit per-request `idempotent` opt-in, such as content-addressed chunk uploads; the delay from `Retry-After` (seconds or HTTP-date) or, on a 429, `X-Sentry-Rate-Limit-Reset`, kept within the range the response `Date` allows, and a per-wait and total-wait cap; a jittered exponential fallback, used for concurrency-limit 429s too; and an abortable sleep. The 401 refresh is not part of this policy and stays allowed for any method. MCP `request()` adopts it in the same PR, retrying rate-limited requests and filling `ApiRateLimitError.retryAfter` from the headers. Verify with toolkit-core unit tests for each `sentry-api-transport` retry scenario and MCP client tests. Shipped in #1673; the CLI's interim local fix (#1677) switched to this module in #1710.
+- [x] 5.1 Move auth headers, 401 refresh (any method), timeouts, retry and backoff through `api-retry` (429 for any method; 5xx, timeouts, and network errors for idempotent methods only), redirect validation, and region routing from `cli/src/lib/sentry-client.ts` into `toolkit-core/src/api-transport.ts`, with an injected `CredentialProvider`, `CacheStore`, logger, and span hook. The CLI used to retry every method on 5xx and timeouts, POSTs included; that was a bug, fixed separately before this move. Verify with transport unit tests. Shipped in #1719.
+- [x] 5.2 Switch the CLI to the shared transport, wiring in the database credentials, the filesystem store, and telemetry spans. Verify the CLI unit and e2e tests pass. Shipped in #1719.
+- [x] 5.3 Add a request-scoped fresh-read bypass to the transport, and verify a test that a bypassed request skips cache reads and replaces the entry. Shipped in #1720.
+
+## 6. MCP on the shared transport
+
+- [x] 6.1 Route every `SentryApiService` request, including `@sentry/api` operations, through `createApiTransport`, and drop `SentryApiService`'s own retry loop so retries do not stack. No host-supplied fetch: hosts share the client from group 8 instead. Verify a test where a rate-limited GET reaches the API at most `maxRetries + 1` times, and one where an in-flight abort keeps the caller's reason. Done in #1722.
+- 6.2 Moved to `cli-first-mcp`: the MCP runs commands through the CLI SDK, so it uses the CLI's fetch and cache.
+- [x] 6.3 Add the `fresh` input to read tools through the shared schema helpers. The request-scoped flag lives in the MCP host (`AsyncLocalStorage` in `mcp-core`'s tool handler), and the shared client reads it only through the transport's `fresh()` callback. Regenerate definitions, then verify `pnpm run measure-tokens` and the tool tests pass. Shipped in #1832: catalog tools with `readOnlyHint` and `openWorldHint` (not the docs tools) get the input, costing 130 tokens across the 10 direct read tools.
+
+## 7. Hosted cache
+
+Off the critical path since `cli-first-mcp`. The memory store (7.1, #1833) can land on its own for the catalog tools; the hosted SDK path runs uncached (`cli-first-mcp` 6.2). The R2 tier (7.3, 7.4, #1842) is parked until traffic on the command surface shows whether cross-isolate reuse pays; the cache policy itself moves into `@sentry/api` with the rest of the client.
+
+- [ ] 7.1 Wire the memory store into `mcp-cloudflare` behind `MCP_RESPONSE_CACHE` (`off`/`memory`/`tiered`), with identity taken from the wrapper token's user and grant IDs. Verify the Workers tests pass, and a two-identity isolation test.
+- [ ] 7.2 Confirm `node:zlib` zstd on a deployed preview Worker. If it is unavailable, keep brotli as the hosted codec and record that in `docs/cloudflare/architecture.md`.
+- [ ] 7.3 Add the R2 binding, its URL allowlist (organization event details without `averageColumn`, project trace-item details without `debug`), and `TieredStore`. Persist only allowlisted entries whose response carries `Cache-Control: private` with a positive `max-age`, expiring at the lesser of that `max-age` and 5 minutes. Write in `waitUntil` and add a 1-day lifecycle rule for garbage collection. Verify tests for a cross-isolate allowlisted hit, no R2 write without server headers, expiry enforced on read, and memory-only volatile entries.
+- [ ] 7.4 Get privacy and security sign-off on the 5-minute stale window after access revocation or deletion before setting `MCP_RESPONSE_CACHE=tiered` in production. Record the decision in `docs/cloudflare/architecture.md`.
+- [ ] 7.5 Add cache hit, miss, and eviction metrics and memory-budget logging. Document them in `docs/operations/monitoring.md`, and verify they appear in a preview deploy.
+
+## 8. The shared client in `@sentry/api`
+
+The plan used to finish the whole client in `toolkit-core` and copy it into `@sentry/api` at the end. It now moves what exists into `@sentry/api` first and builds the rest there, since the CLI is the only long-term caller of endpoint wrappers: the MCP's catalog wrappers are deleted when the CLI's commands replace the catalog (`cli-first-mcp`), so porting them is wasted work.
+
+- [x] 8.1 Audit the existing `toolkit-core` modules for anything that will not run in a browser, fix it, and add a guard: a lint rule that bans `node:*` imports and Node globals (`Buffer`, `process`, `AsyncLocalStorage`, and the like) in the shared modules, and a typecheck of them against the DOM library with no Node types. Modules that are host storage, such as the `node:zlib` cache codec, stay outside the guarded set and do not move in step 2. Verify the guard fails on a planted `node:` import. Done in #1732.
+- [x] 8.2 Foundation: create `toolkit-core/src/api-client/` with errors (`ApiError`, rate limits with `retryAfterMs`), `apiPath`, response validation through the Standard Schema interface with host-supplied schemas (Zod in the MCP, valibot in the CLI; no Zod or valibot runtime dependency in shared code), and response reading. The MCP and the CLI use them. Verify the toolkit-core unit tests and both products' suites pass. Done in #1732.
+- [x] 8.3 Move pagination, cache policy, retry policy, and transport under `api-client/`, with the layout they will have inside `@sentry/api`, and rewrite every importer. Verify tsc, lint, and every suite pass with no behavior change. Done in #1736.
+- [x] 8.4 Request core and the first shared domains: `createApiClientCore` with `SentryApiService` on it (#1737), the organizations domain (#1741), and the idempotent-write list both products use for retries (#1820). **Dropped:** moving the remaining MCP domains onto shared wrappers.
+- [ ] 8.5 (#1875) Move `toolkit-core/src/api-client/` into getsentry/sentry-api-schema's `lib/`, reconciling it with what is already there (`browser-client.ts`, `sentry-errors.ts`, `sentry-pagination.ts`) so the package has one error type, one pagination helper, and one transport. Keep the injected interfaces (credentials, `CacheStore`, fresh-read scope, logger, span hook) and the portability rules. Publish a new `@sentry/api`. Verify the package's tests, and that its browser entry builds and makes a request with a mocked `fetch`. (Formerly 9.1.)
+- [ ] 8.6 (#1876) Bump `@sentry/api` in the pnpm catalog, switch the CLI, `mcp-core`, and `mcp-cloudflare` to it, and delete the `toolkit-core` copies in the same PR. Verify `pnpm run tsc && pnpm run lint && pnpm run test`. (Formerly 9.2.)
+- [ ] 8.10 (#1877) Release once 8.6 lands, before 8.7: the first toolkit release since `cli@0.47.0` (`sentry` and `@sentry/mcp-server`), which also validates Craft 3.8 `versioning.files` (#1825). Verify both packages install from npm and `sentry mcp` and `npx @sentry/mcp-server` answer `tools/list`.
+- [ ] 8.7 (#1878) Move the CLI's endpoint wrappers (`cli/src/lib/api/`) onto the `@sentry/api` client, domain by domain, and delete the CLI's own API errors and pagination. The CLI keeps credential storage and refresh, the SQLite and filesystem cache store, region lookup storage, telemetry, and the mapping of API errors to exit codes. Wrappers that only reshape one generated operation are replaced by the operation. Verify the CLI unit tests pass. (Formerly 8.5.)
+- [ ] 8.8 (#1879) Inventory the endpoints the CLI calls by raw path rather than through a generated operation (about 85 call sites in `cli/src/lib/api/` and 55 in `mcp-core/src/api-client/` by a path grep, many duplicates), and get each one into `@sentry/api`: publish it in getsentry/sentry's OpenAPI schema so it generates, or record why it stays raw. Verify the inventory is checked in and each new operation is used.
+- [ ] 8.9 In every PR, keep behavior the same and call out each intentional change in the PR body. Update `docs/contributing/api-patterns.md` and the `@sentry/api` README for the new layering, and verify `pnpm run docs:check` passes. Ongoing: #1737, #1741, and #1820 updated the toolkit docs for their layers. (Formerly 8.7.)
+- Old 8.6 **dropped:** merging the wrappers both products call. After the catalog is deleted, only the CLI calls endpoint wrappers; the MCP calls CLI operations.
+
+## 9. Merged into group 8
+
+Moving the client into `@sentry/api` (old 9.1, 9.2) is now 8.5 and 8.6.
+
+## 10. Trained compression dictionary
+
+**Dropped.** The hosted cache is off the critical path, and a shippable training corpus is not worth building for it.
+
+## 11. MCP tools as a portable face of the CLI
+
+**Replaced by `cli-first-mcp`.** The MCP exposes the CLI's commands through search and execute tools instead of one ported tool per command.
+
+- [x] 11.6 `@sentry/mcp-server` as a dependency-free bundle of the server built from CLI source. Done in #1731. Under `cli-first-mcp` it carries the exposed command handlers instead of catalog tools (7.1 there).
+- 11.1, 11.2, 11.4: replaced by `cli-first-mcp` group 6, which runs the CLI SDK itself on Workers, one instance per request with persistence off. The per-domain split into portable operations (11.1) survives only as a fallback for domains Workers cannot run (6.7 there).
+- 11.3 **Dropped:** moving each MCP tool into `sentry/mcp`. The command surface exposes commands generically.
+- 11.5 moved to `cli-first-mcp` 6.8 (OAuth scope comparison).
+- 11.7 Partly done in #1731: an oxlint rule bans `sentry` in `mcp-core` and `toolkit-core`, and `lint:deps` fails on workspace cycles. `mcp-cloudflare` now imports the CLI SDK, so the remaining rule is set when `cli-first-mcp` 6.5 lands.
+
+## 12. Integration
+
+- [ ] 12.1 Run `pnpm run tsc && pnpm run lint && pnpm run test` and the MCP eval suite on the final state, and record the results in the PR.
+
+## Workflow follow-up
+
+- Archive the change after review once all tasks are complete.
+- Follow up on getsentry/sentry#128818 and getsentry/sentry#128828. When the server headers ship, confirm the CLI honors them and enable the R2 tier.