MCP client refactor - storage adapter

[mattzcarey]

part one in a long saga. This moves all the mcp storage control to the client manager with an interface to try and make it less platform specific.

also cleans up the _connectMcpServersInternal and mcp.connect into..

• mcp.registerServer()
• mcp.connectToServer()

tested with: https://search-mcp.parallel.ai/mcp on https://workers-ai-playground.mattzcarey.workers.dev/

[changeset-bot]

⚠️ No Changeset found

Latest commit: fcc2948

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[claude]

Claude Code Review

Issues Found:

1. Debug console.log left in production code - client-manager.ts:413

   console.log(servers);

   Should be removed or replaced with proper logging.

2. Type safety issue in ensureJsonSchema checks - index.ts:479, 520

   if (typeof this.mcp.ensureJsonSchema === "function") {
     await this.mcp.ensureJsonSchema();
   }

   This typeof check shouldn't be necessary since ensureJsonSchema is always present on MCPClientManager. Remove the conditional or explain why it's needed.

3. Race condition potential in restoreConnectionsFromStorage - client-manager.ts:149-220
   When checking existing connections, only ready state triggers a skip with warning. But failed state falls through and creates a new connection. This could mask persistent failures - consider logging or handling failed states explicitly.

4. Missing connection cleanup in registerServer - client-manager.ts:233
   registerServer returns early if connection exists but doesn't verify the connection is in a good state. A stale/failed connection won't be recreated.

5. Storage adapter null checks are defensive but inconsistent - client-manager.ts:701, 720, 731
   Methods like saveServer, removeServer, listServers check if _storage exists, but storage is required (non-optional) in constructor. These checks suggest uncertainty about the design - either make storage optional everywhere or remove the defensive checks.

Testing:

• Good test coverage for OAuth flow and callback URL management
• Missing tests for race conditions during reconnection
• Missing tests for failed connection state handling in restoreConnectionsFromStorage

Architecture:
The storage adapter abstraction is solid and makes the code more testable. The separation of registerServer/connectToServer is cleaner than the previous monolithic approach.

[pkg-pr-new]

Open in StackBlitz

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

commit: fcc2948

[threepointone]

📚 Documentation Sync

I've created a documentation PR to sync these changes to cloudflare-docs:

Docs PR: cloudflare/cloudflare-docs#26535

Documentation Changes

This PR introduces a storage adapter architecture for the MCP client manager. The documentation includes:

1. New Advanced Configuration Guide (advanced-client-api.mdx)

   • Explains the MCPStorageAdapter interface
   • Provides examples for implementing custom storage backends (KV, R2, external databases)
   • Documents the connection restoration process after hibernation
   • Details performance considerations and caching strategies

2. OAuth Security Section (updated oauth-mcp-client.mdx)

   • Documents the security improvement where callback URLs are cleared after successful OAuth
   • Explains state parameter validation
   • Notes on secure token storage

3. API Reference Updates (updated mcp-client-api.mdx)

   • Added link to advanced configuration guide
   • Noted the modular storage adapter architecture

Why These Docs Matter

This refactoring introduces a breaking change in how MCPClientManager is initialized (now requires a storage adapter in options). While the Agent class handles this transparently for most users, advanced users who might want custom storage backends (e.g., storing MCP configs in KV instead of SQL) now have a documented path forward.

The OAuth security improvements are also worth documenting for user awareness.

---

This is an automated sync from the intelligent documentation workflow.

[threepointone]

📚 Documentation sync

Documentation has been updated in cloudflare-docs to reflect these changes:

Docs PR: cloudflare/cloudflare-docs#26535

Changes documented

• New page: mcp-storage.mdx - Explains the storage adapter architecture and security considerations
• Updated: mcp-client-api.mdx - Added security notes about OAuth credential cleanup
• Updated: oauth-mcp-client.mdx - Added security information about automatic credential cleanup

The documentation covers:

• Storage adapter interface for flexible MCP server configuration persistence
• Automatic OAuth credential cleanup after successful authentication (security improvement)
• Connection restoration behavior after Agent hibernation

---

🤖 Auto-generated comment

[threepointone]

Documentation Updated

The documentation for this PR has been updated in cloudflare-docs#26535.

Documentation changes:

• Added new Storage Adapter page documenting the MCPStorageAdapter interface
• Updated MCP Client API reference to reference storage adapter pattern
• Documented breaking change: MCPClientManager now requires storage option
• Included migration guide for direct MCPClientManager usage
• Documented security improvements in OAuth credential handling

Please review the documentation PR when you have a chance.

[threepointone]

📚 Documentation sync completed

The documentation for this PR has been updated in the cloudflare-docs repository.

Documentation PR: cloudflare/cloudflare-docs#26535

Updated documentation:

• MCP Client API Reference - Updated to reflect storage adapter pattern, automatic connection restoration, and OAuth security improvements
• Storage Adapter Guide - New comprehensive guide on the storage adapter pattern and custom storage backends
• MCP Storage Architecture - New documentation explaining internal storage architecture
• OAuth MCP Client Guide - Updated with OAuth security considerations

Key changes documented:

• Storage adapter pattern for decoupling MCP connection management from storage
• Automatic connection restoration after Agent hibernation
• OAuth security improvements (callback URL clearing to prevent replay attacks)
• Custom storage backend implementation guide
• Connection state management and efficient callback routing

The documentation is ready for review alongside this PR.