Add CIMD support for hosted MCP OAuth

[dcramer]

Summary

Add and validate support for OAuth Client ID Metadata Documents (CIMD) for the hosted MCP Cloudflare OAuth proxy.

CIMD lets OAuth clients use an HTTPS URL as their client_id, where that URL serves the client metadata document. In MCP 2025-11-25, clients and authorization servers SHOULD support CIMD; Dynamic Client Registration is now a MAY fallback for compatibility.

Current State

Confirmed from source inspection:

• @cloudflare/workers-oauth-provider supports CIMD in the version currently installed by this repo (0.3.0) and in the latest published version (0.8.0).
• The provider requires both:
  • clientIdMetadataDocumentEnabled: true
  • the Workers global_fetch_strictly_public compatibility flag
• Our wrangler.jsonc, wrangler.canary.jsonc, and wrangler.test.jsonc already include global_fetch_strictly_public.
• Our Cloudflare OAuth proxy does not currently pass clientIdMetadataDocumentEnabled: true to new OAuthProvider(...).
• Our path-scoped authorization-server metadata compatibility shim does not advertise client_id_metadata_document_supported.
• Our protected-resource metadata implementation is separate and already path-scoped for /mcp....
• The MCP TypeScript SDK has client-side CIMD support in @modelcontextprotocol/sdk@1.26.0: it checks client_id_metadata_document_supported, uses provider.clientMetadataUrl as the client_id when available, and falls back to Dynamic Client Registration otherwise.
• I did not find equivalent direct CIMD support in @ai-sdk/mcp@1.0.52.
• Our repo-local mcp-test-client always uses Dynamic Client Registration today.

Relevant files:

• packages/mcp-cloudflare/src/server/index.ts
• packages/mcp-cloudflare/src/server/authorization-server-metadata.ts
• packages/mcp-cloudflare/src/server/protected-resource-metadata.ts
• packages/mcp-cloudflare/wrangler*.jsonc
• packages/mcp-test-client/src/auth/oauth.ts

Goals

• Enable CIMD support in the hosted Cloudflare OAuth proxy.
• Advertise CIMD support consistently through authorization-server metadata.
• Preserve Dynamic Client Registration fallback for clients that do not support CIMD.
• Keep path-scoped MCP resource behavior intact for /mcp, /mcp/{org}, and /mcp/{org}/{project}.
• Add focused tests that prove the behavior and guard the security-sensitive edge cases.

Non-Goals

• Do not remove Dynamic Client Registration.
• Do not change stdio auth; stdio uses Sentry device-code auth and is unrelated to CIMD.
• Do not implement a custom CIMD fetcher unless the Cloudflare provider behavior proves insufficient.
• Do not add enterprise-managed authorization or ID-JAG support as part of this work.

Proposed Plan

1. Enable Cloudflare provider support

• Add clientIdMetadataDocumentEnabled: true to new OAuthProvider(...) in packages/mcp-cloudflare/src/server/index.ts.
• Keep the existing global_fetch_strictly_public flag in all Wrangler configs.
• Confirm local/test runtime exposes the flag sufficiently for provider metadata to report support.

2. Advertise support in metadata

• Verify root authorization metadata from the Cloudflare provider reports:

  {
    "client_id_metadata_document_supported": true
  }

• Update createScopedAuthorizationServerMetadataResponse(...) so path-scoped compatibility metadata also includes client_id_metadata_document_supported: true.

• Ensure scoped metadata still includes the resource-bound authorization endpoint for /mcp... URLs.

3. Add server behavior tests

Add Cloudflare package tests covering:

• /.well-known/oauth-authorization-server includes client_id_metadata_document_supported: true.
• /.well-known/oauth-authorization-server/mcp includes client_id_metadata_document_supported: true.
• /.well-known/oauth-authorization-server/mcp/{org}/{project} includes client_id_metadata_document_supported: true.
• Existing protected-resource metadata still returns the exact path/query resource identifier.
• Existing WWW-Authenticate patching still points to path-specific protected-resource metadata.

4. Add CIMD flow tests

Use mocked fetch or worker test harness support to simulate a client metadata URL.

Cover successful flow:

• Authorization request uses client_id=https://client.example/oauth/client.json.
• Provider fetches the metadata document.
• Metadata document includes matching client_id, client_name, redirect_uris, grant_types, response_types, and token_endpoint_auth_method: "none".
• Authorization request redirect URI is accepted only when listed in the fetched metadata document.

Cover failure cases:

