Creating MCP Servers

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

Choosing an Approach

Approach	Stateful?	Requires Durable Objects?	Best for
`createMcpHandler()`	No	No	Stateless tools, simplest setup
`McpAgent`	Yes	Yes	Stateful tools, per-session state, elicitation
Raw `WebStandardStreamableHTTPServerTransport`	No	No	Full 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);
  }
};

Important: 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'll normally setup all your tools/resources and anything else you might need. In this case, we're 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's 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's 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. I'll try with https://playground.ai.cloudflare.com:

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, please do not use this in production)

import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import {
  OAuthProvider,
  type OAuthHelpers
} from "@cloudflare/workers-oauth-provider";
import { z } from "zod";
import { env } from "cloudflare:workers";

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

  async init() {
    // Helper to return text responses from our tools
    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}`);
      }
    );
  }
}

// HTML form page for users to write our password
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" } }
  );
}

// This is the default handler of our worker BEFORE requests are authenticated.
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);

    // Only handle our auth UI/flow here
    if (url.pathname !== "/authorize") {
      return new Response("NOT FOUND", { status: 404 });
    }

    // Parse the OAuth request
    const oauthReq = await provider.parseAuthRequest(request);

    // We render the password page for GET requests
    if (request.method === "GET") {
      return passwordPage({ query: url.searchParams.toString() });
    }

    // We validate the password in POST requests
    if (request.method === "POST") {
      const form = await request.formData();
      const password = String(form.get("password") || "");

      const SHARED_PASSWORD = env.SHARED_PASSWORD; // Store this as a secret
      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."
        });
      }

      // We give everyone the same userId
      const userId = "friend";

      const { redirectTo } = await provider.completeAuthorization({
        request: oauthReq,
        userId,
        scope: [], // We don't care about scopes

        // We could add anything we wanted here so we could access it
        // within the MCP with `this.props`
        props: { userId },
        metadata: undefined
      });

      return Response.redirect(redirectTo, 302);
    }

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

// OAuthProvider creates our worker handler
export default new OAuthProvider({
  authorizeEndpoint: "/authorize",
  tokenEndpoint: "/token",
  clientRegistrationEndpoint: "/register",
  apiHandlers: { "/mcp": StorageMcp.serve("/mcp") },
  defaultHandler
});

You would also add these to your wrangler.jsonc:

{
  // rest of your config...
  "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "your-bucket-name" }],
  "kv_namespaces": [
    {
      "binding": "OAUTH_KV", // required by OAuthProvider
      "id": "your-kv-id"
    }
  ]
}

What's going on?

In ~160 lines we were able to write our custom OAuth authorization flow so anyone that knows our secret password can use the MCP server.

Just like before, in init() we set a few tools to access files in our R2 bucket. We also have the whoami tool to show users what userId we authenticated them with. It's just an example of how to access props from within the McpAgent.

Most of the code here is either the HTML page to type in the password or the OAuth /authorize logic. The important part is to notice how in the OAuthProvider we expose the StorageMcp through the apiHandlers key and use the same serve method we were using before.

Let's see how this looks like

Once again, using https://playground.ai.cloudflare.com: The auth flow prompts us for the password.

Once we've authenticated ourselves we can use all the tools!

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. By setting the jurisdiction option, you can ensure that your Durable Object instances (and their data) are created in a specific geographic region.

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:

Option	Description
`sessionIdGenerator`	Function that returns a session ID for new sessions
`enableJsonResponse`	Return JSON instead of SSE streams (default: `false`)
`storage`	Optional `{ get, set }` adapter for persisting transport state across requests
`corsOptions`	CORS configuration

For more complex examples including authentication with third-party providers, see the examples directory.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Creating MCP Servers

Choosing an Approach

Stateless MCP Server with `createMcpHandler()`

`createMcpHandler` Options

Accessing Authenticated User Context

Stateful MCP Server with `McpAgent`

Writing TinyMCP

What is going on here?

Putting it to the test

Password-protected StorageMcp with OAuth!

What's going on?

Let's see how this looks like

Data Jurisdiction for Compliance

Using the EU Jurisdiction for GDPR

Available Jurisdictions

Elicitation (Human-in-the-Loop)

WorkerTransport

Read more

FilesExpand file tree

mcp-servers.md

Latest commit

History

mcp-servers.md

File metadata and controls

Creating MCP Servers

Choosing an Approach

Stateless MCP Server with createMcpHandler()

createMcpHandler Options

Accessing Authenticated User Context

Stateful MCP Server with McpAgent

Writing TinyMCP

What is going on here?

Putting it to the test

Password-protected StorageMcp with OAuth!

What's going on?

Let's see how this looks like

Data Jurisdiction for Compliance

Using the EU Jurisdiction for GDPR

Available Jurisdictions

Elicitation (Human-in-the-Loop)

WorkerTransport

Read more

Stateless MCP Server with `createMcpHandler()`

`createMcpHandler` Options

Stateful MCP Server with `McpAgent`