feat(cloudflare): Add hosted OAuth CIMD support

AGENTS.md

@@ -1,132 +1,59 @@
-# AGENTS.md
-Sentry MCP is a Model Context Protocol server that exposes Sentry's error tracking and performance monitoring to AI assistants through 19 tools.
-
-## Principles
-
-- **Type Safety**: Prefer strict types over `any` - they catch bugs and improve tooling. Use `unknown` for truly unknown types.
-- **Security**: Never log secrets. Validate external input. See docs/operations/security.md.
-- **Simplicity**: Follow existing patterns. Check neighboring files before inventing new approaches.
-
-## Constraints
-
-- **Tool count**: Target ≤20, hard limit 25 (AI agents have limited tool slots).
-- **Quality gate**: `pnpm run tsc && pnpm run lint && pnpm run test` must pass before committing.
-
-## Repository Structure
-
-```
-sentry-mcp/
-├── packages/
-│   ├── mcp-core/            # Core MCP implementation (private)
-│   │   └── src/
-│   │       ├── tools/       # 19 tool modules
-│   │       ├── server.ts    # buildServer()
-│   │       ├── api-client/  # Sentry API
-│   │       └── internal/    # Shared utils
-│   ├── mcp-server/          # stdio transport (@sentry/mcp-server on npm)
-│   ├── mcp-cloudflare/      # Web app + OAuth
-│   ├── mcp-server-evals/    # AI evaluation tests
-│   ├── mcp-server-mocks/    # MSW mocks
-│   └── mcp-test-client/     # CLI test client
-└── docs/                    # All documentation
-```
-
-## Documentation Map
-
-- docs/README.md — Full documentation index
-
-**Read before tool changes:**
-- docs/contributing/adding-tools.md — Tool implementation guide
-- docs/contributing/tool-responses.md — Tool output policy and QA review checklist
-- docs/testing/overview.md — Testing requirements and snapshot policy
-- docs/contributing/common-patterns.md — Error handling, Zod schemas, shared formatting patterns
-- docs/contributing/error-handling.md — Error types and propagation
-
-**Contributing:**
-- docs/contributing/api-patterns.md — Sentry API client usage
-- docs/contributing/coding-guidelines.md — TypeScript and code style guidance
-- docs/contributing/documentation-style-guide.md — Documentation style guide
-- docs/contributing/pr-management.md — Commit and PR guidelines
-- docs/contributing/quality-checks.md — Pre-commit checklist
-- docs/contributing/search-events-api-patterns.md — Search Events API patterns
-
-**Testing:**
-- docs/testing/overview.md — Unit, snapshot, eval, and agent CLI testing
-- docs/testing/stdio.md — Stdio transport testing
-- docs/testing/remote.md — Remote server and OAuth testing
-
-**Architecture and Operations:**
-- docs/architecture/overview.md — System design
-- docs/operations/security.md — Authentication and security patterns
-- docs/operations/stdio-auth.md — Device code flow, token caching, client ID architecture
-- docs/operations/oauth-signout-playbook.md — Remote OAuth diagnostic runbook
-- docs/operations/embedded-agents.md — LLM provider configuration for AI-powered tools
-- docs/operations/github-actions.md — GitHub Actions guidance
-- docs/operations/logging.md — Logging guidance
-- docs/operations/monitoring.md — Monitoring guidance
-- docs/operations/token-cost-tracking.md — Tool definition token cost tracking
-
-**Cloudflare:**
-- docs/cloudflare/overview.md — Cloudflare package overview
-- docs/cloudflare/architecture.md — Cloudflare architecture
-- docs/cloudflare/oauth-architecture.md — Cloudflare OAuth architecture
-
-**Integrations:**
-- docs/integrations/claude-code-plugin.md — Plugin structure and agent prompts
-- docs/integrations/ide-instructions-refactor.md — IDE instruction refactor notes
-
-**Specs:**
-- docs/specs/README.md — Specs index
-- docs/specs/embedded-agent-openai-routing.md — Embedded agent OpenAI routing spec
-- docs/specs/search-events.md — Search Events spec
-- docs/specs/subpath-constraints.md — Subpath constraints spec
-
-**Releases:**
-- docs/releases/stdio.md — npm package release
-- docs/releases/cloudflare.md — Cloudflare deployment
+# Agent Instructions
+
+## Package Manager
+- Use **pnpm**; Node.js must be `>=20`.
+- `CLAUDE.md` is a symlink to this file; do not maintain a divergent copy.
+
+## Package Roles
+| Package | Role |
+|---|---|
+| `packages/mcp-core` | Shared MCP server, tools, schemas, Sentry API client, and tool definitions. |
+| `packages/mcp-server` | Published stdio transport package (`@sentry/mcp-server`). |
+| `packages/mcp-cloudflare` | Hosted web app, HTTP `/mcp` transport, OAuth authorization server routes, and demo chat web client. |
+| `packages/mcp-test-client` | Local CLI for stdio/HTTP transport QA, OAuth, DCR, CIMD, and agent-mode testing. |
+| `packages/mcp-server-mocks` | MSW fixtures and mocks for tests. |
+
+## OAuth And Transport Boundaries
+- `packages/mcp-server` uses stdio auth flows; do not mix it with hosted OAuth behavior.
+- In `packages/mcp-cloudflare`, `/oauth/*` is the hosted OAuth authorization server.
+- In `packages/mcp-cloudflare`, `/mcp` is the protected HTTP MCP resource; `?agent=1` switches to embedded-agent mode.
+- In `packages/mcp-cloudflare`, `/api/chat` is the demo chat backend acting as an MCP client of `/mcp`.
+- The demo chat OAuth client identity must stay separate from the MCP resource identity.
+- Preserve Dynamic Client Registration unless a change explicitly removes it.
 
 ## Commands
