With Cloudflare's Agents SDK, how do you expose a support agent's tools to other agents as a remote MCP server now that McpAgent is deprecated?
answer
- server side and client side
- deprecated and feature-frozen
- a factory, one server per request
- agents/mcp/server
- addMcpServer() on the consumer
basics
~10 sServe the tools from a Worker route with createMcpHandler(createServer) from agents/mcp/server, which builds a fresh MCP server per request; McpAgent is deprecated and kept only for migrating servers. Other agents connect with this.addMcpServer().
solid answer
~40 sSince Agents SDK v0.20.0, `McpAgent` (one Durable Object per MCP session, served with `McpAgent.serve("/mcp")`) is deprecated and feature-frozen. New servers use `createMcpHandler` from `agents/mcp/server`: you pass a factory that returns an `McpServer` from `@modelcontextprotocol/server` with its tools, and call `createMcpHandler(createServer)(request, env, ctx)` from `fetch`. It creates a server per request, needs no Durable Object, and by default (`legacy: "stateless"`) also answers older stateless clients. Durable data stays where it already lives: tool handlers reach the customer's `SupportAgent` through `getAgentByName()`, or read D1, KV or R2. Consuming agents call `this.addMcpServer(name, url)`, which persists the registration in SQLite, restores it on wake and is idempotent for the same name and URL. Put authentication in front; CORS is not access control.
code
typescript · 26 linesimport { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";
import { getAgentByName } from "agents";
function makeServerFactory(env: Env) {
return () => {
const server = new McpServer({ name: "support-tools", version: "1.0.0" });
server.registerTool(
"queueStatus",
{ description: "Number of open tickets in the support queue" },
async () => {
const queue = await getAgentByName(env.SupportAgent, "support-queue");
const open = await queue.openTicketCount(); // Durable Object RPC
return { content: [{ type: "text", text: String(open) }] };
},
);
return server;
};
}
export default {
fetch(request: Request, env: Env, ctx: ExecutionContext) {
// authenticate the caller before this line in a real deployment
return createMcpHandler(makeServerFactory(env))(request, env, ctx);
},
} satisfies ExportedHandler<Env>;go deeper
Recall that createMcpHandler serves MCP tools from a Worker route and that another agent connects to them with addMcpServer().
Explain the per-request server factory, the legacy option, and why McpAgent's per-session Durable Object is now a migration path rather than the default.
Plan a staged migration off McpAgent for clients that still need sessions, and secure the route with authentication and explicit hostname allowlists.
Decide which data a tool may touch and where it lives, since a stateless MCP layer in front of per-customer agents moves isolation into the agents.
## Two roles: serving tools and using them A support agent that "exposes tools to other agents" over the Model Context Protocol involves two sides in Cloudflare's Agents SDK: - a **server** side, a Worker route that answers MCP requests and lists tools such as `lookupTicket` or `scheduleFollowUp`; - a **client** side, the other agents, which connect to that route and hand its tools to their model. The protocol itself, its messages and its versions, is a subject of its own. The question here is which SDK classes do each job on Cloudflare today. ## What changed: `McpAgent` is deprecated For a long time the answer was **`McpAgent`** from `agents/mcp`: a class backed by a Durable Object, one instance per MCP client session, with the Agent state APIs (`state`, `setState()`, `sql`) and a static `McpAgent.serve("/mcp")` that built the Worker handler. Since **Agents SDK v0.20.0** (July 2026), which added support for the stateless MCP 2026-07-28 release candidate, the docs mark `McpAgent` **deprecated and feature-frozen**. It remains for existing servers while they migrate. The current path is **`createMcpHandler`**: | | `createMcpHandler` (current) | `McpAgent` (legacy) | | --- | --- | --- | | Import | `agents/mcp/server` | `agents/mcp` | | MCP server package | `@modelcontextprotocol/server` | `@modelcontextprotocol/sdk` | | Per request | a fresh server from your factory | one Durable Object per client session | | Durable Object needed | no | yes | | Session state | none | per session, reset when the client starts a new session | ## Serving tools with `createMcpHandler` 1. Write a **factory** function that builds and returns an `McpServer` and registers its tools. 2. In the Worker's `fetch`, call `createMcpHandler(createServer)(request, env, ctx)`. 3. Pass the factory itself, not a server you constructed once. The handler creates **one server per request**, because the stateless protocol carries version, identity and capabilities on every request. Useful options, with their defaults: - `route`: the exact path handled, `"/mcp"` by default. - `legacy`: `"stateless"` (default) also answers older clients that send ordinary stateless requests; `"reject"` serves only the new protocol. - `allowedHostnames` and `allowedOriginHostnames`: needed on a custom domain, since the default Host and Origin allowlist covers localhost and the `workers.dev` route. - CORS headers are not authentication. Put OAuth or another authentication layer in front of the endpoint. ## Where the tool data lives now A stateless handler forgets everything between requests. That is fine for this scenario, because the support data already has a home: the customer's `SupportAgent` instance. A tool handler can reach it from the Worker with `getAgentByName(env.SupportAgent, name)` and call an RPC method, or read D1, KV or R2. The docs' rule is to keep cross-request data behind an authenticated handle in one of those stores rather than in an MCP session ID. ## The other agents: `addMcpServer()` An agent that wants these tools calls `this.addMcpServer("support", "https://support.example.com/mcp")`: - The registration is stored in the agent's SQLite and **restored when the agent wakes**. - The call is **idempotent** when name and URL both match an existing connection, so it is safe in `onStart()`. - `this.mcp.getAITools()` converts the connected tools into the AI SDK's format for a model call. - An `AIChatAgent` waits for these connections before `onChatMessage()` runs (`waitForMcpConnections`, 10 seconds by default), so restored tools are present after hibernation. ## Migrating an existing `McpAgent` - Ordinary tools, prompts and resources move into a factory and one `createMcpHandler` route. - A server that relies on sessions, pushed server-to-client requests, standalone streams or replay needs a staged migration: add the stateless route beside the old one, send only legacy traffic to `McpAgent.serve()`, and remove it once clients have moved and old sessions have drained. ## Why the stateless design fits agents Moving state out of the MCP layer sounds like a loss, but in this scenario it removes a duplicate. With `McpAgent`, a tool call ran inside a session object whose state was reset when the client started a new session, while the real customer memory sat in another agent anyway. With `createMcpHandler`, the MCP route is a thin, stateless front door: any number of calling agents can use it, a deploy does not strand sessions, and the support agents remain the single place where a customer's history and schedules live. The cost is that anything a tool needs between calls must be stored deliberately, behind an authenticated handle.
- What happened to state in a legacy McpAgent server when the same MCP client reconnected later?Each client session was backed by its own `McpAgent` instance, so a reconnecting client started a new session and the state was reset. That is one reason durable support data belongs in the customer's agent or another store, not in the MCP server's session.
- Why must the MCP route set allowedHostnames when it moves to a custom domain?The Workers wrapper checks Host and browser Origin against an allowlist that, by default, covers localhost-class names and the endpoint's `workers.dev` hostname. On a custom domain with wildcard CORS you list the hostnames explicitly; otherwise valid requests are refused.
- Starting a new MCP server on McpAgent because older tutorials do.
- Constructing one global McpServer and passing it to createMcpHandler().
- Keeping durable customer data in MCP session state.
- Treating CORS headers on the MCP route as access control.
- Confusing addMcpServer(), which connects to a server, with serving one.
Assumes the Agents SDK as of 2026-10-10: v0.20.0 (July 2026) made createMcpHandler with a per-request server factory the current way to serve MCP and marked McpAgent deprecated and feature-frozen.