Skip to content

refactor(mcp): split MCPClientManager and serialize connection work per server - #2661

Closed
mattzcarey wants to merge 5 commits into
fix/2658-mcp-midsession-reauthfrom
refactor/mcp-client-manager-machine
Closed

mattzcarey wants to merge 5 commits into
fix/2658-mcp-midsession-reauthfrom
refactor/mcp-client-manager-machine

Conversation

@mattzcarey

@mattzcarey mattzcarey commented Oct 22, 2026 •

Copy link
Copy Markdown
Member

MCPClientManager now runs all connection work for a server through a per-server queue, so connect, discovery, OAuth callback completion and restore never overlap on one connection. Removing a server cancels its queued work, and work that is already running can't write back once the server is gone. RPC servers restore in the background after onStart, the same way HTTP servers do.

Stacked on #2660, and part of the same work on #2658. The manager was one 2,600-line file that kept background work as loose promises in a map, and that allowed these races:

  • two conn.init() calls for one server ran at once and closed each other's client
  • a connect or token exchange that finished after removeServer() wrote auth_url or a session onto a server re-registered under the same id
  • onStart awaited RPC restore, whose timeout is 60s, inside a 30s startup budget, so a hung McpAgent could reset the host object again and again

Things callers will notice:

  • restored RPC tools are not ready the moment startup ends, so call waitForConnections() first. AIChatAgent waits by default; Think waits when waitForMcpConnections is set.
  • a connectToServer(), discoverIfConnected() or establishConnection() still queued when its server is removed rejects with ServerLaneCancelledError, and a queued OAuth callback returns authSuccess: false
  • waitForConnections() also waits for user-started connects and discoveries

The SQL, OAuth callback handling, AI tool conversion and URL policy moved out into server-store.ts, oauth-callback.ts, ai-tools.ts and url-policy.ts. The queue lives in server-lanes.ts.

pnpm run check, the agents workers suite and the client and server conformance lanes pass. New tests cover the queue, cancelling queued work on removal, the removal and re-registration races, and RPC restore not blocking startup.

@changeset-bot

changeset-bot Bot commented Oct 22, 2026 •

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 0406eaf

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

@agent-think

agent-think Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

✅ agents import sizes: no significant changes (978d6f95 → 0406eaf1, workflow run)

devin-ai-integration[bot]

This comment was marked as resolved.

@pkg-pr-new

pkg-pr-new Bot commented Oct 22, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@2661

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@2661

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@2661

hono-agents

npm i https://pkg.pr.new/hono-agents@2661

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@2661

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@2661

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@2661

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@2661

commit: 0406eaf

devin-ai-integration[bot]

This comment was marked as resolved.

@mattzcarey
mattzcarey force-pushed the refactor/mcp-client-manager-machine branch 2 times, most recently from 67c61e4 to 3974b04 Compare October 27, 2026 12:05
@mattzcarey
mattzcarey force-pushed the refactor/mcp-client-manager-machine branch from 3974b04 to a0157df Compare October 27, 2026 13:04
@mattzcarey
mattzcarey force-pushed the refactor/mcp-client-manager-machine branch from a0157df to e18bafd Compare October 27, 2026 13:49
@mattzcarey
mattzcarey added this pull request to stack #2750 October 27, 2026 18:20
@mattzcarey
mattzcarey force-pushed the refactor/mcp-client-manager-machine branch 4 times, most recently from e4d8bb6 to 28c1144 Compare October 29, 2026 18:58

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 1 new potential issue.

⚠️ 1 issue in files not directly in the diff

⚠️ MCP client changes lose release entry

With the agents changeset removed, the MCP client fixes and changed connection behavior have no release entry. Changesets cannot include this PR in an agents version bump.

Devin Review

- ServerLanes queues connect, discovery, establish, OAuth callback and
  restore work per server; nested calls run inline, listeners run outside
- OAuth callback parsing, state checks, code exchange and response
  rendering move to oauth-callback.ts
- settleServer()/connectAndDiscover() replace Agent-side orchestration in
  addMcpServer
- work that outlives removeServer no longer writes back; a code exchange
  that finishes after removal clears its tokens
- RPC servers restore in the background instead of holding onStart
- forget() bumps a per-server generation so work still queued behind a
  removed server rejects with ServerLaneCancelledError instead of running
- callback failure and stale-success paths check they still own the
  connection before touching state, so a re-registered server keeps its link
A callback queued behind work for a server that is then removed returns a
failed callback result instead of rejecting, and settleServer /
connectAndDiscover report the server as removed.
@mattzcarey

Copy link
Copy Markdown
Member Author

Replaced by #2782 (MCP client changes) and #2783 (examples).

@mattzcarey mattzcarey closed this Oct 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant