Make McpAgent extend Agent + Streaming HTTP protocol features by deathbyknowledge · Pull Request #415 · cloudflare/agents

deathbyknowledge · 2025-08-18T22:08:32Z

Lib changes:

McpAgent now extends the base Agent class extend McpAgent from Agent #235
Refactor to only use Agent and Partykit Server primitives. Depends on Allow routing ctx props to Server partykit#268
Clients can now GET the MCP endpoint to establish a standalone SSE stream for server initiated messages
Clients can now DELETE the MCP endpoint to terminate a session Support MCP DELETE requests #416
Tool notifications are now also handled in the Streamable HTTP transport

Tests:

New tests to check the updated Streamable HTTP bits
Added E2E tests that deploy (using alchemy) complete MCP servers and test expected behavior with @modelcontextprotocol/sdk. They include authless and OAuth MCP examples.

Streamable HTTP changes adapted from the TS SDK

Run the E2E from /packages/agents with

npm run test:e2e

changeset-bot · 2025-08-18T22:08:36Z

🦋 Changeset detected

Latest commit: 4e1794f

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

This PR includes changesets to release 2 packages

Name	Type
agents	Patch
hono-agents	Patch

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

deathbyknowledge · 2025-08-18T22:10:11Z

   * @returns An error response object with status code and message
   */
