Investigate: 400 error on MCP endpoint - empty grantedSkills after SDK upgrade

[dcramer]

Problem

After upgrading @modelcontextprotocol/sdk from 1.22.0 to 1.25.3 (PR #752), Claude Code authentication appeared to fail with a 400 error.

Observed:

• 400 on POST https://mcp.sentry.dev/mcp/sentry/mcp-server?experimental=1 (2026-01-30 15:59:21 PST)

Likely Cause

The 400 response comes from mcp-handler.ts:149-152:

if (validSkills.size === 0) {
  return new Response(
    "Authorization failed: No valid skills were granted. Please re-authorize and select at least one permission.",
    { status: 400 },
  );
}

This suggests the grantedSkills field was either:

1. Empty or not passed correctly after the SDK upgrade
2. Skill parsing failed due to format changes
3. OAuth token didn't include skills due to SDK changes

MCP SDK Changes (1.22.0 → 1.25.3)

Potentially relevant changes:

• v1.25.0: "SPEC COMPLIANCE: Remove loose/passthrough types not allowed/defined by MCP spec"
• v1.24.0: Added invalid_target OAuth error (RFC 8707), client credentials OAuth flow
• v1.23.0: "Support upscoping on insufficient_scope 403", "Adjust scope management to line up with SEP-835"

Investigation Steps

1. Check if scope/skill format changed in MCP SDK 1.25.x
2. Review OAuth token contents before/after upgrade
3. Test authentication flow with SDK 1.25.3 and capture actual error
4. Check if grantedSkills parsing needs to be updated

Context

• PR fix(deps): Address Dependabot security vulnerabilities #752 was reverted in PR Revert "fix(deps): Address Dependabot security vulnerabilities (#752)" #753 due to this and other issues
• No server-side errors were logged from the user's IP, suggesting the issue may be in OAuth flow or client-side
• Related to dependency upgrades for Dependabot security alerts

Files

• packages/mcp-cloudflare/src/server/lib/mcp-handler.ts
• packages/mcp-cloudflare/src/server/oauth/

[dcramer]

Investigation Summary

Investigated this issue and created #758 with diagnostic logging to help capture future occurrences.

Findings

What we confirmed:

• All 628 tests pass with SDK 1.25.3 — no obvious breaking changes
• The 400 error path at mcp-handler.ts:148-152 had no logging, making diagnosis impossible
• Empty grantedSkills array correctly triggers the 400 (verified via new test)

What we couldn't determine:

• The actual value of grantedSkills when the error occurred (empty array? malformed data? type issue?)
• Whether this was a new authorization or a refreshed token
• Reproducibility — single incident with no server-side logs

Potential root causes identified:

1. Version mismatch — agents@0.2.23 was designed for SDK 1.22.0, but pnpm hoists SDK 1.25.x when upgrading the catalog
2. Token state — Existing token may have had skills stored in a format that didn't survive the upgrade
3. Refresh flow — Token refresh might not have preserved grantedSkills correctly

Next Steps

1. Merge fix(cloudflare): Add diagnostic logging for empty grantedSkills errors #758 — Adds diagnostic logging to capture grantedSkills value, type, and array status on future 400 errors

2. Before retrying SDK upgrade, consider:

   • Upgrade agents package to 0.3.6 (designed for SDK 1.25.2) to eliminate version mismatch
   • Test in staging with real OAuth flows (new auth, refresh, re-auth)
   • Monitor logs after deployment for any occurrences

3. If issue recurs, the new logging will show exactly what grantedSkills contained, enabling proper diagnosis

[dcramer]

Update: SDK Upgrade PR Created

Created PR #759 to retry the SDK upgrade (1.21.0 → 1.25.3) with:

• Diagnostic logging now in place from fix(cloudflare): Add diagnostic logging for empty grantedSkills errors #758 to capture any runtime issues
• All 628 tests pass locally
• agents package stays at 0.2.23 to avoid requiring AI SDK v6

If this upgrade triggers the same 400 error, we'll now have detailed logging to identify the root cause.

[dcramer]

Root Cause Found 🎯

The 400 error is not related to grantedSkills - it's a protocol version mismatch:

Bad Request: Unsupported MCP-Protocol-Version: 2025-11-25. 
Supported versions: 2025-03-26, 2025-06-18

What's happening

1. Claude Code (client) is now using MCP protocol version 2025-11-25
2. Our server's createMcpHandler from agents@0.2.23 only advertises support for 2025-03-26 and 2025-06-18
3. The server rejects the connection with a 400 before any OAuth/skills logic runs

Why this wasn't obvious before

• The original issue reported grantedSkills being empty, which was a red herring
• The diagnostic logging we added doesn't fire because the 400 happens at the protocol negotiation layer, before our handler code runs

Fix Required

Upgrade the agents package from Cloudflare, which controls the MCP handler. However, this has cascading dependencies:

• agents@0.2.35 requires ai>=5.0.0 (we have ai@^4.3.16)
• agents@0.3.x requires ai>=6.0.0

This is now a blocking issue - Claude Code users cannot connect until we upgrade.

Next Steps

1. Revert PR chore: Upgrade @modelcontextprotocol/sdk to ^1.25.3 #759 was already merged, but it's not the cause - need to upgrade agents package
2. Upgrade path: ai@4.x → ai@5.x or ai@6.x + corresponding agents version
3. Test thoroughly since the AI SDK changes may affect our agent mode functionality

[dcramer]

Upgrade Analysis Complete

Root Cause

Claude Code uses MCP protocol version 2025-11-25, but our server (via agents@0.2.23) only supports 2025-03-26 and 2025-06-18.

Required Upgrades

To support protocol 2025-11-25, we need:

Package	Current	Required	Notes
agents	0.2.23	0.3.5+	First version with MCP SDK 1.25.2
ai	4.3.16	6.x	Required by agents 0.3.x
@ai-sdk/anthropic	1.2.12	3.x	Required by ai 6.x
@ai-sdk/openai	1.3.22	3.x	Required by ai 6.x
@ai-sdk/react	1.2.12	3.x	Required by ai 6.x
@modelcontextprotocol/sdk	1.21.0	1.25.3	Already merged in #759

AI SDK 6 Breaking Changes Requiring Code Updates

1. experimental_createMCPClient moved to @ai-sdk/mcp package
2. LanguageModelV1 type renamed to LanguageModel
3. maxSteps replaced with stopWhen: stepCountIs(n)
4. tool() function API changed
5. Multiple test file updates needed

Estimated Scope

• ~15 files need modification
• Significant testing required for agent functionality

Recommendation

This is a non-trivial upgrade. I recommend:

1. Create a dedicated branch for the full AI SDK 6 migration
2. Thoroughly test agent mode functionality after upgrade
3. Consider phased rollout if possible

@dcramer Let me know if you want me to proceed with the full migration or if you'd like to explore other options (e.g., temporary workaround, coordinating with Cloudflare on agents package).