README.md
A lightweight template for deploying stateless MCP servers on Cloudflare Workers
MCP Server (createMcpHandler)
The simplest way to run a stateless MCP server on Cloudflare Workers. Uses createMcpHandler from the Agents SDK to handle all MCP protocol details in one line.
What it demonstrates
createMcpHandler— the Agents SDK helper that wraps anMcpServerinto a Worker-compatible fetch handler- Minimal setup — define tools on an
McpServer, pass it tocreateMcpHandler, done - Stateless — no Durable Objects, no persistent state, each request is independent
Running
npm install
npm run dev
Open the browser to see the built-in tool tester, or connect with the MCP Inspector at http://localhost:5173/mcp.
How it works
import { createMcpHandler } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
function createServer() {
const server = new McpServer({ name: "Hello MCP Server", version: "1.0.0" });
server.registerTool(
"hello",
{
description: "Returns a greeting",
inputSchema: { name: z.string().optional() }
},
async ({ name }) => ({
content: [{ type: "text", text: `Hello, ${name ?? "World"}!` }]
})
);
return server;
}
export default {
fetch: async (request, env, ctx) => {
const server = createServer();
return createMcpHandler(server)(request, env, ctx);
}
};
Related examples
- `mcp` — stateful MCP server with
McpAgentand Durable Objects - `mcp-worker-authenticated` — adding OAuth authentication
- `mcp-client` — connecting to MCP servers as a client
Tools (1)
helloReturns a greetingConfiguration
claude_desktop_config.json
{"mcpServers": {"mcp-worker": {"command": "npx", "args": ["-y", "mcp-worker"]}}}Try it
→Call the hello tool to get a greeting for the name 'Claude'.
→Use the hello tool without providing a name to see the default greeting.
→Test the hello tool functionality on the local worker instance.