MCP handler APIs

The Agents SDK provides two server handler paths:

McpAgent is deprecated and feature-frozen. Migrate existing McpAgent servers to a stateless handler. Refer to the migration guide when sessionful features require a staged rollout.

For a stateless server:

npm i agents @modelcontextprotocol/server@2.0.0 zod

yarn add agents @modelcontextprotocol/server@2.0.0 zod

pnpm add agents @modelcontextprotocol/server@2.0.0 zod

bun add agents @modelcontextprotocol/server@2.0.0 zod

For an explicit legacy server:

npm i agents @modelcontextprotocol/sdk@1.30.0 zod

yarn add agents @modelcontextprotocol/sdk@1.30.0 zod

pnpm add agents @modelcontextprotocol/sdk@1.30.0 zod

bun add agents @modelcontextprotocol/sdk@1.30.0 zod

Use the exact MCP versions required by your installed Agents release.

createMcpHandler creates a callable stateless MCP request handler from an MCP SDK v2 server factory. Invoke it from a Worker's object fetch() export or compose it inside another handler.

import {
	createMcpHandler,
	type CreateMcpHandlerOptions,
	type StatelessMcpHandler,
} from "agents/mcp/server";
import type { McpServerFactory } from "@modelcontextprotocol/server";

function createMcpHandler(
	factory: McpServerFactory,
	options?: CreateMcpHandlerOptions,
): StatelessMcpHandler;

• factory creates a fresh McpServer or Server from @modelcontextprotocol/server. It can be synchronous or asynchronous.
• options combines Agents Worker options with supported upstream SDK v2 handler options.

The factory receives this request context:

interface McpRequestContext {
	era: "modern" | "legacy";
	authInfo?: AuthInfo;
	requestInfo?: Request;
}

A zero-argument factory remains valid.

import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";
import { z } from "zod";

function createServer() {
	const server = new McpServer({
		name: "hello-server",
		version: "1.0.0",
	});

	server.registerTool(
		"hello",
		{
			description: "Return a greeting",
			inputSchema: { name: z.string().optional() },
		},
		async ({ name }) => ({
			content: [{ type: "text", text: `Hello, ${name ?? "World"}!` }],
		}),
	);

	return server;
}

export default {
	fetch(request, env, ctx) {
		return createMcpHandler(createServer)(request, env, ctx);
	},
};

import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";
import { z } from "zod";

function createServer() {
	const server = new McpServer({
		name: "hello-server",
		version: "1.0.0",
	});

	server.registerTool(
		"hello",
		{
			description: "Return a greeting",
			inputSchema: { name: z.string().optional() },
		},
		async ({ name }) => ({
			content: [{ type: "text", text: `Hello, ${name ?? "World"}!` }],
		}),
	);

	return server;
}

export default {
	fetch(request, env, ctx) {
		return createMcpHandler(createServer)(request, env, ctx);
	},
} satisfies ExportedHandler;

Pass the factory itself. Do not create one global server instance or pass a constructed SDK v2 server directly.

The following options are available:

SDK v1 transport options do not apply to this handler. It rejects options such as transport, storage, sessionIdGenerator, eventStore, and enableJsonResponse.

Use responseMode: "json" instead of enableJsonResponse: true. JSON mode drops notifications emitted before a final result.

The handler creates one MCP server for each request. This follows the draft protocol model, where version, identity, and capabilities travel with every request rather than through a protocol session.

Application data can still be durable. Store cross-request data behind an authenticated handle in a Durable Object, D1, KV, or R2 rather than an MCP session ID.

Elicitation through a stateless handler returns input_required and completes through multi-round-trip requests (MRTR). On each retry, the SDK echoes the latest requestState and sends responses for the immediately preceding input round. It does not accumulate earlier inputResponses. The Worker does not remain suspended while a user responds.

Use inputRequired(...) to request input. Read that round's accepted form content from context.mcpReq.inputResponses with acceptedContent(...). Seal trusted intermediate values needed by later rounds into integrity-protected requestState.

