Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cloudflare/agents/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers the different ways to create MCP servers with the Agents SDK and helps you choose the right approach.

​
Choosing an Approach

ApproachStateful?Requires Durable Objects?Best for
createMcpHandler()NoNoStateless tools, simplest setup
McpAgentYesYesStateful tools, per-session state, elicitation
Raw WebStandardStreamableHTTPServerTransportNoNoFull control, no SDK dependency
  • createMcpHandler() is the fastest way to get a stateless MCP server running. Use it when your tools do not need per-session state.
  • McpAgent gives you a Durable Object per session with built-in state management, elicitation support, and both SSE and Streamable HTTP transports.
  • Raw transport gives you full control if you want to use the @modelcontextprotocol/sdk directly without the Agents SDK helpers.

​
Stateless MCP Server with createMcpHandler()

The simplest way to create an MCP server. No Durable Objects or bindings required: 
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 message",
      inputSchema: { name: z.string().optional() }
    },
    async ({ name }) => ({
      content: [{ text: `Hello, ${name ?? "World"}!`, type: "text" }]
    })
  );

  return server;
}

export default {
  fetch: async (request: Request, env: Env, ctx: ExecutionContext) => {
    const server = createServer();
    return createMcpHandler(server)(request, env, ctx);
  }
};
Create a new McpServer instance per request. The MCP SDK does not allow connecting an already-connected server to a new transport.

​
createMcpHandler Options

createMcpHandler(server, {
  route: "/mcp",              // path to handle (default: "/mcp")
  enableJsonResponse: true,   // use JSON responses instead of SSE streaming
  sessionIdGenerator: () => crypto.randomUUID(),
  corsOptions: { ... },       // CORS configuration
  authContext: { props: {} },  // manually set auth context
  transport: workerTransport   // provide your own WorkerTransport instance
});

​
Accessing Authenticated User Context

When your MCP server is wrapped with OAuthProvider from @cloudflare/workers-oauth-provider, authenticated user information is available inside tools via getMcpAuthContext(): 
import { createMcpHandler, getMcpAuthContext } from "agents/mcp";

server.registerTool(
  "whoami",
  { description: "Returns the authenticated user" },
  async () => {
    const auth = getMcpAuthContext();
    return {
      content: [
        {
          type: "text",
          text: auth ? JSON.stringify(auth.props) : "Not authenticated"
        }
      ]
    };
  }
);
The OAuthProvider sets ctx.props on the execution context, which createMcpHandler automatically picks up and makes available via getMcpAuthContext().

​
Stateful MCP Server with McpAgent

McpAgent gives each client session its own Durable Object with persistent state. Use this when your tools need to track per-session data.

​
Writing TinyMCP

Prototyping is very easy! If you want to quickly deploy an MCP, it only takes ~20 lines of code: 
import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

// Our MCP server!
export class TinyMcp extends McpAgent {
  server = new McpServer({ name: "", version: "v1.0.0" });

  async init() {
    this.server.registerTool(
      "square",
      {
        description: "Squares a number",
        inputSchema: { number: z.number() }
      },
      async ({ number }) => ({
        content: [{ type: "text", text: String(number ** 2) }]
      })
    );
  }
}

// This is literally all there is to our Worker
export default TinyMcp.serve("/");
Your wrangler.jsonc would look something like: 
{
  "name": "tinymcp",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-28",
  "compatibility_flags": ["nodejs_compat"],
  "durable_objects": {
    "bindings": [
      {
        "name": "MCP_OBJECT",
        "class_name": "TinyMcp"
      }
    ]
  },
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["TinyMcp"]
    }
  ]
}

​
What is going on here?

McpAgent requires us to define 2 bits, server and init(). init() is the initialization logic that runs every time our MCP server is started (each client session goes to a different Agent instance).
In there you will normally setup all your tools/resources and anything else you might need. In this case, we are only setting the tool square. That was just the McpAgent, but we still need a Worker to route requests to our MCP server. McpAgent exports a static method that deals with that for you. That is what TinyMcp.serve(...) is for.
It returns an object with a fetch handler that can act as our Worker entrypoint and deal with the Streamable HTTP transport for us, so we can deploy our MCP directly!

​
Putting it to the test

It is a very simple MCP indeed, but you can get a feel of how fast you can get a server up and running. You can deploy this worker and test your MCP with any client.

​
Password-protected StorageMCP with OAuth