-
-```bash
-# Development
-pnpm run dev                              # Start dev server
-pnpm run build                            # Build all packages
-
-# Testing
-pnpm -w run cli --transport stdio "q"      # Test MCP tools
-pnpm -w run cli --transport stdio --access-token=TOKEN "q"
-pnpm -w run cli --transport stdio --agent "query"
-
-# Quality (run before committing)
-pnpm run tsc && pnpm run lint && pnpm run test
-
-# Token overhead
-pnpm run measure-tokens                   # Check tool definition size
-
-# Definitions (run after changing tools, skills, or agent prompts)
-pnpm run --filter @sentry/mcp-core generate-definitions
-```
-
-## QA Playbook
-
-For MCP tool QA, use the `mcp-qa` skill at `.agents/skills/mcp-qa/SKILL.md`:
-stdio-first local CLI and real agent clients; Cloudflare HTTP or `/mcp` only
-for transport, OAuth, routing, or hosted-server compatibility.
-
-## Task Management
-
-Use `/dex` skill to coordinate complex work. Create tasks with full context, break down into subtasks, complete with detailed results.
-
-## Workflow
-
-1. Check neighboring files for existing patterns before writing new code.
-2. When adding or modifying Sentry API endpoint usage, ALWAYS validate the endpoint behavior against the Sentry source code in `~/src/sentry` instead of assuming docs or client parameters are authoritative.
-3. Update relevant docs when changing functionality.
-4. Follow docs/contributing/error-handling.md for error types.
-5. Follow docs/contributing/pr-management.md for commits and PRs.
+| Task | Command |
+|---|---|
+| Full typecheck | `pnpm run tsc` |
+| Full lint | `pnpm run lint` |
+| Full tests | `pnpm run test` |
+| Cloudflare tests | `pnpm --filter @sentry/mcp-cloudflare test` |
+| Cloudflare typecheck | `pnpm --filter @sentry/mcp-cloudflare tsc` |
+| CLI QA | `pnpm -w run cli --transport http --mcp-host=http://localhost:5173/mcp --list-tools` |
+| Generate definitions | `pnpm run --filter @sentry/mcp-core generate-definitions` |
+
+## References
+| Need | File |
+|---|---|
+| Docs index | `docs/README.md` |
+| Tool changes | `docs/contributing/adding-tools.md` |
+| Tool responses | `docs/contributing/tool-responses.md` |
+| Error handling | `docs/contributing/error-handling.md` |
+| Testing | `docs/testing/overview.md` |
+| Remote/OAuth QA | `docs/testing/remote.md` |
+| OAuth architecture | `docs/cloudflare/oauth-architecture.md` |
+| Security | `docs/operations/security.md` |
+| PR guidance | `docs/contributing/pr-management.md` |
+
+## Conventions
+- Prefer strict TypeScript; use `unknown` instead of `any` for unknown values.
+- Never log secrets or tokens.
+- When changing Sentry API endpoint usage, validate behavior against `~/src/sentry`.
+- Update docs for behavior changes.
+- Run the relevant focused tests before the full quality gate.
+- Run `pnpm run --filter @sentry/mcp-core generate-definitions` after changing tools, skills, or agent prompts.
 
 ## Commit Attribution
