MCP client refactor - storage adapter #652

mattzcarey · 2025-11-14T16:28:41Z

part one in a long saga. This moves all the mcp storage functions 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/

Other fun stuff here:

reasoning card for playground
updating to qwen 3 as default

changeset-bot · 2025-11-14T16:28:44Z

🦋 Changeset detected

Latest commit: 0966d6c

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

This PR includes changesets to release 2 packages

Name	Type
agents	Minor
hono-agents	Major

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

claude · 2025-11-14T16:30:03Z

Claude Code Review

Architecture Issues

Critical: Race condition in OAuth flow (index.ts:482-487)
The OAuth callback handling fires onServerStateChanged which triggers a broadcast, then establishConnection is called in the background which fires another onServerStateChanged. However, establishConnection can fail after the broadcast, leaving the UI showing stale state. The background connection should complete before broadcasting, or the error state should trigger another broadcast.

Storage timing issue (client.ts:600-602)
clearAuthUrl is called immediately after completeAuthorization, but if establishConnection fails later, the auth_url is already cleared. This breaks reconnection attempts since the system thinks OAuth is complete when it isn't. Consider clearing auth_url only after establishConnection succeeds.

Code Quality

Missing error handling in restoreConnectionsFromStorage (client.ts:223)
Connection restoration catches errors but continues silently. Failed restorations should be tracked so the UI can show which servers need attention.

Inconsistent state machine (client.ts:160-196)
The logic skips servers in various states but doesn't document why. A server in "authenticating" state during restore likely indicates an incomplete OAuth flow that should be cleaned up or retried.

Type safety gap (client-storage.ts:79-85)
AgentMCPClientStorage constructor takes sql with a signature that returns T[], but the SQL operations don't validate that the template strings are actually SQL. Consider a more type-safe SQL builder or at least document the expected usage pattern.

Testing Coverage

The test file (client-manager.test.ts) has grown significantly (+1757 lines) but I cannot verify test quality without seeing the full file. Ensure tests cover:

The OAuth race condition scenarios
Failed connection restoration
Concurrent registerServer/connectToServer calls
Storage adapter error cases

Minor Issues

client.ts:166-167: Log message could be more actionable - suggest what user should do
index.ts:1322: mcp.dispose() called but no check if already disposed
client-storage.ts:22,26: Return types use Promise<T | undefined> | undefined - this dual async/sync pattern is confusing, pick one

pkg-pr-new · 2025-11-14T16:30:28Z

Open in StackBlitz

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

commit: 0966d6c

This PR introduces a storage adapter architecture for the MCP client manager, allowing custom storage backends for MCP server configurations. Changes: - Created advanced-client-api.mdx documenting the MCPStorageAdapter interface - Added security section to oauth-mcp-client.mdx about callback URL clearing - Updated mcp-client-api.mdx to link to advanced configuration guide These docs explain the new storage adapter pattern, OAuth security improvements, and provide examples for implementing custom storage backends. Related: cloudflare/agents#652

Documents the MCP client manager refactoring that introduces a storage adapter interface and implements automatic OAuth credential cleanup for enhanced security. Changes: - Add new mcp-storage.mdx explaining storage adapter architecture - Document automatic OAuth credential cleanup after authentication - Add security notes about replay attack prevention - Document automatic connection restoration after hibernation - Update OAuth guide with security information Related PR: cloudflare/agents#652 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

threepointone · 2025-11-14T16:39:37Z

📚 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:

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
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
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 · 2025-11-14T16:40:02Z

📚 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

- Add new storage-adapter.mdx page documenting the MCPStorageAdapter interface - Update mcp-client-api.mdx to reference storage adapter pattern - Document breaking change: MCPClientManager now requires storage option - Include migration guide for direct MCPClientManager usage - Document security improvements in OAuth credential handling Related to cloudflare/agents#652

threepointone · 2025-11-14T16:43:31Z

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 · 2025-11-14T18:53:51Z

📚 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.

deathbyknowledge

🔥

packages/agents/src/index.ts

threepointone

paired and reviewd, ping when done and let's land this

examples/x402-mcp/src/index.ts

packages/agents/src/mcp/client.ts

packages/agents/src/mcp/client-storage.ts

packages/agents/src/index.ts

packages/agents/package.json

…ger class.

threepointone

stampung pending a descriptive changeset

@mattzcarey