To get a feel of what a more realistic MCP might look like, let’s deploy an MCP that lets anyone that knows our secret password access a shared R2 bucket.
This is an example of a custom authorization flow. Do not use this in production.
1

Define the McpAgent

Create your McpAgent with tools that interact with R2:
import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
import { env } from "cloudflare:workers";

export class StorageMcp extends McpAgent {
  server = new McpServer({ name: "", version: "v1.0.0" });

  async init() {
    const textRes = (text: string) => ({
      content: [{ type: "text" as const, text }]
    });

    this.server.registerTool(
      "writeFile",
      {
        description: "Store text as a file with the given path",
        inputSchema: {
          path: z.string().describe("Absolute path of the file"),
          content: z.string().describe("The content to store")
        }
      },
      async ({ path, content }) => {
        try {
          await env.BUCKET.put(path, content);
          return textRes(`Successfully stored contents to ${path}`);
        } catch (e: unknown) {
          return textRes(`Couldn't save to file. Found error ${e}`);
        }
      }
    );

    this.server.registerTool(
      "readFile",
      {
        description: "Read the contents of a file",
        inputSchema: {
          path: z.string().describe("Absolute path of the file to read")
        }
      },
      async ({ path }) => {
        const obj = await env.BUCKET.get(path);
        if (!obj || !obj.body)
          return textRes(`Error reading file at ${path}: not found`);
        try {
          return textRes(await obj.text());
        } catch (e: unknown) {
          return textRes(`Error reading file at ${path}: ${e}`);
        }
      }
    );

    this.server.registerTool(
      "whoami",
      {
        description: "Check who the user is"
      },
      async () => {
        return textRes(`${this.props?.userId}`);
      }
    );
  }
}
2

Create the OAuth flow

Build a simple password-based authentication flow:
import {
  OAuthProvider,
  type OAuthHelpers
} from "@cloudflare/workers-oauth-provider";

function passwordPage(opts: { query: string; error?: string }) {
  const err = opts.error
    ? `<p class="text-red-600 mb-2">${opts.error}</p>`
    : "";
  return new Response(
    `<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>ENTER THE MAGIC WORD</title>
  <script src="https://cdn.tailwindcss.com"></script>
</head>
<body class="font-sans grid place-items-center min-h-screen bg-gray-100">
  <form method="POST" action="/authorize?${opts.query}" 
        class="bg-white p-6 rounded-lg shadow-md w-full max-w-xs">
    <h1 class="text-lg font-semibold mb-3">ENTER THE MAGIC WORD</h1>
    ${err}
    <label class="block text-sm mb-1">Password</label>
    <input name="password" type="password" required autocomplete="current-password"
           class="w-full border rounded px-3 py-2 mb-3" />
    <button type="submit"
            class="w-full py-2 bg-black text-white rounded font-medium hover:bg-gray-800">
      Continue
    </button>
  </form>
</body>
</html>`,
    { headers: { "content-type": "text/html; charset=utf-8" } }
  );
}

interface StorageEnv {
  OAUTH_PROVIDER: OAuthHelpers;
  SHARED_PASSWORD: string;
}

const defaultHandler = {
  async fetch(request: Request, env: StorageEnv) {
    const provider = env.OAUTH_PROVIDER;
    const url = new URL(request.url);

    if (url.pathname !== "/authorize") {
      return new Response("NOT FOUND", { status: 404 });
    }

    const oauthReq = await provider.parseAuthRequest(request);

    if (request.method === "GET") {
      return passwordPage({ query: url.searchParams.toString() });
    }

    if (request.method === "POST") {
      const form = await request.formData();
      const password = String(form.get("password") || "");

      const SHARED_PASSWORD = env.SHARED_PASSWORD;
      if (!SHARED_PASSWORD) {
        return new Response("Server misconfigured: missing SHARED_PASSWORD", {
          status: 500
        });
      }
      if (password !== SHARED_PASSWORD) {
        return passwordPage({
          query: url.searchParams.toString(),
          error: "Wrong password."
        });
      }

      const userId = "friend";

      const { redirectTo } = await provider.completeAuthorization({
        request: oauthReq,
        userId,
        scope: [],
        props: { userId },
        metadata: undefined
      });

      return Response.redirect(redirectTo, 302);
    }

    return new Response("Method Not Allowed", {
      status: 405,
      headers: { allow: "GET, POST" }
    });
  }
};
3

Wire it all together

