Build a Remote MCP server

This guide shows how to deploy a remote MCP server on Cloudflare using Streamable HTTP transport. You have two options:

• Without authentication — anyone can connect and use the server (no login required).
• With authentication and authorization — users sign in before accessing tools, and you can control which tools an agent can call based on the user's permissions.

The templates in this guide build the server with createMcpHandler from the Agents SDK. The handler is stateless: each request gets a fresh McpServer from a factory function, so the server needs no Durable Object or session. Keep data that must outlive a request in a binding such as KV, D1, or a Durable Object.

To move an existing McpAgent server, refer to Migrate to MCP SDK v2. The deprecated API is documented in the McpAgent reference.

You can start by deploying a public MCP server ↗︎ without authentication, then add user authentication and scoped authorization later. If you already know your server will require authentication, you can skip ahead to the next section.

The button below will guide you through everything you need to do to deploy an example MCP server ↗︎ to your Cloudflare account:

Once deployed, this server will be live at your workers.dev subdomain (for example, remote-mcp-server-authless.your-account.workers.dev/mcp). You can connect to it immediately using the AI Playground ↗︎ (a remote MCP client), MCP inspector ↗︎ or other MCP clients.

A new git repository will be set up on your GitHub or GitLab account for your MCP server, configured to automatically deploy to Cloudflare each time you push a change or merge a pull request to the main branch of the repository. You can clone this repository, develop locally, and start customizing the MCP server with your own tools.

You can use the Wrangler CLI to create a new MCP Server on your local machine and deploy it to Cloudflare.

1. Open a terminal and run the following command:

   npmyarnpnpm

   npm create cloudflare@latest -- remote-mcp-server-authless --template=cloudflare/ai/demos/remote-mcp-authless

   During setup, select the following options: - For Do you want to add an AGENTS.md file to help AI coding tools understand Cloudflare APIs?, choose No. - For Do you want to use git for version control?, choose No. - For Do you want to deploy your application?, choose No (we will be testing the server before deploying).

   Now, you have the MCP server setup, with dependencies installed.

2. Move into the project folder:

   cd remote-mcp-server-authless

3. In the directory of your new project, run the following command to start the development server:

   npm start

   ⎔ Starting local server...
   [wrangler:info] Ready on http://localhost:8788

   Check the command output for the local port. In this example, the MCP server runs on port 8788, and the MCP endpoint URL is http://localhost:8788/mcp.

4. To test the server locally:

   1. In a new terminal, run the MCP inspector ↗︎. The MCP inspector is an interactive MCP client that allows you to connect to your MCP server and invoke tools from a web browser.

      npx @modelcontextprotocol/inspector@latest

      🚀 MCP Inspector is up and running at:
      	http://localhost:5173/?MCP_PROXY_AUTH_TOKEN=46ab..cd3
      
      🌐 Opening browser...

      The MCP Inspector will launch in your web browser. You can also launch it manually by opening a browser and going to http://localhost:<PORT>. Check the command output for the local port where MCP Inspector is running. In this example, MCP Inspector is served on port 5173.

   2. In the MCP inspector, enter the URL of your MCP server (http://localhost:8788/mcp), and select Connect. Select List Tools to show the tools that your MCP server exposes.

5. You can now deploy your MCP server to Cloudflare. From your project directory, run:

   npx wrangler@latest deploy

   If you have already connected a git repository to the Worker with your MCP server, you can deploy your MCP server by pushing a change or merging a pull request to the main branch of the repository.

   The MCP server will be deployed to your *.workers.dev subdomain at https://remote-mcp-server-authless.your-account.workers.dev/mcp.

6. To test the remote MCP server, take the URL of your deployed MCP server (https://remote-mcp-server-authless.your-account.workers.dev/mcp) and enter it in the MCP inspector running on http://localhost:5173.

You now have a remote MCP server that MCP clients can connect to.

Connect an MCP client with Streamable HTTP support directly to your deployed endpoint. For example, add the server to Claude Code:

claude mcp add --transport http math https://remote-mcp-server-authless.your-account.workers.dev/mcp

Run claude mcp list to verify the connection. Then ask Claude to use one of your tools. For example:

Could you use the math tool to add 23 and 19?

Claude should invoke the tool and show the server response.

For other clients, refer to Test a Remote MCP Server.

The server you deployed accepts any client. To require users to sign in, put it behind an OAuth authorization server built with Workers OAuth Provider ↗︎:

1. Build an authorization server Worker with OAuthAuthorizationServer. Its /authorize page signs users in, directly or through GitHub, Google, Cloudflare Access, or another identity provider.
2. Wrap your MCP server's createMcpHandler in an OAuthResourceServer, which checks each request's token with the authorization server over a Service Binding.

MCP clients find the authorization server from your MCP server's 401 response, sign the user in, and retry with a token. Your tools read the signed-in user with getMcpAuthContext().

Refer to Authorization for both Workers in full.