Build a Remote MCP server

Last updated Oct 22, 2026 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.

Choosing an approach

The Agents SDK provides multiple ways to create MCP servers. Choose the approach that fits your use case:

Use createMcpHandler for a new stateless server. An existing McpAgent without legacy stateful dependencies can migrate directly. If it uses MCP session state, RPC, pushed requests, streams, or replay, plan the stateless equivalents and serve stateless and legacy lanes during the transition. Refer to Migrate to MCP SDK v2 for the staged rollout.

Deploy your first MCP server

Template protocol path

The quick-deploy templates in this section still use the deprecated McpAgent path. Do not use that path for a new server. Start with the mcp-worker example ↗︎. If an existing template deployment needs sessionful behavior, add a stateless route and follow the migration guide.

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.

Via the dashboard

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.

Via the CLI

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
   ```

yarn create cloudflare remote-mcp-server-authless --template=cloudflare/ai/demos/remote-mcp-authless ```

   pnpm 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:

```sh
   cd remote-mcp-server-authless
   ```

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

```sh
   npm start
   ```

```sh
   ⎔ 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`.

Note

You cannot interact with the MCP server by opening the `/mcp` URL directly in a web browser. The `/mcp` endpoint expects an MCP client to send MCP protocol messages, which a browser does not do by default. In the next step, we will demonstrate how to connect to the server using an MCP client.
4. To test the server locally:
   1. In a new terminal, run the [MCP inspector ↗︎](https://github.com/modelcontextprotocol/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.

```sh
      npx @modelcontextprotocol/inspector@latest
      ```

```sh
      🚀 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:

```sh
   npx wrangler@latest deploy
   ```

If you have already [connected a git repository](https://developers.cloudflare.com/workers/ci-cd/builds/) 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 from an MCP client

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

```sh
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.

Add Authentication

The public MCP server example you deployed earlier allows any client to connect and invoke tools without logging in. To add user authentication to your MCP server, you can integrate Cloudflare Access or a third-party service as the OAuth provider. Your MCP server handles secure login flows and issues access tokens that MCP clients can use to make authenticated tool calls. Users sign in with the OAuth provider and grant their AI agent permission to interact with the tools exposed by your MCP server, using scoped permissions.

Cloudflare Access OAuth

You can configure your MCP server to require user authentication through Cloudflare Access. Cloudflare Access acts as an identity aggregator and verifies user emails, signals from your existing identity providers (such as GitHub or Google), and other attributes such as IP address or device certificates. When users connect to the MCP server, they will be prompted to log in to the configured identity provider and are only granted access if they pass your Access policies.