-  onError(error: Error): { status: number; message: string } {
+  onMcpError(error: Error): { status: number; message: string } {


This seems to be a breaking change. The old McpAgent had a custom onError method that clashes with the base Agent method with the same name once we extend it.

pkg-pr-new · 2025-08-19T09:33:34Z

Open in StackBlitz

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

commit: 4e1794f

whoiskatrin · 2025-08-27T16:52:46Z

this is some really good stuff! @deathbyknowledge great work

threepointone

tentative approval pending nits and notes

threepointone · 2025-09-01T11:52:22Z

-  onmessage?: (message: JSONRPCMessage) => void;
-  sessionId?: string;
+  async setInitialized() {
+    await this.ctx.storage.put("initialized", true);


Suggested change

await this.ctx.storage.put("initialized", true);

// todo: move to sync api once https://github.com/cloudflare/workerd/pull/4895 lands

await this.ctx.storage.put("initialized", true);

…equest

kentcdodds · 2025-09-09T16:38:23Z

How confident are we that this is going to be merged? Can I safely prepare teaching material based on this PR?

deathbyknowledge · 2025-09-09T16:44:58Z

How confident are we that this is going to be merged? Can I safely prepare teaching material based on this PR?

We're waiting to release the AI SDK v5 changes to merge this. Should land this week

kentcdodds · 2025-09-09T17:19:24Z

That is helpful context. Do you have an idea/recommendation for getting:

Authentication information into tool handlers
request.url information into tool handlers

I know that the extra arg is a TypeScript MCP SDK-specific thing, but this implementation uses the TypeScript MCP SDK so it seems reasonable to expect to be able to use that. But at this point I don't care all that much, I just would like there to be some recommended way to accomplish this. Everything I've tried I've been told that it's not the right way to do it 🙃

deathbyknowledge · 2025-09-09T17:22:31Z

That is helpful context. Do you have an idea/recommendation for getting:

The comment I left here #426 (comment) should cover all of those

kentcdodds · 2025-09-09T17:23:49Z

Just saw your message on my PR: #426 (comment)

Thanks for that!

So I take it from your message that it is fine/encouraged/recommended for me to modify ctx.props?

deathbyknowledge · 2025-09-09T17:30:12Z

It is fine in the context of McpAgent as it's the only to customize the props as of now, as long as it happens in the handlers mentioned in the comment. We'll be improving the ergonomics regardless, to avoid going through so many hoops and possible footguns. I'll make sure to add some docs to cover this in detail.

kentcdodds · 2025-09-09T17:32:13Z

Sounds good. Thank you for your help!

kentcdodds · 2025-09-09T17:33:56Z

Oh, one question to be clear. How does McpAgent plan to support the things the extra argument offers:

Autocomplete dropdown in a code editor showing available properties: _meta?, authInfo?, requestId, requestInfo?, sendNotification, sendRequest, sessionId?, and signal.

deathbyknowledge · 2025-09-09T18:00:21Z

That still needs to be thought out, it might not be directly though an extra argument but not sure yet

kentcdodds · 2025-09-10T15:40:05Z

That's fine. Just my 2¢, I think it would be good for the ecosystem if Cloudflare's implementation either supported the full TypeScript SDK (preferred) or built its own. Supporting part of the SDK will lead to confusion for folks I think.

remorses · 2025-09-11T17:33:41Z

LFG

deathbyknowledge commented Aug 18, 2025

View reviewed changes

deathbyknowledge marked this pull request as ready for review August 19, 2025 07:40

threepointone reviewed Aug 19, 2025

View reviewed changes

Comment thread packages/agents/src/mcp/index.ts Outdated

Comment thread packages/agents/src/mcp/index.ts Outdated

whoiskatrin mentioned this pull request Aug 22, 2025

add GET request support for MCP endpoints #408

Closed

deathbyknowledge mentioned this pull request Aug 24, 2025

Allow routing ctx props to Server cloudflare/partykit#268

Merged

deathbyknowledge mentioned this pull request Aug 30, 2025

MCP: Support authInfo from Transport #426

Closed

threepointone approved these changes Sep 1, 2025

View reviewed changes

threepointone reviewed Sep 1, 2025

View reviewed changes

Comment thread packages/agents/src/e2e/remote-mcp-authless/index.ts

Comment thread packages/agents/src/e2e/remote-mcp-server/index.ts

Comment thread packages/agents/src/e2e/remote-mcp-server/index.ts

deathbyknowledge and others added 19 commits September 3, 2025 15:45

make McpAgent extend Agent

c3f432c

route with getAgentByName

cea87c6

implement MCP server req/notifications + tool notifications

6f656bf

add tests for standalone sse with streaming http

f3a3dae

rename standalone method to better match

de5fa4b

fix format

856a874

usse base Agent onError

affcfd4

remove DO overrides

74258ad

restore connectionId of standalone sse on hibernation

ee9478b

Create perfect-feet-breathe.md

0e0f72f

fix for hibernate: false

26d7596

refactor to only use Server and Agent primitives + DELETE support

a90ccc1

add e2e tests for authless and oauth MCPs

361c6ac

tidy

f95875e

use new partykit server props

f4996e7

close writer immediately

11e926c

add multiple MCPs in e2e

6201caf

include custom props examples + don't assume props can't change per r…

7c9c156

…equest

better comments and amends

6e6d5fc

Update .changeset/perfect-feet-breathe.md

969371c

deathbyknowledge force-pushed the mcp-agent-extend-base-agent branch from c26e919 to 969371c Compare September 3, 2025 13:51

deathbyknowledge added 2 commits September 3, 2025 22:09

add docs

dac9aa4

fix typos

4e1794f

AbhiPrasad mentioned this pull request Sep 11, 2025

Add tests to ensure that cloudflare MCPAgent changes work with durable objects instrumentation getsentry/sentry-javascript#17598

Closed

threepointone approved these changes Sep 11, 2025

View reviewed changes

deathbyknowledge merged commit f7bd395 into cloudflare:main Sep 11, 2025
3 checks passed

threepointone mentioned this pull request Sep 11, 2025

Version Packages #455

Merged

	await this.ctx.storage.put("initialized", true);
	// todo: move to sync api once https://github.com/cloudflare/workerd/pull/4895 lands
	await this.ctx.storage.put("initialized", true);

Conversation

deathbyknowledge commented Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

🦋 Changeset detected

Uh oh!

deathbyknowledge Aug 18, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

whoiskatrin commented Aug 27, 2025

Uh oh!

threepointone left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

threepointone Sep 1, 2025

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!

kentcdodds commented Sep 9, 2025

Uh oh!

deathbyknowledge commented Sep 9, 2025

Uh oh!

kentcdodds commented Sep 9, 2025

Uh oh!

deathbyknowledge commented Sep 9, 2025

Uh oh!

kentcdodds commented Sep 9, 2025

Uh oh!

deathbyknowledge commented Sep 9, 2025

Uh oh!

kentcdodds commented Sep 9, 2025

Uh oh!

kentcdodds commented Sep 9, 2025

Uh oh!

deathbyknowledge commented Sep 9, 2025

Uh oh!

kentcdodds commented Sep 10, 2025

Uh oh!

Uh oh!

remorses commented Sep 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

deathbyknowledge commented Aug 18, 2025 •

edited

Loading

changeset-bot Bot commented Aug 18, 2025 •

edited

Loading

pkg-pr-new Bot commented Aug 19, 2025 •

edited

Loading