Combine the MCP server with OAuth:
export default new OAuthProvider({
  authorizeEndpoint: "/authorize",
  tokenEndpoint: "/token",
  clientRegistrationEndpoint: "/register",
  apiHandlers: { "/mcp": StorageMcp.serve("/mcp") },
  defaultHandler
});
Add these to your wrangler.jsonc:
{
  "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "your-bucket-name" }],
  "kv_namespaces": [
    {
      "binding": "OAUTH_KV",
      "id": "your-kv-id"
    }
  ]
}

​
Data Jurisdiction for Compliance

McpAgent supports specifying a data jurisdiction for your MCP server, which is particularly useful for satisfying GDPR and other data residency regulations.

​
Using the EU Jurisdiction for GDPR

To comply with GDPR requirements, you can specify the "eu" jurisdiction to ensure that all data processed by your MCP server remains within the European Union: 
export default TinyMcp.serve("/", {
  jurisdiction: "eu"
});
Or with the OAuth-protected example: 
export default new OAuthProvider({
  authorizeEndpoint: "/authorize",
  tokenEndpoint: "/token",
  clientRegistrationEndpoint: "/register",
  apiHandlers: {
    "/mcp": StorageMcp.serve("/mcp", { jurisdiction: "eu" })
  },
  defaultHandler
});
When you specify jurisdiction: "eu", Cloudflare will create the Durable Object instances in EU data centers, ensuring that:
  • All MCP session data stays within the EU
  • User data processed by your tools remains in the EU
  • State stored in the Durable Object’s storage API stays in the EU
This helps you comply with GDPR’s data localization requirements without any additional configuration.

​
Available Jurisdictions

The jurisdiction option accepts any value supported by Cloudflare’s Durable Objects jurisdiction API, including:
  • "eu" - European Union
  • "fedramp" - FedRAMP compliant locations

​
Elicitation (Human-in-the-Loop)

MCP servers can request additional input from the user during a tool call using elicitation. This is useful for confirmation dialogs, requesting amounts, or any interactive tool flow. Elicitation is supported via McpAgent (which manages the request/response lifecycle through Durable Object storage) or via WorkerTransport (for stateful non-McpAgent setups). 
import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

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

  initialState = { counter: 0 };

  async init() {
    this.server.registerTool(
      "increase-counter",
      {
        description: "Increase the counter",
        inputSchema: {
          confirm: z.boolean().describe("Do you want to increase the counter?")
        }
      },
      async ({ confirm }, extra) => {
        if (!confirm) {
          return { content: [{ type: "text", text: "Cancelled." }] };
        }

        const result = await this.server.server.elicitInput(
          {
            message: "By how much?",
            requestedSchema: {
              type: "object",
              properties: {
                amount: { type: "number", title: "Amount" }
              },
              required: ["amount"]
            }
          },
          { relatedRequestId: extra.requestId }
        );

        if (result.action !== "accept" || !result.content?.amount) {
          return { content: [{ type: "text", text: "Cancelled." }] };
        }

        const amount = Number(result.content.amount);
        this.setState({ counter: this.state.counter + amount });

        return {
          content: [
            {
              type: "text",
              text: `Counter increased by ${amount}, now ${this.state.counter}`
            }
          ]
        };
      }
    );
  }
}

export default MyMCP.serve("/mcp");
See the examples/mcp-elicitation example for a full working demo.

​
WorkerTransport

WorkerTransport is a server-side transport for running MCP servers in stateless Workers while optionally persisting session state. It is used internally by createMcpHandler() but can also be used directly for advanced scenarios like stateful sessions without McpAgent. 
import { WorkerTransport, type TransportState } from "agents/mcp";

const transport = new WorkerTransport({
  sessionIdGenerator: () => crypto.randomUUID(),
  enableJsonResponse: false,
  storage: {
    get: () => kv.get<TransportState>("mcp_state"),
    set: (state: TransportState) => kv.put<TransportState>("mcp_state", state)
  }
});

​
Key Options

OptionDescription
sessionIdGeneratorFunction that returns a session ID for new sessions
enableJsonResponseReturn JSON instead of SSE streams (default: false)
storageOptional { get, set } adapter for persisting transport state across requests
corsOptionsCORS configuration

​
Next Steps

Connecting Clients

Connect your agent to external MCP servers

Transports

Learn about different MCP transport options

Securing Servers

Implement OAuth and security best practices

Examples

View example implementations on GitHub

Build docs developers (and LLMs) love

Get started for freeTalk to us