Skip to content
Cloudflare Docs

Getting Started

You can build both local and remote Model Context Protocol (MCP) ↗ servers on Cloudflare.

Local MCP servers rely on running a local proxy on the same machine as your application. Remote MCP servers run on Cloudflare and support remote, authenticated connections over the Internet.

This guide will teach you how to build and deploy your first remote MCP server to Cloudflare. If you want to build a local MCP server, see the build a local MCP server guide instead.

What is the Model Context Protocol (MCP)?

Model Context Protocol (MCP) ↗ is an open standard that connects AI systems with external applications. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various accessories, MCP provides a standardized way to connect AI agents to different services.

MCP Terminology

  • MCP Hosts: AI assistants (like Claude ↗ or Cursor ↗), AI agents, or applications that need to access external capabilities.
  • MCP Clients: Clients embedded within the MCP hosts that connect to MCP servers and invoke tools. Each MCP client instance has a single connection to an MCP server.
  • MCP Servers: Applications that expose tools, prompts ↗, and resources ↗ that MCP clients can use.

Remote vs. local MCP connections

The MCP standard supports two modes of operation:

Deploy your first MCP server

This guide will walk you through how to deploy an example MCP server ↗ to your Cloudflare account. You will then customize this example to suit your needs.

The link below will guide you through everything you need to do to deploy this example MCP server ↗ to your Cloudflare account:

Deploy to Workers ↗

At the end of this process, you will have a new git repository on your GitHub or GitLab account for your MCP server, configured to automatically deploy Cloudflare each time you push a change or merge a pull request to the main branch of the repository. You can then clone this repository, develop locally, and start writing code and building.

Alternatively, you can use the command line as shown below to create a new MCP Server on your local machine.

Terminal window
npm create cloudflare@latest -- my-mcp-server --template=cloudflare/ai/demos/remote-mcp-server

Now, you have the MCP server setup, with dependencies installed. Move into that project folder:

Terminal window
cd my-mcp-server

Local development

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

Terminal window
npm start

Your MCP server is now running on http://localhost:8787/sse.

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.

Terminal window
npx @modelcontextprotocol/inspector@latest

Open the MCP inspector in your web browser:

Terminal window
open http://localhost:5173

In the inspector, enter the URL of your MCP server, http://localhost:8787/sse, and click Connect:

MCP inspector — where to enter the URL of your MCP server

You will be redirected to an example OAuth login page. Enter any username and password and click "Log in and approve" to continue. (you can add your own authentication and/or authorization provider to replace this. Refer to the authorization section for details on how to do this.)

MCP OAuth Login Page

Once you have logged in, you will be redirected back to the inspector. You should see the "List Tools" button, which will list the tools that your MCP server exposes.

MCP inspector — authenticated

Deploy your MCP server

You can deploy your MCP server to Cloudflare using the following Wrangler CLI command within the example project:

Terminal window
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.

After deploying, take the URL of your deployed MCP server, and enter it in the MCP inspector running on http://localhost:5173. You now have a remote MCP server, deployed to Cloudflare, that MCP clients can connect to.

Connect your MCP server to Claude and other MCP Clients

Now that your MCP server is running with OAuth authentication, you can connect Claude Desktop or other MCP clients to it. This lets you to test what an interaction with your OAuth-enabled MCP server will be like with a real MCP client.

Connect to your MCP server running locally

Follow these steps to connect Claude Desktop to the MCP server running on your local machine:

  1. Open Claude Desktop and navigate to Settings -> Developer -> Edit Config. This opens the configuration file that controls which MCP servers Claude can access.
  2. Replace the content with this configuration:
{
  "mcpServers": {
    "math": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8787/sse"
      ]
    }
  }
}

This tells Claude to communicate with your MCP server running at http://localhost:8787/sse, with the mcp-remote tool handling the authentication between Claude and your server.

  1. Save the file and restart Claude Desktop (command/ctrl + R). When Claude restarts, a browser window will open showing your OAuth login page. Complete the authentication flow to grant Claude access to your MCP server.

Once authenticated, you'll be able to see your tools by clicking the tools icon in the bottom right corner of Claude's interface.

Test the integration

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 result generated by the MCP server.

Connect to your deployed MCP server

After you've deployed your MCP server to Cloudflare, update your Claude Desktop configuration to point to the deployed URL:

{
  "mcpServers": {
    "math": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-worker-name.your-account.workers.dev/sse"
      ]
    }
  }
}

Restart Claude Desktop and complete the authentication flow again. Once this is done, Claude will be able to make calls to your remote MCP server.

