feat: rename server property to mcp in MCP-related classes for improved developer experience #427

kentcdodds · 2025-08-28T17:18:35Z

Technically there are some breaking changes here, but they're either done in a non-breaking way or they're breaking features I do not think are used (and are not documented).

Closes #425

BREAKING: Renamed server property to mcp in McpAgent and updated related examples.
BREAKING: Renamed mcp property to mcpClientManager in Agent class to avoid naming conflicts.
Added backward compatibility for server property in McpAgent with a deprecation warning.
Updated all MCP examples to reflect the new naming convention.
Improved property naming consistency across the MCP implementation.

…ed developer experience - **BREAKING**: Renamed `server` property to `mcp` in `McpAgent` and updated related examples. - **BREAKING**: Renamed `mcp` property to `mcpClientManager` in `Agent` class to avoid naming conflicts. - Added backward compatibility for `server` property in `McpAgent` with a deprecation warning. - Updated all MCP examples to reflect the new naming convention. - Improved property naming consistency across the MCP implementation.

changeset-bot · 2025-08-28T17:18:38Z

🦋 Changeset detected

Latest commit: c8994e2

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

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

kentcdodds · 2025-08-28T17:19:47Z

packages/agents/src/index.ts

-  mcp: MCPClientManager = new MCPClientManager(this._ParentClass.name, "0.0.1");
+  mcpClientManager: MCPClientManager = new MCPClientManager(
+    this._ParentClass.name,
+    "0.0.1"
+  );