-
 AI commits MUST include:
 ```
 Co-Authored-By: (the agent model's name and attribution byline)

README.md

@@ -166,7 +166,7 @@ To contribute changes, you'll need to set up your local environment:
    - Edit `packages/mcp-cloudflare/.env` and add:
      - `SENTRY_CLIENT_ID=your_development_sentry_client_id`
      - `SENTRY_CLIENT_SECRET=your_development_sentry_client_secret`
-     - `COOKIE_SECRET=my-super-secret-cookie`
+     - `COOKIE_SECRET=my-super-secret-cookie` (optional for local dev; `pnpm dev` provides a development-only default when omitted)
 
 4. **Start the development server:**
 

docs/cloudflare/oauth-architecture.md

@@ -101,11 +101,12 @@ sequenceDiagram
 
 The MCP OAuth Provider is built with `@cloudflare/workers-oauth-provider` and provides:
 
-1. **Dynamic client registration** - MCP clients can register on-demand
-2. **PKCE support** - Secure authorization code flow
-3. **Token management** - Issues and validates MCP tokens
-4. **Consent UI** - Custom approval screen for permissions
-5. **Token encryption** - Stores Sentry tokens encrypted in MCP token props
+1. **Client ID metadata documents (CIMD)** - MCP clients can use an HTTPS metadata URL as `client_id`
+2. **Dynamic client registration fallback** - MCP clients can still register on-demand at `/oauth/register`
+3. **PKCE support** - Secure authorization code flow
+4. **Token management** - Issues and validates MCP tokens
+5. **Consent UI** - Custom approval screen for permissions
+6. **Token encryption** - Stores Sentry tokens encrypted in MCP token props
 
 ### Sentry OAuth Integration
 
@@ -124,13 +125,19 @@ The integration with Sentry OAuth happens through:
 sequenceDiagram
     participant Agent as AI Agent
     participant MCPOAuth as MCP OAuth Provider
+    participant ClientMeta as Client Metadata URL
     participant KV as Cloudflare KV
     participant User as User
     participant MCP as MCP Server
 
-    Agent->>MCPOAuth: Register as client
-    MCPOAuth->>KV: Store client registration
-    MCPOAuth-->>Agent: MCP Client ID & Secret
+    alt CIMD client
+        Agent->>MCPOAuth: Use HTTPS metadata URL as client_id
+        MCPOAuth->>ClientMeta: Fetch client metadata document
+    else DCR fallback
+        Agent->>MCPOAuth: Register as client
+        MCPOAuth->>KV: Store client registration
+        MCPOAuth-->>Agent: MCP Client ID & Secret
+    end
 
     Agent->>MCPOAuth: Request authorization
     MCPOAuth->>User: Show MCP consent screen
@@ -166,10 +173,16 @@ const oAuthProvider = new OAuthProvider({
   authorizeEndpoint: "/oauth/authorize",
   tokenEndpoint: "/oauth/token", 
   clientRegistrationEndpoint: "/oauth/register",
+  clientIdMetadataDocumentEnabled: true,
   scopesSupported: Object.keys(SCOPES),
 });
 ```
 
+With CIMD enabled, the authorization-server metadata advertises
+`client_id_metadata_document_supported: true`. URL client IDs must resolve to
+metadata for a public authorization-code client; opaque dynamically registered
+client IDs continue to use the stored DCR metadata.
+
 ### 2. API Handler
 
 The `apiHandler` is a protected endpoint that requires valid OAuth tokens:

openspec/changes/add-cimd-hosted-oauth/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-17