Step 1

Create Your MCP Server

# Create new MCP server from template
npm create cloudflare@latest -- my-mcp-server --template=cloudflare/ai/demos/remote-mcp-authless

# Navigate to your project
cd my-mcp-server

# Install dependencies and start development server
npm install
npm run dev

⛅️ wrangler 4.64.0
───────────────────
Your Worker has access to the following bindings:
Binding                     Resource            Mode
env.MCP_OBJECT (MyMCP)      Durable Object      local
╭──────────────────────────────────────────────────────────────────────╮
│ [b] open a browser [d] open devtools [c] clear console [x] to exit │
╰──────────────────────────────────────────────────────────────────────╯
⎔ Starting local server…
[wrangler:info] Ready on http://localhost:8787

Step 2: Test with MCP Inspector

# In a new terminal window (keep your server running)
npx @modelcontextprotocol/inspector

Inspector Connection Process:

1. The inspector starts at http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=[your_token]
2. Open this URL in your browser (the inspector will do this automatically)
3. Make sure “Streamable HTTP” is the Transport Type
4. Enter http://localhost:8787/mcp as the URL
5. Click “Connect” to establish the connection
6. Make sure you’re on the “Tools” tab
7. Click “List Tools”
8. Click the “add” tool and run it with 2 numbers

You now have a functional MCP server that AI assistants can connect to and use!

Step 1: Add a Random Number Generator Tool

Add the following tool to your src/index.ts inside the init() method, after the existing tools:

// inside of async init() { ... }
this.server.tool(
  "generate_random_number",
  "Generates a random number between two numbers",
  { min: z.number(), max: z.number() },
  async ({ min, max }) => ({
    content: [
      {
        type: "text",
        text: String(Math.floor(Math.random() * (max - min + 1)) + min),
      },
    ],
  }),
);

Click the refresh button next to “Available Tools” in the MCP Inspector, and you should see the new “generate_random_number” tool. Try calling it!

Step 2: Test Your New Tool

Save the file. Your dev server picks up changes automatically. Head back to the MCP Inspector, click the refresh button next to “Available Tools” to reload, and you should see “generate_random_number” in the list. Test it with {"min": 1, "max": 100}.

Step 1: Enhance with the drand Randomness API

Replace your existing generate_random_number tool in src/index.ts with this enhanced version:

this.server.tool(
  "generate_random_number",
  "Generate a truly random number between two numbers",
  { min: z.number(), max: z.number() },
  async ({ min, max }) => {
    try {
      // Fetch true randomness from the drand beacon endpoint
      const response = await fetch(
        "https://drand.cloudflare.com/public/latest",
      );
      const data = (await response.json()) as {
        round: number;
        signature: string;
        previous_signature: string;
        randomness: string;
      };

      // Process randomness
      const randomHex = data.randomness;
      const startIndex = Math.floor(Math.random() * (randomHex.length - 8));
      const randomValue = parseInt(
        randomHex.slice(startIndex, startIndex + 8),
        16,
      );

      // Scale to requested range
      const scaledRandom = (Math.abs(randomValue) % (max - min + 1)) + min;

      return {
        content: [
          {
            type: "text",
            text: String(scaledRandom),
          },
        ],
      };
    } catch (error) {
      // Fallback to Math.random if API fails
      return {
        content: [
          {
            type: "text",
            text: String(Math.floor(Math.random() * (max - min + 1)) + min),
          },
        ],
      };
    }
  },
);

Step 2: Test the Enhanced Tool

Save the file and head back to the MCP Inspector. Click the refresh button next to “Available Tools” to reload, then test generate_random_number a few times with {"min": 1, "max": 100}. The results now come from the drand randomness beacon instead of Math.random().

Step 1: Deploy Your MCP Server

# Login to Cloudflare (if not already done)
$ npx wrangler login

# Deploy to Workers
$ npm run deploy

Once deployed (usually 30-60 seconds), copy the deployment URL from the output. Your MCP endpoint will be at https://my-mcp-server.[your-account].workers.dev/mcp.

Step 2: Test with AI Playground

Now for the fun part - connecting your deployed MCP server to an actual AI assistant.

🎮 AI Playground Testing:

1. Visit the AI Playground
2. Create a new chat session
3. Click the “Tools” button in the interface
4. Add your MCP server URL: https://your-worker.workers.dev/mcp (make sure to include /mcp)
5. Click “Connect” and verify tools are loaded
6. Test your tools by asking the AI to use them
7. Example: “Generate a random number between 1 and 100”

How cool is that? An LLM was able to call the tool you built, deployed globally on our edge network!

Step 1: Create and Configure KV Namespace

# Create a new KV namespace for our MCP server and choose the options below
npx wrangler kv namespace create "TODO_STORE"

 ⛅️ wrangler 4.64.0
───────────────────
Resource location: remote

🌀 Creating namespace with title "TODO_STORE"
✨ Success!
To access your new KV Namespace in your Worker, add the following snippet to your configuration file:
{
  "kv_namespaces": [
    {
      "binding": "TODO_STORE",
      "id": "abc1234567890defghij"
    }
  ]
}
✔ Would you like Wrangler to add it on your behalf? … yes
✔ What binding name would you like to use? … TODO_STORE
✔ For local dev, do you want to connect to the remote resource instead of a local resource? … no

