Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4d5ab91
feat: rename server property to mcp in MCP-related classes for improv…
kentcdodds Aug 28, 2025
c8994e2
turns out mcp was used in an example. This should probably be major
kentcdodds Aug 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions .changeset/mcp-property-rename.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
---
"@cloudflare/agents": patch
---

Rename `server` property to `mcp` in MCP-related classes for better developer experience

## Changes

- **BREAKING**: Renamed `server` property to `mcp` in `McpAgent` class and related examples
- **BREAKING**: Renamed `mcp` property to `mcpClientManager` in `Agent` class to avoid naming conflicts
- Added backward compatibility support for `server` property in `McpAgent` with deprecation warning
- Updated all MCP examples to use the new `mcp` property naming convention
- Improved property naming consistency across the MCP implementation

## Migration

If you're using the `server` property in your `McpAgent` implementations, update your code:

```ts
// Before
export class MyMcpAgent extends McpAgent {
server = new McpServer({...});
}

// After
export class MyMcpAgent extends McpAgent {
mcp = new McpServer({...});
}
```

The `server` property is still supported for backward compatibility but will be removed in a future version.
8 changes: 4 additions & 4 deletions examples/mcp-elicitation-demo/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ type Env = {
};

export class McpServerAgent extends McpAgent<Env, { counter: number }, {}> {
server = new McpServer({
mcp = new McpServer({
name: "Elicitation Demo Server",
version: "1.0.0"
})
Expand Down Expand Up @@ -94,7 +94,7 @@ export class McpServerAgent extends McpAgent<Env, { counter: number }, {}> {

async init() {
// Counter tool with user confirmation via elicitation
this.server.tool(
this.mcp.tool(
"increment-counter",
"Increment the counter with user confirmation",
{
Expand Down Expand Up @@ -162,7 +162,7 @@ export class McpServerAgent extends McpAgent<Env, { counter: number }, {}> {
);

// User creation tool with form-based elicitation
this.server.tool(
this.mcp.tool(
"create-user",
"Create a new user with form input",
{
Expand Down Expand Up @@ -265,7 +265,7 @@ export class McpServerAgent extends McpAgent<Env, { counter: number }, {}> {
// Direct MCP connection
export class MyMcpServer extends McpAgent {
async init() {
this.server.tool(
this.mcp.tool(
"my-tool",
"My tool",
{ input: z.string() },
Expand Down
8 changes: 4 additions & 4 deletions examples/mcp-elicitation-demo/src/server.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
};

export class McpServerAgent extends McpAgent<Env, { counter: number }, {}> {
server = new McpServer({
mcp = new McpServer({
name: "Elicitation Demo Server",
version: "1.0.0"
});
Expand Down Expand Up @@ -83,7 +83,7 @@

async init() {
// Counter tool with user confirmation via elicitation
this.server.tool(
this.mcp.tool(
"increment-counter",
"Increment the counter with user confirmation",
{
Expand Down Expand Up @@ -151,7 +151,7 @@
);

// User creation tool with form-based elicitation
this.server.tool(
this.mcp.tool(
"create-user",
"Create a new user with form input",
{
Expand Down Expand Up @@ -225,7 +225,7 @@
);

// Counter resource
this.server.resource("counter", "mcp://resource/counter", (uri: URL) => {
this.mcp.resource("counter", "mcp://resource/counter", (uri: URL) => {
return {
contents: [
{
Expand Down Expand Up @@ -388,7 +388,7 @@
__clientSession: this.name
};

const result = await this.mcp.callTool({

Check failure on line 391 in examples/mcp-elicitation-demo/src/server.ts

View workflow job for this annotation

GitHub Actions / check (ubuntu-24.04) 

Property 'mcp' does not exist on type 'MyAgent'.
serverId,
name: toolName,
arguments: enhancedArgs
Expand Down
6 changes: 3 additions & 3 deletions examples/mcp/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,17 +19,17 @@ Inside your `McpAgent`'s `async init()` method, you can use the MCP SDK to defin

```ts
export class MyMCP extends McpAgent<Env> {
server = new McpServer({
mcp = new McpServer({
name: "Demo",
version: "1.0.0"
});

async init() {
this.server.resource(`counter`, `mcp://resource/counter`, (uri) => {
this.mcp.resource(`counter`, `mcp://resource/counter`, (uri) => {
// ...
});

this.server.tool(
this.mcp.tool(
"add",
"Add two numbers together",
{ a: z.number(), b: z.number() },
Expand Down
6 changes: 3 additions & 3 deletions examples/mcp/src/server.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ type Env = {
type State = { counter: number };

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

@cliffhall cliffhall Aug 28, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

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

Copy link
Author

@kentcdodds kentcdodds Aug 28, 2025

Choose a reason for hiding this comment

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

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
			},
		);
	}
}

Copy link

@cliffhall cliffhall Aug 28, 2025

Choose a reason for hiding this comment

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

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
			},
		);
	}
}

Copy link
Author

@kentcdodds kentcdodds Aug 28, 2025

Choose a reason for hiding this comment

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

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!

Copy link
Author

@kentcdodds kentcdodds Aug 28, 2025

Choose a reason for hiding this comment

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

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

name: "Demo",
version: "1.0.0"
});
Expand All @@ -19,13 +19,13 @@ export class MyMCP extends McpAgent<Env, State, {}> {
};

async init() {
this.server.resource("counter", "mcp://resource/counter", (uri) => {
this.mcp.resource("counter", "mcp://resource/counter", (uri) => {
return {
contents: [{ text: String(this.state.counter), uri: uri.href }]
};
});

this.server.tool(
this.mcp.tool(
"add",
"Add to the counter, stored in the MCP",
{ a: z.number() },
Expand Down
6 changes: 3 additions & 3 deletions packages/agents/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -411,7 +411,7 @@ type Env = {
type State = { counter: number };

export class MyMCP extends McpAgent<Env, State, {}> {
server = new McpServer({
mcp = new McpServer({
name: "Demo",
version: "1.0.0"
});
Expand All @@ -421,13 +421,13 @@ export class MyMCP extends McpAgent<Env, State, {}> {
};

async init() {
this.server.resource("counter", "mcp://resource/counter", (uri) => {
this.mcp.resource("counter", "mcp://resource/counter", (uri) => {
return {
contents: [{ text: String(this.state.counter), uri: uri.href }]
};
});

this.server.tool(
this.mcp.tool(
"add",
"Add to the counter, stored in the MCP",
{ a: z.number() },
Expand Down
21 changes: 12 additions & 9 deletions packages/agents/src/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -291,7 +291,10 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
private _ParentClass: typeof Agent<Env, State> =
Object.getPrototypeOf(this).constructor;

mcp: MCPClientManager = new MCPClientManager(this._ParentClass.name, "0.0.1");
mcpClientManager: MCPClientManager = new MCPClientManager(
this._ParentClass.name,
"0.0.1"
);
Copy link
Author

@kentcdodds kentcdodds Aug 28, 2025

Choose a reason for hiding this comment

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

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


/**
* Initial state for the Agent
Expand Down Expand Up @@ -441,8 +444,8 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
return agentContext.run(
{ agent: this, connection: undefined, request, email: undefined },
async () => {
if (this.mcp.isCallbackRequest(request)) {
await this.mcp.handleCallbackRequest(request);
if (this.mcpClientManager.isCallbackRequest(request)) {
await this.mcpClientManager.handleCallbackRequest(request);

// after the MCP connection handshake, we can send updated mcp state
this.broadcast(
Expand Down Expand Up @@ -1483,7 +1486,7 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
};
}

const { id, authUrl, clientId } = await this.mcp.connect(url, {
const { id, authUrl, clientId } = await this.mcpClientManager.connect(url, {
client: options?.client,
reconnect,
transport: {
Expand All @@ -1500,7 +1503,7 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
}

async removeMcpServer(id: string) {
this.mcp.closeConnection(id);
this.mcpClientManager.closeConnection(id);
this.sql`
DELETE FROM cf_agents_mcp_servers WHERE id = ${id};
`;
Expand All @@ -1514,10 +1517,10 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {

getMcpServers(): MCPServersState {
const mcpState: MCPServersState = {
prompts: this.mcp.listPrompts(),
resources: this.mcp.listResources(),
prompts: this.mcpClientManager.listPrompts(),
resources: this.mcpClientManager.listResources(),
servers: {},
tools: this.mcp.listTools()
tools: this.mcpClientManager.listTools()
};

const servers = this.sql<MCPServerRow>`
Expand All @@ -1526,7 +1529,7 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {

if (servers && Array.isArray(servers) && servers.length > 0) {
for (const server of servers) {
const serverConn = this.mcp.mcpConnections[server.id];
const serverConn = this.mcpClientManager.mcpConnections[server.id];
mcpState.servers[server.id] = {
auth_url: server.auth_url,
capabilities: serverConn?.serverCapabilities ?? null,
Expand Down
35 changes: 30 additions & 5 deletions packages/agents/src/mcp/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,8 +210,24 @@ export abstract class McpAgent<
*/
private _agent: Agent<Env, State>;

get mcp() {
return this._agent.mcp;
get mcpClientManager() {
return this._agent.mcpClientManager;
}
Comment on lines +213 to +215
Copy link
Author

@kentcdodds kentcdodds Aug 28, 2025

Choose a reason for hiding this comment

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

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.

Copy link
Contributor

@mattzcarey mattzcarey Oct 9, 2025

Choose a reason for hiding this comment

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

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.


/**
* Getter that returns the MCP server implementation.
* Supports both 'server' and 'mcp' properties for better developer experience.
* If 'mcp' property is set, use that; otherwise fall back to 'server' property.
*/
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;
Comment on lines +222 to +230
Copy link
Contributor

@mattzcarey mattzcarey Oct 9, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

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.

}

protected constructor(ctx: DurableObjectState, env: Env) {
Expand Down Expand Up @@ -333,7 +349,7 @@ export abstract class McpAgent<
)) as TransportType;
await this._init(this.props);

const server = await this.server;
const server = await this.mcpServer;

// Connect to the MCP server
if (this._transportType === "sse") {
Expand All @@ -350,8 +366,17 @@ export abstract class McpAgent<

/**
* McpAgent API
* @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>;
Comment on lines +369 to +379
Copy link
Author

@kentcdodds kentcdodds Aug 28, 2025

Choose a reason for hiding this comment

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

This is the primary focus of this PR

Copy link
Contributor

@mattzcarey mattzcarey Oct 9, 2025

Choose a reason for hiding this comment

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

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

props!: Props;
initRun = false;

Expand Down Expand Up @@ -430,7 +455,7 @@ export abstract class McpAgent<
// This is not the path that the user requested, but the path that the worker
// generated. We'll use this path to determine which transport to use.
const path = url.pathname;
const server = await this.server;
const server = await this.mcpServer;

switch (path) {
case "/sse": {
Expand Down
Loading