feat(mcp): upgrade to MCP SDK v2

[bobbyjohnstx]

Summary

Upgrade @modelcontextprotocol/sdk from 1.27.1 to v2 (@modelcontextprotocol/client package).

Why

The v2 SDK brings:

• Auto version negotiation (versionNegotiation: { mode: "auto" })
• Improved error types (RegistrationRejectedError, SdkHttpError)
• listChanged callback pattern
• listMaxPages option for paginated resource listing
• Better session recovery for expired connections

Implementation

1. Add @modelcontextprotocol/client dependency
2. Update imports in src/mcp/index.ts from subpath imports (@modelcontextprotocol/sdk/client/index.js) to the new top-level package
3. Add versionNegotiation: { mode: "auto" } and listMaxPages: 1_000 to client options
4. Ensure backward compatibility with MCP servers on older protocol versions
5. Update error handling to use new error types where applicable
6. Test with both stdio and SSE/StreamableHTTP transports

Files

• src/mcp/index.ts — main client, imports, transport setup
• src/mcp/auth.ts — if auth flow changes
• package.json — dependency update

Notes

• The existing @modelcontextprotocol/sdk@1.27.1 reconnect loop patch (if applied) should be evaluated for removal — v2 may fix it upstream.
• Test with at least one real MCP server (e.g., filesystem) to verify compatibility.

[bobbyjohnstx]

Risk Assessment — Defer 2-4 Weeks

Independent architect + critic review completed 2026-08-07. Both recommend deferring this upgrade until a stable v2 release is available.

Key Findings

opencode reverted v2 within 16 minutes (commit 89ca9bb → revert 3e12a60). Their attempt used @modelcontextprotocol/client@2.0.0-beta.5 — a pre-release version. No stable v2 exists yet.

Risk Inventory

Risk	Severity	Detail
No stable release	Critical	Only beta.5 available. Shipping a pre-release SDK in production is unacceptable.
Session recovery bugs	High	opencode's revert was likely caused by session recovery regressions. v2's SessionRecovery class replaces manual reconnect logic.
OAuth iss field propagation	High	v2 adds an iss (issuer) parameter to finishAuth() and stored tokens. Tinycode's OAuth callback server and auth storage must handle this correctly or remote MCP auth breaks.
Type renames (structural, not just naming)	Medium	OAuthTokensSchema → OAuthTokenResponseSchema, OAuthMetadataSchema → AuthorizationServerMetadataSchema — these carry structural changes, not just renames.
Test mock paths	Medium	5 test files use mock.module() with SDK subpath imports (@modelcontextprotocol/sdk/client/index.js). All paths change in v2.
Reconnect loop patch	Low	Must verify if v2 natively fixes the receivedResponse flag bug before removing our SDK patch.

Missing from Original Issue

1. src/mcp/auth.ts not listed — OAuth type renames (OAuthTokensSchema, OAuthMetadataSchema) break this file
2. 5 test files with mock.module() paths — not mentioned, all break on import path changes
3. iss field chain — flows from finishAuth() → token storage → callback handler; no mention of verifying this
4. Session recovery behavioral change — v2's SessionRecovery class replaces manual reconnect, not a drop-in

Recommendation

• Wait for stable v2 release (npm view @modelcontextprotocol/client versions — check periodically)
• When ready: budget 2-3 days, not a quick dependency bump
• Pre-upgrade: write integration tests for stdio + SSE + OAuth transports to catch regressions
• Post-upgrade: verify the reconnect loop patch can be removed (check if receivedResponse flag bug is fixed upstream)