Refer to the stateless elicitation example ↗ for a two-round tool flow. For stateful pushed requests, refer to Elicitation on legacy servers.

The Workers wrapper validates every present browser Origin. It rejects malformed, opaque, and non-HTTP Origins with 403. Origin-less non-browser MCP clients remain valid.

The default allowlist includes localhost-class Origins, the endpoint's workers.dev hostname, and a concrete hostname from corsOptions.origin. The handler also applies matching Host checks to localhost and workers.dev endpoints. This keeps local DNS rebinding protection without requiring a separate Origin list for the common Workers routes.

For a custom domain with wildcard CORS, set allowedHostnames and allowedOriginHostnames explicitly. If corsOptions.origin is a concrete URL, the handler derives its Origin hostname automatically:

export default {
	fetch(request, env, ctx) {
		return createMcpHandler(createServer, {
			allowedHostnames: ["mcp.example.com"],
			corsOptions: {
				origin: "https://app.example.com",
			},
		})(request, env, ctx);
	},
};

export default {
	fetch(request, env, ctx) {
		return createMcpHandler(createServer, {
			allowedHostnames: ["mcp.example.com"],
			corsOptions: {
				origin: "https://app.example.com",
			},
		})(request, env, ctx);
	},
} satisfies ExportedHandler;

Allowlist values are hostnames without a scheme or port. Origin matching ignores scheme and port.

Set allowedOriginHostnames: "*" only when trusted middleware validates Origins before calling the handler. This value turns off the handler Origin check, including malformed and opaque Origin rejection. MCP HTTP servers must validate browser Origins.

CORS response headers are not authentication. Protect the MCP endpoint with OAuth or another authentication layer.

The handler does not infer a Host allowlist from request.url. If a deployment accepts arbitrary Host values, validate them before calling the handler. Local servers outside Cloudflare Workers should follow the upstream SDK DNS rebinding guidance.

The default legacy: "stateless" setting accepts ordinary legacy tools, prompts, and resources. This lane uses the SDK v2 web-standard transport and does not import WorkerTransport.

This compatibility path does not provide a complete session transport:

• Each POST creates a new server and transport.
• HTTP GET and DELETE return 405.
• No MCP session ID persists.
• Pushed elicitation, sampling, and roots requests fail immediately.
• Standalone streams, resumability, replay, and session deletion are unavailable.
• Published experimental tasks are not supported through this path.

Set legacy: "reject" for a stateless-only endpoint. During migration, route legacy clients that still require protocol sessions to a temporary createLegacyMcpHandler or McpAgent lane.

createMcpHandler returns a StatelessMcpHandler. It is callable and exposes request and notification controls:

interface StatelessMcpHandler {
	(request: Request, env: unknown, ctx: ExecutionContext): Promise<Response>;

	fetch(
		request: Request,
		options?: McpHandlerRequestOptions,
	): Promise<Response>;

	notify: {
		toolsChanged(): void;
		promptsChanged(): void;
		resourcesChanged(): void;
		resourceUpdated(uri: string): void;
	};
}

type McpHandlerRequestOptions = {
	authInfo?: AuthInfo;
	parsedBody?: unknown;
};

Call the handler from a Worker's object fetch() export:

export default {
	fetch(request, env, ctx) {
		return createMcpHandler(createServer)(request, env, ctx);
	},
} satisfies ExportedHandler;

Do not export the callable directly as a Worker's default export. Wrangler treats function default exports as WorkerEntrypoint classes.

Use fetch() when another framework or authentication layer has already parsed or validated request data:

const response = await handler.fetch(request, {
	authInfo,
	parsedBody,
});

authInfo is passed to the server factory and request handlers. The handler does not derive it from request headers or verify access tokens. parsedBody avoids reparsing a JSON body that upstream middleware already consumed.

The notify methods publish typed change events to matching open subscriptions/listen streams:

Calling a notifier when no matching subscription is open is a no-op.