In retrospect, I do not think this change is necessary and I'm happy to back it out. This is the most breaking thing about this PR. Though again I don't think anyone is intended to use this property (it's also undocumented).

kentcdodds · 2025-08-28T17:20:32Z

packages/agents/src/mcp/index.ts

+  get mcpClientManager() {
+    return this._agent.mcpClientManager;
+  }


This bit is technically breaking for anyone who's using the client manager, but I don't think anyone is and it's not documented.

Very happy with this change. I think this is super confusing at the moment.

We should keep the mcp() and mark it as deprecated to be removed in the next version.

kentcdodds · 2025-08-28T17:20:50Z

packages/agents/src/mcp/index.ts

+   * @deprecated Use the `mcp` property instead for better developer experience.
+   */
+  server?: MaybePromise<McpServer | Server>;
+  /**
+   * This is only set as optional for backward compatibility in case you're
+   * using the legacy `server` property. It's recommended to use `mcp`.
+   *
+   * In the future, we'll make this a required abstract property to implement
+   * and remove the `server` property.
   */
-  abstract server: MaybePromise<McpServer | Server>;
+  mcp?: MaybePromise<McpServer | Server>;


This is the primary focus of this PR

Would you be open to this changing to mcpServer() ?

cliffhall · 2025-08-28T20:06:45Z

examples/mcp/src/server.ts


 export class MyMCP extends McpAgent<Env, State, {}> {
-  server = new McpServer({
+  mcp = new McpServer({


Maybe mcp could be a getter that returns server? That way it would be totally backward compatible.

I don't think that would allow me to do this:

export class MyMCP extends McpAgent { mcp = new McpServer({}); // <-- this is the desired API async init() { this.mcp.server.setRequestHandler( SetLevelRequestSchema, async (request, extra) => { // ... handler logic }, ); } }

Something like this?

export class MyMCP extends McpAgent { get mcp(): McpServer { return this.server; } server = new McpServer({}); async init() { this.mcp.server.setRequestHandler( SetLevelRequestSchema, async (request, extra) => { // ... handler logic }, ); } }

I could do that myself without having to change anything in agents. That's actually a reasonable workaround if they decide this is more trouble than it's worth. Thanks for the idea!

Oh, actually I can't do that because mcp is already set to the mcpClientManager 🙁

pkg-pr-new · 2025-08-29T16:14:13Z

Open in StackBlitz

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

commit: c8994e2

kentcdodds · 2025-08-29T19:17:06Z

.changeset/mcp-property-rename.md

@@ -0,0 +1,31 @@
+---
+"@cloudflare/agents": major


Changed to major because there was an example of using the previous existing mcp property so people may actually be using that.

kentcdodds · 2025-08-29T19:17:19Z

examples/mcp-elicitation-demo/src/server.ts

      };

-      const result = await this.mcp.callTool({
+      const result = await this.mcpClientManager.callTool({


Here's the breaking change.

whoiskatrin · 2025-09-12T11:38:29Z

FYI I'm not against this, I think the change makes life better. My concern it's a breaking change, if we do so, I'd like to make a bigger release and then also prepare people for this migration.

kentcdodds · 2025-09-12T12:54:59Z

I'm fine waiting 👍

mattzcarey · 2025-10-09T15:23:50Z

packages/agents/src/mcp/index.ts

+  get mcpServer(): MaybePromise<McpServer | Server> {
+    const server = this.mcp ?? this.server;
+    if (!server) {
+      throw new Error(
+        'Neither the `mcp` nor `server` property is set. Please set "mcp".'
+      );
+    }
+
+    return server;


I think this adds to the confusion right now.

IMO mcpServer should be the new name for server(). Thereby we can have a deprecation notice on the mcp() naming and keep everything clean. Much happier for more descriptive names especially as this class gets bigger.

mattzcarey

Agreed server.server is super annoying and doesnt give you any info on what each class should do. Also agreed that the clientManager being called mcp is confusing.

To make migration a bit smoother I would propose:

mcp -> mcpClientManager
server -> mcpServer

the 2. also emulates the Anthropic way of doing things in MCP TS SDK where the McpServer is a higher level abstraction and the Server is the lower level one. This will be easy to land as we can deprecate the old names with no conflict.

threepointone · 2025-10-09T15:46:32Z

but that still means writing mcpServer.server

mattzcarey · 2025-10-09T16:22:53Z

but that still means writing mcpServer.server

i hate that much less. You also only need to write that when accessing the underlying sdk server which makes sense?

kentcdodds commented Aug 28, 2025

View reviewed changes

kentcdodds mentioned this pull request Aug 28, 2025

MCP: Deal with the server.server echo? #425

Open

cliffhall reviewed Aug 28, 2025

View reviewed changes

whoiskatrin requested a review from threepointone August 29, 2025 16:13

turns out mcp was used in an example. This should probably be major

c8994e2

kentcdodds commented Aug 29, 2025

View reviewed changes

whoiskatrin added on the roadmap Feature accepted and planned for implementation mcp Issues related to MCP functionality breaking change labels Sep 15, 2025

mattzcarey reviewed Oct 9, 2025

View reviewed changes

mattzcarey requested changes Oct 9, 2025

View reviewed changes

Nithin200487 approved these changes Oct 13, 2025

View reviewed changes

feat: rename server property to mcp in MCP-related classes for improved developer experience #427

Are you sure you want to change the base?

feat: rename server property to mcp in MCP-related classes for improved developer experience #427

Uh oh!

Conversation

kentcdodds commented Aug 28, 2025

Uh oh!

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

Uh oh!

🦋 Changeset detected

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

whoiskatrin commented Sep 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kentcdodds commented Sep 12, 2025

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mattzcarey left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

threepointone commented Oct 9, 2025

Uh oh!

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

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

changeset-bot bot commented Aug 28, 2025 •

edited

Loading

cliffhall Aug 28, 2025 •

edited

Loading

pkg-pr-new bot commented Aug 29, 2025 •

edited

Loading

whoiskatrin commented Sep 12, 2025 •

edited

Loading

mattzcarey Oct 9, 2025 •

edited

Loading

mattzcarey left a comment •

edited

Loading

mattzcarey commented Oct 9, 2025 •

edited

Loading