fix(mcp): handle provider OAuth interoperability gaps

[reachjalil]

What this fixes

This is a focused follow-up to #2810 for OAuth interoperability gaps found against live remote MCP providers. The implementation is provider-neutral and applies to Den-managed OpenWork Connect.

Resource discovery aliases

Some protected-resource metadata identifies a resource as an origin with a trailing /, while advertising the same origin without / as its OAuth discovery alias. OpenWork previously rejected that constrained equivalence and then incorrectly fell back to asking for a pre-registered client ID and secret.

This PR accepts only HTTP(S) root-origin equivalence for a resource-scoped discovery alias. The authorization-server metadata issuer remains canonical, and authorization-response issuer validation remains exact.

For https://mcp.vercel.com, discovery now resolves the advertised dynamic-registration flow without asking the administrator for a client ID or secret.

Deferred OAuth challenges

Some MCP servers allow unauthenticated initialize and challenge only on tools/list. OpenWork previously treated initialize alone as a usable connection, closed the authorization window, and left the connection without credentials.

This PR requests one bounded tool page before returning connected, both during initial connection and after the OAuth callback. A late challenge now starts the normal OAuth flow. If token exchange succeeds but initialize or tool discovery then fails, the newly exchanged credential is invalidated through the existing cleanup path.

For https://api.descript.com/v2/mcp, this means the OAuth challenge raised at tool discovery is no longer missed.

Connection handoff screen

The shared OAuth popup immediately renders a small OpenWork-styled Preparing your connection screen while Den performs discovery. It provides an accessible live status, subtle animation, and a reduced-motion fallback before the same window navigates to the provider.

Callback compatibility and rollout

• The deployment-wide callback is the default for new OAuth setup.
• Existing connections that were created with a connection-specific callback keep that callback on reconnect; there is no migration toggle and no credential rewrite.
• In-flight version-one signed state remains accepted only by the legacy callback route for its existing ten-minute lifetime.
• Shared-callback state is rejected by legacy routes, even when a path ID matches.
• Pre-registered OAuth clients, client metadata documents, and dynamic client registration remain supported.
• Local/direct engine MCP and the engine-to-Den meta-MCP are unchanged.

Relationship to #2851

• This PR (fix(mcp): handle provider OAuth interoperability gaps #2853) owns generic provider OAuth discovery, callback validation, first-tool-page usability, and the pre-redirect popup.
• fix(den): recover imported MCP authentication setup #2851 owns plugin/chat import classification, marketplace readiness, binding preservation, and administrator/member recovery.
• Merge fix(mcp): handle provider OAuth interoperability gaps #2853 first, then fix(den): recover imported MCP authentication setup #2851. fix(den): recover imported MCP authentication setup #2851 deliberately reuses the runtime validation implemented here instead of adding provider logic to the import path.

Visual walkthrough

Add the Vercel MCP server

Entering https://mcp.vercel.com completes OAuth discovery automatically. The form shows provider-advertised permissions and does not ask for a client ID or secret.

Start the OAuth handoff

Clicking Connect opens this lightweight status screen immediately, then navigates the same popup to the provider.

Security boundaries

• No provider-specific runtime branch was added.
• Root alias equivalence is limited to HTTP(S), the same origin, the root path, and no query or fragment.
• Authorization-response issuer checks remain exact.
• Tokens and client secrets remain Den-owned.
• Declaring a connection usable now includes one bounded first-page tools/list request because tool access is the capability OpenWork exposes and where compliant servers may issue the OAuth challenge.

Validation

Branch head: 8a42366c, rebased onto current upstream/dev at 55033420.

• @openwork/enterprise-mcp-client: typecheck passed.
• @openwork/enterprise-mcp-client: build passed.
• @openwork/enterprise-mcp-client: 40 passed, including post-callback rollback when initialize succeeds but tool discovery fails.
• Den API connection/callback compatibility suite: 15 passed against an isolated current-schema database.
• Den Web OAuth popup and authorization-URL suite: 8 passed.
• Combined with fix(den): recover imported MCP authentication setup #2851 in a fresh isolated worktree:
  • enterprise MCP client: 40 passed
  • import/readiness API suites: 34 passed
  • connection/callback API suite: 15 passed
  • combined Web suites: 20 passed
  • enterprise client build and both affected TypeScript checks passed
  • git diff --check passed
• GitHub Actions passed: Den API, Den Web, and inference builds; Linux and macOS test matrices; Helm validation; and i18n audit.
• Live requirements discovery:
  • https://mcp.vercel.com: ready; issuer https://vercel.com; dynamic registration; no warnings.
  • https://api.descript.com/v2/mcp: ready; issuer https://api.descript.com; client-metadata registration; no warnings.
• During local iteration, a pre-registered OAuth provider completed both the existing connection-specific callback and the deployment-wide callback after the provider allowlist change propagated.

Not run / external limits

• A full live OAuth consent and tool call was not completed against Vercel or Descript because that requires provider accounts and consent.
• Fork Vercel preview contexts can report deployment-authorization failures because the fork cannot deploy to Different AI's projects. Those permissions are separate from the MCP provider behavior and repository checks covered here.

Review map

• Usability and callback validation: packages/enterprise-mcp-client/src/enterprise-mcp-client.ts
• Constrained alias comparison: packages/enterprise-mcp-client/src/oauth-resource-alias.ts
• Discovery and canonical issuer binding: packages/enterprise-mcp-client/src/requirements-discovery.ts and oauth-discovery-binding.ts
• Callback compatibility routes: ee/apps/den-api/src/routes/org/mcp-connections.ts
• Pre-redirect popup: ee/apps/den-web/app/(den)/dashboard/_components/mcp-authorization-url.ts

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
openwork-landing	Ready	Preview, Comment, Open in v0	Jul 16, 2026 7:17pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
openwork-diagnostics	Skipped		Jul 16, 2026 7:17pm

[vercel]

@reachjalil is attempting to deploy a commit to the Different AI Team on Vercel.

A member of the Team first needs to authorize it.