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

⚠️ No Changeset found

Latest commit: d5b672e

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 · 2025-11-14T16:30:03Z

Claude Code Review

Critical Issues

1. Missing await in removeMcpServer (packages/agents/src/index.ts:1465-1468)

async removeMcpServer(id: string) {
  this.mcp.closeConnection(id);  // Missing await
  this.mcp.removeServer(id);
  this.broadcastMcpServers();
}

closeConnection() is async but not awaited. This creates a race condition where the server record could be deleted from storage before the connection is fully closed, potentially leaving orphaned resources.

Fix: await this.mcp.closeConnection(id);

Architecture Issues

2. Storage adapter passed to OAuth provider is too broad (client-manager.ts:134-138)
The entire storage adapter (with SQL and KV access) is passed to DurableObjectOAuthClientProvider. OAuth providers should only need KV access for tokens, not full storage control.

Consider creating a narrower interface for OAuth providers that only exposes KV operations.

3. Connection state race condition in restore (client-manager.ts:164-187)
The code checks existingConn state and decides whether to skip/continue, but between the check and the registerServer call, another async operation could change the state. The restoration logic would be clearer with explicit state machine transitions.

Testing Gaps

4. No integration tests for OAuth flow
The test file (client-manager.test.ts) mocks the OAuth flow but doesn't actually test the full sequence: register → connect → callback → establish connection. This leaves OAuth edge cases (duplicate callbacks, state mismatches, concurrent OAuth attempts) untested.

5. Cache invalidation not tested
The callback URL cache mechanism (_callbackUrlCache, _invalidateCallbackUrlCache) is implemented but has no test coverage verifying the cache is properly invalidated when servers are added/removed.

Minor Issues

6. Inconsistent connection disposal (client-manager.ts:687-688)
closeConnection deletes the connection before disposing event subscriptions, while closeAllConnections disposes after deletion. Should follow consistent ordering.

7. Silent connection recreation (client-manager.ts:239-242)
registerServer silently skips if connection exists. This hides potential bugs where callers expect registration to succeed but the old connection is reused with potentially stale config.

Summary: Address the missing await (#1) before merging. Consider #2 for security boundaries. Others are improvements for future PRs.

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

Open in StackBlitz

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

commit: d5b672e

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.

packages/agents/src/index.ts

deathbyknowledge

🔥

deathbyknowledge · 2025-11-17T16:04:33Z

packages/agents/src/index.ts

-    this._ParentClass.name,
-    "0.0.1"
-  );
+  readonly mcp!: MCPClientManager;


Nit: ! is not needed if you set it in the constructor

deathbyknowledge · 2025-11-17T16:22:23Z

packages/agents/src/index.ts

+            await this.mcp.ensureJsonSchema();
+          }
+
+          await this._initializeMcpConnectionsFromStorage();


Does it make sense to move this._mcpConnectionsInitialized and this._initializeMcpConnectionsFromStorage inside the ClientManager constructor?

Ideally in the Agent constructor we'd just do this.mcp = new MCPClientManager(this._ParentClass.name, "0.0.1", ...) and forget about it right?

Maybe the call to ensureJsonSchema() too?

this is super annoying. We need the name to make the called to the d-o-OauthClient. We dont have that in the constructor where this is defined :(

I can clean this up a bit tho

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

Open

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

mattzcarey and others added 2 commits November 14, 2025 23:29

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

fcc2948

reasoning card

55d2452

mattzcarey commented Nov 17, 2025

View reviewed changes

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

Apply suggestion from @mattzcarey

2e37160

deathbyknowledge approved these changes Nov 17, 2025

View reviewed changes

mattzcarey added 6 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

MCP client refactor - storage adapter #652

Are you sure you want to change the base?

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!

⚠️ No Changeset found

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

Critical Issues

Architecture Issues

Testing Gaps

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!

Uh oh!

deathbyknowledge left a comment

Choose a reason for hiding this comment

Uh oh!

deathbyknowledge Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

deathbyknowledge Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

deathbyknowledge Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

mattzcarey Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

mattzcarey Nov 17, 2025

Choose a reason for hiding this comment

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