• Metadata URL fetch returns non-200.
• Metadata document client_id does not exactly match the metadata URL.
• Metadata document has no redirect_uris.
• Authorization request uses a redirect URI not present in the metadata document.
• Metadata document uses disallowed token_endpoint_auth_method, such as client_secret_post.
• Oversized metadata response is rejected by provider behavior if feasible to exercise.

5. Review consent and phishing UX

CIMD changes what the user sees during OAuth consent because the client identity is now fetched from a URL.

Review the authorization approval UI and tests to ensure it displays enough information for user trust decisions:

• client name
• client metadata host or full client ID URL
• redirect URI hostname
• warnings or clear treatment for localhost redirect URIs

If existing UI only shows the friendly client name, add the hostname/redirect host before enabling broadly.

6. Decide whether to update repo-local test client

The current mcp-test-client is DCR-only. Options:

• Leave it as DCR-only and rely on dedicated Cloudflare tests for CIMD.
• Add optional CIMD support with a clientMetadataUrl config/flag so it can exercise the new path end-to-end.

If we update it, also fix the adjacent MCP 2025-11-25 drift where token requests should include the RFC 8707 resource parameter; it currently sends resource on authorization but not token exchange.

7. Validate against real clients

After unit/integration tests:

• Test with an MCP SDK OAuth client configured with clientMetadataUrl.
• Verify the SDK chooses CIMD when metadata advertises support.
• Verify the same SDK falls back to DCR when the flag is disabled or metadata omits support.
• Test at least one non-CIMD client to confirm DCR remains working.

8. Rollout

• Prefer canary first.
• Watch OAuth telemetry for:
  • invalid client errors
  • metadata fetch failures
  • redirect URI validation failures
  • registration volume changes
• If canary is clean, enable in production.

Acceptance Criteria

• Cloudflare OAuth metadata advertises client_id_metadata_document_supported: true when CIMD is enabled.
• Path-scoped authorization metadata advertises the same support.
• URL-based client_id authorization requests work when the metadata document is valid.
• Invalid metadata documents fail safely.
• Redirect URIs are validated against fetched metadata.
• Dynamic Client Registration still works.
• Existing scoped MCP OAuth flows continue to bind the correct /mcp... resource.
• Tests cover success and key failure cases.
• pnpm run tsc && pnpm run lint && pnpm run test passes before merge.

Open Questions

• Should CIMD be always-on in production once tests pass, or controlled by an env flag for staged rollout?
• Do we need additional allowlist/trust policy controls for client metadata domains, or is open CIMD acceptable for our hosted MCP server?
• Should the repo-local mcp-test-client gain first-class CIMD support, or is that better left to SDK/client compatibility QA?
• Should we upgrade @cloudflare/workers-oauth-provider from 0.3.0 to 0.8.0 before enabling this, given newer versions include related metadata/resource handling improvements?

References

• MCP authorization spec: https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization
• OAuth Client ID Metadata Document draft: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document
• Cloudflare provider CIMD docs: https://github.com/cloudflare/workers-oauth-provider#client-id-metadata-document-cimd-support
• Cloudflare global_fetch_strictly_public: https://developers.cloudflare.com/workers/configuration/compatibility-flags/#global-fetch-strictly-public

[linear-code]

MCP-988

[dcramer]

Spec-first implementation plan

This should be implemented from the MCP 2025-11-25 authorization requirements outward, not from the Cloudflare provider toggle inward.

Spec baseline

Target MCP spec: 2025-11-25 authorization.

Requirements and compatibility points this change should satisfy:

• HTTP MCP authorization should conform to the MCP authorization spec.
• MCP servers must expose OAuth 2.0 Protected Resource Metadata with at least one authorization_servers entry.
• MCP authorization servers must expose OAuth Authorization Server Metadata or OpenID Connect Discovery metadata.
• Authorization servers and clients should support OAuth Client ID Metadata Documents.
• Clients should prefer:
  1. pre-registered client info,
  2. CIMD when client_id_metadata_document_supported: true,
  3. Dynamic Client Registration when registration_endpoint is available.
• Implementations that support CIMD must follow the OAuth Client ID Metadata Document draft:
  • URL client IDs must be HTTPS URLs with a non-root path.
  • fetched metadata must contain matching client_id.
  • fetched metadata must contain valid redirect_uris.
  • authorization requests must validate redirect_uri against fetched metadata.
  • authorization servers must consider SSRF and abuse risks.
• MCP clients must include the RFC 8707 resource parameter in both authorization and token requests. This is adjacent drift in the repo-local test client, not a blocker for hosted proxy CIMD.