Notification routing belongs to the handler instance. Constructing a new handler inside every Worker fetch() call is suitable for ordinary tools, prompts, resources, and MRTR elicitation. It cannot notify a subscriptions/listen stream owned by an earlier handler instance.

Create the handler once at module scope when using notify or subscriptions/listen, then invoke it from the Worker object export:

const handler = createMcpHandler(createServer);

export default {
	fetch(request, env, ctx) {
		return handler(request, env, ctx);
	},
} satisfies ExportedHandler;

Notifications are isolate-local. A notification published in one Worker isolate does not reach a subscription stream running in another isolate.

createLegacyMcpHandler serves an SDK v1 server through WorkerTransport.

import {
	createLegacyMcpHandler,
	type CreateLegacyMcpHandlerOptions,
	type LegacyMcpHandler,
} from "agents/mcp";
import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

function createLegacyMcpHandler(
	server: McpServer | Server,
	options?: CreateLegacyMcpHandlerOptions,
): LegacyMcpHandler;

Use this handler only as a temporary migration bridge when an existing SDK v1 endpoint still requires legacy sessions, transport storage, event replay, or pushed server-to-client requests.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { createLegacyMcpHandler } from "agents/mcp";

function createServer() {
	return new McpServer({ name: "legacy-server", version: "1.0.0" });
}

export default {
	async fetch(request, env, ctx) {
		return createLegacyMcpHandler(createServer())(request, env, ctx);
	},
};

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { createLegacyMcpHandler } from "agents/mcp";

function createServer() {
	return new McpServer({ name: "legacy-server", version: "1.0.0" });
}

export default {
	async fetch(request: Request, env: Env, ctx: ExecutionContext) {
		return createLegacyMcpHandler(createServer())(request, env, ctx);
	},
} satisfies ExportedHandler<Env>;

Passing an SDK v1 server to createMcpHandler still works but emits a deprecation warning. Move the server to an SDK v2 factory and pass the factory to createMcpHandler. If sessionful behavior prevents an immediate migration, use createLegacyMcpHandler only on the temporary legacy lane.

experimental_createMcpHandler is also deprecated. Move its SDK v1 server to an SDK v2 factory. Use createLegacyMcpHandler only as a temporary bridge for sessionful behavior.

CreateLegacyMcpHandlerOptions extends WorkerTransportOptions and adds these fields:

Common WorkerTransportOptions include:

Create a fresh SDK v1 server for each request unless you provide a persistent transport already connected to that server. One server cannot reconnect to several transports.

A compatible @cloudflare/workers-oauth-provider supplies verified standard AuthInfo to SDK v2 callbacks at context.http.authInfo.

The existing getMcpAuthContext() helper continues to return application props:

interface McpAuthContext {
	props: Record<string, unknown>;
}

import { getMcpAuthContext } from "agents/mcp/server";

server.registerTool(
	"whoami",
	{ description: "Return the current identity", inputSchema: {} },
	async (_args, context) => {
		const auth = getMcpAuthContext();

		return {
			content: [
				{
					type: "text",
					text: JSON.stringify({
						clientId: context.http?.authInfo?.clientId,
						scopes: context.http?.authInfo?.scopes,
						userId: auth?.props.userId,
					}),
				},
			],
		};
	},
);

import { getMcpAuthContext } from "agents/mcp/server";

server.registerTool(
	"whoami",
	{ description: "Return the current identity", inputSchema: {} },
	async (_args, context) => {
		const auth = getMcpAuthContext();

		return {
			content: [
				{
					type: "text",
					text: JSON.stringify({
						clientId: context.http?.authInfo?.clientId,
						scopes: context.http?.authInfo?.scopes,
						userId: auth?.props.userId,
					}),
				},
			],
		};
	},
);

Do not log or return authInfo.token or authInfo.extra.props.

Refer to Migrate to MCP SDK v2 before changing an existing server. The migration guide covers dual-era routing, stateful servers, client changes, and rollout checks.