* move storage to the client manager * fix: url missing after page load * fix: dots * fix: callback handling is now in client manager with 2 stage storage. * some auth edge cases * make storage sync for the moment to reduce complexity * better default states * cancel button on frontend * remove openai from agents package.json * unify mcp storage * fix lock file * fix: tests * feat: more refactor * tools tests * update x402 * fix: types * update default model in playground * reasoning card * Apply suggestion from @mattzcarey * fix: from review * add smooth scrolling * fix: calling restore onstart and json schema the rest of the time * fix: oauth tests * remove smooth scroll :( * make tests smaller * rename to client for review * revert changes to mcp.connect() * make storage async * fix readonly nit * revert remove openai ai sdk provider * remove public storage api * add todos for ensureJsonSchema * fix: mcp server states and unify observability to the mcp client manager class. * remove callback cache * dead * createConnection. in memory method * add tests * changeset * formatting * claude comments * remove redundant checks

mattzcarey added 5 commits November 14, 2025 11:25

move storage to the client manager

d69fafb

fix: url missing after page load

5ae0fc1

fix: dots

06d8204

fix: callback handling is now in client manager with 2 stage storage.

3d297e3

some auth edge cases

a2a5337

threepointone mentioned this pull request Nov 14, 2025

MCP client refactor - storage adapter cloudflare/cloudflare-docs#26535

Closed

mattzcarey added 8 commits November 14, 2025 17:19

make storage sync for the moment to reduce complexity

3e64892

better default states

9215674

cancel button on frontend

050ea26

remove openai from agents package.json

6a8de3f

unify mcp storage

1c5d5a9

fix lock file

3078663

fix: tests

c6cfcfc

feat: more refactor

6f13b13

mattzcarey marked this pull request as draft November 14, 2025 18:48

mattzcarey added 4 commits November 14, 2025 22:50

tools tests

3cecc93

update x402

fcf7aa9

fix: types

8268b7e

update default model in playground

dc1237c

mattzcarey marked this pull request as ready for review November 14, 2025 23:29

deathbyknowledge approved these changes Nov 17, 2025

View reviewed changes

packages/agents/src/index.ts Outdated Show resolved Hide resolved

packages/agents/src/index.ts Outdated Show resolved Hide resolved

mattzcarey added 7 commits November 17, 2025 20:04

fix: from review

1e936c7

add smooth scrolling

d909624

fix: calling restore onstart and json schema the rest of the time

3e616d4

fix: oauth tests

5161b0d

remove smooth scroll :(

0fc2de9

make tests smaller

d5b672e

rename to client for review

1c138ec

threepointone reviewed Nov 18, 2025

View reviewed changes

mattzcarey added 11 commits November 18, 2025 14:54

revert changes to mcp.connect()

d3f5182

make storage async

021c167

fix readonly nit

704d07c

revert remove openai ai sdk provider

0a7acad

remove public storage api

64c4a7d

add todos for ensureJsonSchema

e09b3cb

fix: mcp server states and unify observability to the mcp client mana…

cf448d8

…ger class.

remove callback cache

9eac678

dead

d8a1d4f

createConnection. in memory method

f482b0c

add tests

5ef1e8b

threepointone approved these changes Nov 18, 2025

View reviewed changes

mattzcarey and others added 5 commits November 18, 2025 18:31

changeset

51fca96

Merge branch 'main' into feat/mcp-storage-adapter

67033d8

formatting

7ad9317

claude comments

d1f479f

remove redundant checks

0966d6c

threepointone merged commit c07b2c0 into main Nov 18, 2025
4 of 5 checks passed

threepointone deleted the feat/mcp-storage-adapter branch November 18, 2025 19:25

threepointone mentioned this pull request Nov 18, 2025

Version Packages #657

Merged

MCP client refactor - storage adapter #652

MCP client refactor - storage adapter #652

Conversation

mattzcarey commented Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

claude bot commented Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Claude Code Review

Architecture Issues

Code Quality

Testing Coverage

Minor Issues

Uh oh!

pkg-pr-new bot commented Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

threepointone commented Nov 14, 2025

📚 Documentation Sync

Documentation Changes

Why These Docs Matter

Uh oh!

threepointone commented Nov 14, 2025

📚 Documentation sync

Changes documented

Uh oh!

threepointone commented Nov 14, 2025

Documentation Updated

Uh oh!

threepointone commented Nov 14, 2025

📚 Documentation sync completed

Uh oh!

deathbyknowledge left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

threepointone left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

threepointone left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mattzcarey commented Nov 14, 2025 •

edited

Loading

changeset-bot bot commented Nov 14, 2025 •

edited

Loading

claude bot commented Nov 14, 2025 •

edited

Loading

pkg-pr-new bot commented Nov 14, 2025 •

edited

Loading