Cloudflare Workers:

Cloudflare Workers is a serverless, globally distributed execution environment that allows developers to run their code on Cloudflare's edge network, allowing for faster response times and improved performance. Cloudflare Workers support running JavaScript, TypeScript, or WASM code close to your users, without managing or scaling servers.

Deploying MCP servers on Cloudflare Workers gives you ultra-low-latency, global access to context data right at the edge. It simplifies security and operations by leveraging built-in features like rate limiting, auth, and seamless integration with other Cloudflare services. Plus, it’s cost-effective and scales automatically with minimal overhead.

In this guide, we’ll cover step-by-step instructions on how to tackle this, so you’ll be deploying MCP servers to Cloudflare Workers in no time.

Before You Start: Verify Node.js Compatibility

Cloudflare workers run on a lightweight, V8-based runtime environment, rather than a full Node.js runtime. As a result, barebones Workers cannot directly execute Node.js APIs. Cloudflare instead provides support for a subset of Node.js APIs that allow you to use several Node.js libraries within workers. For a list of supported Node.js APIs, refer to https://developers.cloudflare.com/workers/runtime-apis/nodejs/.

Deploying a MCP Server to Workers

This guide provides steps to deploy Javascript & Typescript based MCP Servers built using @modelcontextprotocol/sdk on Cloudflare Workers.

1. Install Wrangler CLI:

Wrangler is Cloudflare’s CLI tool for developing & deploying onto Cloudflare Workers.

npm i wrangler --save-dev

2. Install Cloudflare’s Agent SDK:

Cloudflare’s Agent SDK is a package that allows you to run AI Agents and MCP servers on Cloudflare Workers.

npm install agents

3. Write a Worker’s Script:

Cloudflare Worker requires a script that acts as the entry point to the MCP Server. The worker’s script is characterized by 2 parts:

1. A class that extends the MCPAgent class from the Agents SDK

2. An ESModule that handles the incoming requests to the Worker

Below is an example worker’s script that enables us to serve the MCP Server. Place the worker script wherever it is most appropriate in your project structure.

import { MCPAgent } from "agents/mcp";
import { server } from "src/index.js";  // Import the MCP server instance from its implementation file
export class MyMCP extends MCPAgent {
  // Create OR Assign your MCP Server instance here
  server = server;
  async init() {
  // Perform server initialization here, such as registering tools, resources, etc
  // if these steps are not handled for the server instance above
  }
}
export default {
  async fetch(
    req: Request, 
    env: Env, 
    ctx: ExecutionContext
  ): Promise<Response> {
    const url = new URL(req.url);
    if (url.pathname === '/sse' || url.pathname === '/sse/message') {
      // Handles server-sent message (SSE) transport messages
      return await MyMCP.serveSSE('/sse').fetch(req, env, ctx);
    }
    else if (url.pathname === '/mcp') {
      // Handles streamable HTTP transport messages
      return await MyMCP.serve('/mcp').fetch(req, env, ctx);
    }
  }
}

4. Create the wrangler config file:

In your project root folder, create a file called wrangler.jsonc, which includes the information required for deploying & running the MCP Server on Cloudflare Workers.

{
  "$schema": "node_modules/wrangler/config-schema.json"
  "name": "<Name of cloudflare worker>",
  "main": "<Path to the worker script in your directory>",
  # Optional build step performed prior to deploying the worker
  "build":
  {
    "command": "<Command used to build the worker>",
    "cwd": "<Directory where the build command is executed>",
    "watch": "<Directory to look for changes while running the worker locally>"
  }
  "compatibility_date": "<Date of deployment in yyyy-mm-dd format>",
  "compatibility_flag": [
    # required if MCP server uses node.js libraries
    "nodejs_compat",
    # required if MCP server uses `process.env` for environment variables
    "nodejs_compat_populate_process_env"
  ],
  "durable_objects": {
    "bindings": [
      {
        "name": "MCP_OBJECT",
        "class_name": "MyMCP"
      }
    ]
  },
  "migrations": [
    {
      "new_sqlite_classes": ["MyMCP"],
      "tags": "<tag name>"
    }
  ]
  # Define environment variables here
  "vars":
  {
    "<environment variable name-1>": "<value>",
    "<environment variable name-2>": "<value>"
  }
}

Refer to Cloudflare Docs for Wrangler Configuration for more details.

After making the changes to the config file, run the following command. This will generate & inject the Cloudflarecloudflare types required to run the Worker.

npx wrangler types

Note: Ensure that you run npx wrangler types each time you modify the wrangler config file so that the Cloudflare types are accessible in your project.

Secrets as Environment Variables:

The environment variables defined as part of the wrangler config file are processed as-is and are stored as plain text, which is a significant security risk. Instead, Cloudflare offers the following options to provide secrets as environment variables to the workers:

For Locally Hosted Workers:

1. Create .dev.vars file in the root directory

2. List each sensitive field per line in the format shown below

<Key>="<Value>"
<Key>="<Value>

For Deployed Workers:

Execute the following command as shown below in the command line. Enter the secret’s value when prompted. This will add the secret as an environment variable to the deployed worker. Cloudflare will treat it as a sensitive field & store it securely.

npx wrangler secret put <secret name

5. Test Cloudflare Worker locally:

Wrangler provides the feature to run your Cloudflare worker locally to test out before deploying. The following command starts the worker locally:

npx wrangler dev

The output will display the local URL where your Worker is being served.

Additionally, you can test the connection to MCP Server using the MCP Inspector tool. It is a visual tool for testing & debugging MCP Servers. Execute the following commands to install & run the tool.

npm i @modelcontextprotocol/inspector
npx @modelcontextprotocol/inspector

Open a browser and navigate to the domain where the MCP Inspector tool is hosted. Select the transport type of your MCP Server you want to connect to, and enter the domain where the MCP Server is hosted. Clicking "Connect" will allow you to perform queries against your locally hosted MCP Server.

6. Deploy onto Cloudflare Workers

Once you are confident that the Cloudflare Worker is running and the MCP Server is accessible via MCP Inspector, we can deploy the worker onto Cloudflare’s network using the following command.

npx wrangler deploy

After deployment, make a note of the URL where your Worker is hosted, as displayed in the output.

7. Configuration for AI Client

Finally, paste the below config in your favourite AI Client such as Claude desktop, Cursor, etc.

For SSE transport

{
  "mcpServers": {
    "<name of MCP Server>": {
      "command": "npx",
      "args": ["mcp-remote", "<Your Cloudflare Domain>/sse"]
    }
  }
}

For Streamable HTTP transport

{
  "mcpServers": {
    "<name of MCP Server>": {
      "command": "npx",
      "args": ["mcp-remote", "<Your Cloudflare Domain>/mcp"]
    }
  }
}

8. What’s Next:

Authentication & Authorization for the deployed MCP Servers: https://developers.cloudflare.com/agents/guides/remote-mcp-server/#add-authentication