Connecting with other MCP Clients

To connect Cursor with your MCP server, choose Type: "Command" and in the Command field, combine the command and args fields into one (e.g.npx mcp-remote https://your-worker-name.your-account.workers.dev/sse).

You can connect your MCP server to other MCP clients like Windsurf by opening the client's configuration file, adding the same JSON that was used for the Claude setup, and restarting the MCP client.

Add Authentication

The example MCP server you just deployed above acts as an OAuth provider to MCP clients, handling authorization, but has a placeholder authentication flow. It lets you enter any username and password to log in, and doesn't actually authenticate you against any user database.

In the next section, you will add a real authentication provider to your MCP server. Even if you already have an authentication provider in place, following these steps will show you more clearly how to integrate it with your MCP server.

We'll use GitHub as the authentication provider here, but you can use any OAuth provider that supports the OAuth 2.0 specification, including Google, Slack, Stytch, Auth0, and more.

Step 1 — Create and deploy a new MCP server

Run the following command to create a new MCP server:

Terminal window
npm create cloudflare@latest -- my-mcp-server-github-auth --template=cloudflare/ai/demos/remote-mcp-server-github

Now, you have the MCP server setup, with dependencies installed. Move into that project folder:

Terminal window
cd my-mcp-server-github-auth

Then, run the following command to deploy the MCP server:

Terminal window
npx wrangler@latest deploy

You'll notice that in the example MCP server, if you open src/index.ts, the primary difference is that the defaultHandler is set to the GitHubHandler:

import GitHubHandler from "./github-handler";


export default new OAuthProvider({
  apiRoute: "/sse",
  apiHandler: MyMCP.Router,
  defaultHandler: GitHubHandler,
  authorizeEndpoint: "/authorize",
  tokenEndpoint: "/token",
  clientRegistrationEndpoint: "/register",
});

This will ensure that your users are redirected to GitHub to authenticate. To get this working though, you need to create OAuth client apps in the steps below.

Step 2 — Create an OAuth App

You'll need to create two GitHub OAuth Apps ↗ to use GitHub as an authentication provider for your MCP server — one for local development, and one for production.

First create a new OAuth App for local development

Navigate to github.com/settings/developers ↗ to create a new OAuth App with the following settings:

  • Application name: My MCP Server (local)
  • Homepage URL: http://localhost:8787
  • Authorization callback URL: http://localhost:8787/callback

For the OAuth app you just created, add the client ID of the OAuth app as GITHUB_CLIENT_ID and generate a client secret, adding it as GITHUB_CLIENT_SECRET to a .dev.vars file in the root of your project, which will be used to set secrets in local development.

Terminal window
touch .dev.vars
echo 'GITHUB_CLIENT_ID="your-client-id"' >> .dev.vars
echo 'GITHUB_CLIENT_SECRET="your-client-secret"' >> .dev.vars
cat .dev.vars

Next, run your MCP server locally

Run the following command to start the development server:

Terminal window
npm start

Your MCP server is now running on http://localhost:8787/sse.

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.

Terminal window
npx @modelcontextprotocol/inspector@latest

Open the MCP inspector in your web browser:

Terminal window
open http://localhost:5173

In the inspector, enter the URL of your MCP server, http://localhost:8787/sse, and click Connect:

You should be redirected to a GitHub login or authorization page. After authorizing the MCP Client (the inspector) access to your GitHub account, you will be redirected back to the inspector. You should see the "List Tools" button, which will list the tools that your MCP server exposes.

Second — create a new OAuth App for production

You'll need to repeat these steps to create a new OAuth App for production.

Navigate to github.com/settings/developers ↗ to create a new OAuth App with the following settings:

  • Application name: My MCP Server (production)
  • Homepage URL: Enter the workers.dev URL of your deployed MCP server (ex: worker-name.account-name.workers.dev)
  • Authorization callback URL: Enter the /callback path of the workers.dev URL of your deployed MCP server (ex: worker-name.account-name.workers.dev/callback)

For the OAuth app you just created, add the client ID and client secret, using Wrangler CLI:

Terminal window
wrangler secret put GITHUB_CLIENT_ID
Terminal window
wrangler secret put GITHUB_CLIENT_SECRET

Finally, connect to your MCP server

Now that you've added the ID and secret of your production OAuth app, you should now be able to connect to your MCP server running at worker-name.account-name.workers.dev/sse using the MCP inspector or (other MCP clients), and authenticate with GitHub.

Next steps