Answer yes to let wrangler add the binding, use TODO_STORE as the binding name, and no for remote local dev.

Step 2: Add a Storage Tool

Add a simple store_value tool to verify KV is working. Make sure your MyMCP class has the <Env> generic so this.env works:

export class MyMCP extends McpAgent<Env> {
  server = new McpServer({
    name: "My MCP Server",
    version: "1.0.0",
  });

  async init() {
    this.server.tool(
        "store_value",
        "Store a simple key-value pair in Cloudflare KV",
        {
            key: z.string().describe("Key to store the value under"),
            value: z.string().describe("Value to store")
        },
        async ({ key, value }) => {
            try {
                await this.env.TODO_STORE.put(key, value);

                return {
                    content: [{
                        type: "text",
                        text: "Value stored successfully"
                    }]
                };
            } catch (error: any) {
                throw new Error(`Failed to store value: ${error}`);
            }
        }
    );

Save the file, click the refresh button next to “Available Tools” in the MCP Inspector, and test with {"key": "test", "value": "hello world"}.

Step 1: Add Todo Management Tools

this.server.tool(
  "add_new_todo",
  "Add a new task to your todo list",
  { task: z.string().describe("Task description") },
  async ({ task }) => {
    await this.env.TODO_STORE.put(
      `${task}`,
      JSON.stringify({
        completed: false,
        createdAt: new Date().toISOString(),
      }),
    );
    return { content: [{ type: "text", text: `Added task: ${task}` }] };
  },
);

this.server.tool(
  "list_all_todos",
  "List all tasks in your todo list",
  {},
  async () => {
    const list = await this.env.TODO_STORE.list();
    const tasks = [];

    for (const key of list.keys) {
      const value = await this.env.TODO_STORE.get(key.name);
      if (value) {
        let taskData;
        try {
          taskData = JSON.parse(value);
        } catch (e) {
          continue;
        }
        tasks.push(`${taskData.completed ? "✅" : "📋"} ${key.name}`);
      }
    }

    if (tasks.length === 0) {
      return {
        content: [
          { type: "text", text: "No tasks found. Add some tasks first!" },
        ],
      };
    }

    return {
      content: [
        {
          type: "text",
          text: `Todo List:\n${tasks.join("\n")}`,
        },
      ],
    };
  },
);

this.server.tool(
  "complete_todo",
  "Mark a task as completed",
  { task: z.string().describe("Task to mark as completed") },
  async ({ task }) => {
    const value = await this.env.TODO_STORE.get(task);
    if (!value) {
      return { content: [{ type: "text", text: `Task "${task}" not found` }] };
    }

    let taskData;
    try {
      taskData = JSON.parse(value);
    } catch (e) {
      return { content: [{ type: "text", text: `Invalid task ${task}` }] };
    }

    taskData.completed = true;

    await this.env.TODO_STORE.put(task, JSON.stringify(taskData));
    return { content: [{ type: "text", text: `Completed task: ${task}` }] };
  },
);

Step 2: Deploy and Test

Deploy your updated server with npm run deploy, then head to the AI Playground and connect with your deployment URL. If you were already connected, click the refresh button next to “Available Tools” to pick up the new tools.

Try a natural conversation:

1. “Add a task to buy groceries”
2. “Show me my todo list”
3. “Mark ‘buy groceries’ as completed”
4. Refresh the page and list tasks again - they persist!

Here is a chat transcript with the qwen3-30b-a3b-fp8 model on the AI Playground and the MCP server we just created.

What You Built

Over the last six steps you went from zero to a fully deployed MCP server with persistent storage and a real application on top of it.

That is the full stack of MCP development: tool creation, validation, external data, persistence, deployment, and a working app. Everything else is a variation on what you already know.

The Universal MCP Pattern

Every MCP tool you will ever build follows the same four-part structure:

server.tool(
  "tool_name", // What it's called
  "What this tool does", // How the AI understands it
  { param: z.string() }, // Zod schema for validation
  async ({ param }) => {
    // Your logic
    // Do the work
    return { content: [{ type: "text", text: "result" }] };
  },
);

You used this exact pattern in Steps 2, 3, 5, and 6. The only things that change between tools are the name, description, schema, and handler logic. The shape is always the same.

Go Build Your Next Tool

You already have every skill required. Here are some ideas, mapped to what you learned:

These are just starting points. The best tool is one that solves a problem you actually have. Come up with your own idea, build it, and deploy it. Your MCP server is already live, so just add a new server.tool() call and run npm run deploy.

Use AI to Accelerate

AI coding assistants are great at generating MCP tools once you give them the right context. Use this prompt as a starting point:

The key is giving the AI your actual code as context. It will follow the patterns you already have in place.

Ship It

Deploy your updated server one more time:

npm run deploy

Your MCP server is live on our global network. Any AI assistant that supports MCP can connect to it using your Workers URL.

Keep Going

• MCP Specification - The protocol standard and full documentation
• Cloudflare Workers docs - Everything Workers can do beyond what we covered
• Cloudflare AI docs - Run AI models directly in your tools
• MCP servers on GitHub - Open source MCP servers to learn from and contribute to
• Cloudflare Discord - Community support and discussion