Skip to content

Commit 1195e85

Browse files
dinasaur404dinasaur404
committed
Add MCP server documentation
1 parent 84bd614 commit 1195e85

File tree

1 file changed

+164
-0
lines changed

1 file changed

+164
-0
lines changed

‎src/content/docs/agents/examples/build-mcp-server.mdx‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
---
2+
pcx_content_type: tutorial
3+
title: Build an MCP Server
4+
sidebar:
5+
order: 100
6+
group:
7+
hideIndex: true
8+
description: Build and deploy an MCP server on Cloudflare Workers
9+
---
10+
11+
import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";
12+
import { Aside } from '@astrojs/starlight/components';
13+
14+
[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open standard that allows AI assistants & LLMs to interact with services directly. If you want users to access your service or product straight from their AI assistant, you can enable this by spinning up an MCP server for your application.
15+
16+
## Building an MCP Server on Cloudflare Workers
17+
18+
Normally, setting up an MCP server requires writing boilerplate code to handle routing, define types, and standing up a server that implements the MCP protocol. But with [Cloudflare Workers](/workers/), all the heavy lifting is done for you, so all you need to do is define your service's functionality as TypeScript methods on your Worker
19+
Once deployed, your Worker becomes an MCP server that AI assistants (as long as they support MCP) can connect to and use to interact with your service.
20+
21+
<Aside type="caution">
22+
Remote MCP servers are not supported yet. The workers-mcp tooling creates a local proxy that forwards requests to your Worker, allowing the server to be used by an MCP client.
23+
</Aside>
24+
25+
## Benefits
26+
27+
- **Minimal setup & built-in boilerplate:** The Worker automatically handles API routing, server management, and MCP protocol compliance. The [workers-mcp](https://www.npmjs.com/package/workers-mcp) package bootstraps your MCP server, allowing you to focus on your service logic.
28+
- **Automatic documentation:** Public methods annotated with JSDoc are automatically documented and exposed as MCP tools. This means AI assistants can quickly understand how to interact with your service, making tool discovery and integration much easier.
29+
- **Scalability & performance:** Deploy your MCP server on Cloudflare's global edge network so that users can make fast, performant requests from their LLMs. Cloudflare will handle traffic spikes and high load, ensuring your service remains available and responsive.
30+
- **Expand MCP server capabilities:** Easily connect to Workers AI, D1, Durable Objects, and other Cloudflare services to add more functionality to your MCP Server.
31+
32+
## Get Started
33+
34+
Follow these steps to create and deploy your own MCP server on Cloudflare Workers.
35+
36+
37+
### Create a new Worker
38+
39+
If you haven't already, install [Wrangler](https://developers.cloudflare.com/workers/wrangler/) and log in:
40+
41+
```bash
42+
npm install wrangler
43+
wrangler login
44+
```
45+
46+
Initialize a new project:
47+
```bash
48+
npx create-cloudflare@latest my-mcp-worker
49+
cd my-mcp-worker
50+
```
51+
52+
### Install the MCP tooling
53+
Inside your project directory, install the [workers-mcp](https://github.com/cloudflare/workers-mcp) package:
54+
55+
```bash
56+
npm install workers-mcp
57+
```
58+
59+
This package provides the tools needed to run your Worker as an MCP server.
60+
61+
### Configure your Worker to support MCP
62+
Run the following setup command:
63+
64+
```bash
65+
npx workers-mcp setup
66+
```
67+
68+
This guided installation process takes a brand new or existing Workers project and adds the required tooling to turn it into an MCP server:
69+
- Automatic documentation generation
70+
- Shared-secret security using Wrangler Secrets
71+
- Installs a local proxy so you can access it from your MCP desktop clients (like Claude Desktop)
72+
73+
### Set up the MCP Server
74+
Replace the contents of your src/index.ts with the following boilerplate code:
75+
76+
```ts
77+
import { WorkerEntrypoint } from 'cloudflare:workers';
78+
import { ProxyToSelf } from 'workers-mcp';
79+
80+
export default class MyWorker extends WorkerEntrypoint<Env> {
81+
/**
82+
* A warm, friendly greeting from your new MCP server.
83+
* @param name {string} The name of the person to greet.
84+
* @return {string} The greeting message.
85+
*/
86+
sayHello(name: string) {
87+
return `Hello from an MCP Worker, ${name}!`;
88+
}
89+
90+
/**
91+
* @ignore
92+
*/
93+
async fetch(request: Request): Promise<Response> {
94+
// ProxyToSelf handles MCP protocol compliance.
95+
return new ProxyToSelf(this).fetch(request);
96+
}
97+
}
98+
```
99+
100+
This converts your Cloudflare Worker into an MCP server, enabling interactions with AI assistants. The key components are:
101+
- **WorkerEntrypoint:** The WorkerEntrypoint class handles all incoming request management and routing. This provides the structure needed to expose MCP tools within the Worker.
102+
- **Tool Definition:** Methods, for example, sayHello, are annotated with JSDoc, which automatically registers the method as an MCP tool. AI assistants can call this method dynamically, passing a name and receiving a greeting in response. Additional tools can be defined using the same pattern.
103+
- **ProxyToSelf:** MCP servers must follow a specific request/response format. ProxyToSelf ensures that incoming requests are properly routed to the correct MCP tools. Without this, you would need to manually parse requests and validate responses.
104+
105+
106+
**Note:** Every public method that is annotated with JSDoc becomes an MCP tool that is discoverable by AI assistants.
107+
108+
109+
### Deploy the MCP server
110+
Update your wrangler.toml with the appropriate configuration then deploy your Worker:
111+
```bash
112+
wrangler deploy
113+
```
114+
115+
Your MCP server is now deployed globally and all your public class methods are exposed as MCP tools that AI assistants can now interact with.
116+
117+
#### Updating your MCP server
118+
When you make changes to your MCP server, run the following command to update it:
119+
```bash
120+
npm run deploy
121+
```
122+
**Note:** If you change method names, parameters, or add/remove methods, Claude and other MCP clients will not see these updates until you restart them. This is because MCP clients cache the tool metadata for performance reasons.
123+
### Connecting MCP clients to your server
124+
The workers-mcp setup command automatically configures Claude Desktop to work with your MCP server. To use your MCP server through other [MCP clients](https://modelcontextprotocol.io/clients), you'll need to configure them manually.
125+
126+
#### Cursor
127+
To get your Cloudflare MCP server working in Cursor, you need to combine the 'command' and 'args' from your config file into a single string and use type 'command'.
128+
129+
In Cursor, create an MCP server entry with:
130+
131+
type: command
132+
command: /path/to/workers-mcp run your-mcp-server-name https://your-server-url.workers.dev /path/to/your/project
133+
134+
For example, using the same configuration as above, your Cursor command would be:
135+
```
136+
/Users/username/path/to/my-new-worker/node_modules/.bin/workers-mcp run my-new-worker https://my-new-worker.username.workers.dev /Users/username/path/to/my-new-worker
137+
```
138+
139+
#### Other MCP clients
140+
For Windsurf and other MCP clients, update your configuration file to include your worker using the same format as Claude Desktop:
141+
```json
142+
{
143+
"mcpServers": {
144+
"your-mcp-server-name": {
145+
"command": "/path/to/workers-mcp",
146+
"args": [
147+
"run",
148+
"your-mcp-server-name",
149+
"https://your-server-url.workers.dev",
150+
"/path/to/your/project"
151+
],
152+
"env": {}
153+
}
154+
}
155+
}
156+
```
157+
Make sure to replace the placeholders with your actual server name, URL, and project path.
158+
### Coming soon
159+
The Model Context Protocol spec is [actively evolving](https://github.com/modelcontextprotocol/specification/discussions) and we're working on expanding Cloudflare's MCP support. Here's what we're working on:
160+
161+
- **Remote MCP support**: Connect to MCP servers directly without requiring a local proxy
162+
- **Authentication**: OAuth support for secure MCP server connections
163+
- **Real-time communication**: SSE (Server-Sent Events) and WebSocket support for persistent connections and stateful interactions between clients and servers
164+
- **Extended capabilities**: Native support for more MCP protocol capabilities like [resources](https://modelcontextprotocol.io/docs/concepts/resources), [prompts](https://modelcontextprotocol.io/docs/concepts/prompts) and [sampling](https://modelcontextprotocol.io/docs/concepts/sampling)

0 commit comments

Comments
 (0)