Fix MCP OAuth callback URL leaking instance name

[threepointone]

Closes #854

Problem

When an agent uses sendIdentityOnConnect: false to protect sensitive instance names (session IDs, user IDs), the MCP OAuth callback URL still exposes the raw instance name:

https://example.com/agents/secure-agent/secret-user-id-123/callback

This URL is sent to the remote OAuth provider as redirect_uri, displayed in the browser address bar, and saved in browser history — completely undermining the security intent. Additionally, the hardcoded /agents/{class}/{name}/callback pattern doesn't work for developers using basePath routing with getAgentByName.

Design decisions

callbackPath is required when sendIdentityOnConnect: false.
Rather than silently hashing or obfuscating the instance name (which would require complex coordination between the routing layer and DO storage), we make the developer explicitly provide a safe callback path. This is consistent with how basePath already works — if you've opted into custom routing to protect instance names, you handle the routing yourself via getAgentByName. The error message is actionable and tells the developer exactly what to do.

callbackPath is optional when sendIdentityOnConnect: true.
The default auto-constructed URL (/agents/{class}/{name}/callback) still works for developers who haven't opted out of identity exposure. This keeps the simple case simple. Developers can still provide callbackPath if they prefer cleaner URLs or a different routing pattern.

Callback detection uses state parameter with origin + pathname verification.
Previously, isCallbackRequest() checked url.includes("/callback") as a loose heuristic — this would break with custom callback paths (e.g., /mcp-oauth-return). The state query parameter (format: {nonce}.{serverId}) is now the primary mechanism for identifying which server a callback belongs to. As defense-in-depth, we also verify that the request's origin and pathname match the registered callback_url for that server, preventing unrelated GET requests with a state param from being intercepted.

Changes

• AddMcpServerOptions type — new callbackPath?: string field with JSDoc documenting it should be a plain path (no query strings or fragments)
• addMcpServer() — resolves callbackPath, enforces it when sendIdentityOnConnect: false, uses it for URL construction when provided. Also normalizes trailing slashes on callbackHost to prevent double-slash URLs.
• isCallbackRequest() — replaced loose url.includes("/callback") substring check with state-based server ID matching plus origin + pathname verification against the stored callback_url
• Tests — new unit tests for custom callback path detection, pathname-based matching, and origin defense-in-depth in client-manager.test.ts. New integration tests in add-mcp-server.test.ts verifying the callbackPath enforcement (throws when sendIdentityOnConnect: false without callbackPath, does not throw when callbackPath is provided).

Notes for reviewers

• The isCallbackRequest change is the subtlest part. The old /callback substring check is replaced by a two-layer approach: (1) extract serverId from the state param and confirm it exists in storage, (2) verify the request's origin + pathname match the stored callback_url for that server. This is both more precise and more permissive than before — it works with any callback path while preventing false-positive interception.

• The runtime enforcement (throw when sendIdentityOnConnect: false without callbackPath) can't be done at the type level since sendIdentityOnConnect is on static options and callbackPath is on the addMcpServer call — TypeScript can't connect those two. The runtime error is clear and fails fast.

[changeset-bot]

🦋 Changeset detected

Latest commit: 47633ba

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
agents	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/agents@868

commit: 47633ba

[mattzcarey]

LGTM