Phase 1: express spec requirements as tests

Add/extend tests before changing runtime behavior.

Metadata tests:

• Root authorization metadata advertises client_id_metadata_document_supported: true when CIMD is enabled.
• Path-scoped compatibility metadata for /mcp advertises client_id_metadata_document_supported: true.
• Path-scoped compatibility metadata for /mcp/{org} and /mcp/{org}/{project} advertises client_id_metadata_document_supported: true.
• Existing path-scoped protected-resource metadata still returns the exact resource value, including path and query.
• Existing 401 WWW-Authenticate patching still points clients at the matching path-scoped protected-resource metadata endpoint.

Provider behavior tests:

• URL-formatted client_id with a valid metadata document reaches the approval dialog.
• The approval dialog uses fetched client metadata.
• POST approval validates the selected redirect URI against the fetched metadata.
• Invalid metadata fails safely:
  • fetch returns non-200,
  • client_id mismatch,
  • missing or empty redirect_uris,
  • requested redirect_uri not listed,
  • disallowed token_endpoint_auth_method, such as client_secret_post.

Consent UI tests:

• Approval UI displays the client name.
• Approval UI displays enough origin information to make CIMD safe:
  • client metadata URL or client ID host,
  • requested redirect URI,
  • redirect URI hostname.
• Localhost redirect URIs are visibly identifiable.

Phase 2: enable provider support

Change packages/mcp-cloudflare/src/server/index.ts:

• Add clientIdMetadataDocumentEnabled: true to new OAuthProvider(...).
• Keep clientRegistrationEndpoint: "/oauth/register" unchanged so Dynamic Client Registration remains a fallback.
• Do not add custom metadata fetching unless tests prove the provider behavior is insufficient.

Wrangler configs:

• Keep global_fetch_strictly_public in prod, canary, and test config.
• Add/adjust a test assertion if possible so CI fails if the flag is removed.

Phase 3: advertise support consistently

Change packages/mcp-cloudflare/src/server/authorization-server-metadata.ts:

• Add client_id_metadata_document_supported: true to path-scoped compatibility metadata.
• Preserve the existing resource-bound authorization_endpoint.
• Preserve registration_endpoint for DCR fallback.

Confirm root metadata from the provider also includes the field after Phase 2.

Phase 4: harden consent and logging

Review packages/mcp-cloudflare/src/server/lib/approval-dialog.ts.

If the UI does not already show the URL-based client identity clearly enough:

• Add a small client identity line derived from client.clientId when it is URL-shaped.
• Prefer displaying host + path or full URL in a controlled, sanitized way.
• Keep existing redirect URI warning behavior.
• Avoid logging secrets or full token/code values.

Review packages/mcp-cloudflare/src/server/oauth/routes/authorize.ts:

• Confirm GET and POST both rely on provider lookupClient(clientId) for CIMD clients.
• Confirm invalid redirect errors remain 4xx/logWarn and do not become Sentry-captured 5xx noise.

Phase 5: optional repo-local client update

Do not block server CIMD support on the repo-local test client.

Follow-up options:

• Leave mcp-test-client DCR-only.
• Or add optional CIMD mode using a configured clientMetadataUrl.

If touching mcp-test-client, also fix token exchange to include the RFC 8707 resource parameter, since MCP 2025-11-25 requires it in both authorization and token requests.

Phase 6: real-client QA

Use a real MCP SDK OAuth client configured with clientMetadataUrl.

Verify:

• When metadata advertises support, SDK uses URL client ID and skips DCR.
• When support is absent, SDK falls back to DCR.
• Existing DCR-only clients still connect.
• Scoped resources still work:
  • /mcp
  • /mcp/{org}
  • /mcp/{org}/{project}

Phase 7: rollout

Roll out canary first.

Watch telemetry for:

• invalid_client
• redirect URI validation failures
• metadata fetch failures
• OAuth registration volume changes
• consent prompt volume changes

Then deploy production once canary is clean.

Implementation order

1. Metadata tests.
2. Provider behavior tests.
3. Enable clientIdMetadataDocumentEnabled.
4. Add scoped metadata advertisement.
5. Fix consent UI if tests show missing identity context.
6. Run package tests.
7. Run full quality gate before merge.

Suggested validation commands

pnpm --filter @sentry/mcp-cloudflare test
pnpm --filter @sentry/mcp-cloudflare tsc
pnpm run tsc && pnpm run lint && pnpm run test