Skip to content

Commit 35f9413

Browse files
deloreyjdeloreyj
authored
Merge pull request #46 from cloudflare/workers-bindings-mcp
Workers bindings mcp
2 parents 4c7ef2f + 3f24617 commit 35f9413

28 files changed

+13130
-652
lines changed

‎apps/sandbox-container/package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@
1010
"build": "docker build .",
1111
"start": "wrangler dev",
1212
"start:container": "tsx container/index.ts",
13-
"postinstall": "mkdir -p workdir"
13+
"postinstall": "mkdir -p workdir",
14+
"types": "wrangler types"
1415
},
1516
"dependencies": {
1617
"@cloudflare/workers-oauth-provider": "0.0.2",

‎apps/sandbox-container/server/index.ts‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,16 @@
11
import OAuthProvider from '@cloudflare/workers-oauth-provider'
2+
import { env } from 'cloudflare:workers'
23

34
import {
4-
AccountSchema,
55
CloudflareAuthHandler,
66
handleTokenExchangeCallback,
7-
UserSchema,
87
} from '@repo/mcp-common/src/cloudflare-oauth-handler'
98

109
import { ContainerManager } from './containerManager'
1110
import { ContainerMcpAgent } from './containerMcp'
1211

12+
import type { AccountSchema, UserSchema } from '@repo/mcp-common/src/cloudflare-oauth-handler'
13+
1314
export { ContainerManager, ContainerMcpAgent }
1415

1516
export type Env = {
@@ -34,7 +35,8 @@ export default new OAuthProvider({
3435
defaultHandler: CloudflareAuthHandler,
3536
authorizeEndpoint: '/oauth/authorize',
3637
tokenEndpoint: '/token',
37-
tokenExchangeCallback: handleTokenExchangeCallback,
38+
tokenExchangeCallback: (options) =>
39+
handleTokenExchangeCallback(options, env.CLOUDFLARE_CLIENT_ID, env.CLOUDFLARE_CLIENT_SECRET),
3840
// Cloudflare access token TTL
3941
accessTokenTTL: 3600,
4042
clientRegistrationEndpoint: '/register',

‎apps/sandbox-container/tsconfig.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
"jsx": "react-jsx",
66
"module": "ESNext",
77
"moduleResolution": "bundler",
8-
"types": ["@cloudflare/workers-types/2023-07-01"],
8+
"types": ["./worker-configuration.d.ts", "@cloudflare/workers-types/2023-07-01"],
99
"noEmit": true,
1010
"esModuleInterop": true,
1111
"forceConsistentCasingInFileNames": true,

‎apps/sandbox-container/worker-configuration.d.ts‎

Lines changed: 5706 additions & 0 deletions
Large diffs are not rendered by default.

‎apps/workers-bindings/.dev.vars.example‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
CLOUDFLARE_CLIENT_ID=
2+
CLOUDFLARE_CLIENT_SECRET=

‎apps/workers-bindings/.eslintrc.cjs‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
/** @type {import("eslint").Linter.Config} */
2+
module.exports = {
3+
root: true,
4+
extends: ['@repo/eslint-config/default.cjs'],
5+
}

‎apps/workers-bindings/.gitignore‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
node_modules
2+
3+
.nx
4+
.idea
5+
.vscode
6+
.zed
7+
# Logs
8+
9+
logs
10+
_.log
11+
npm-debug.log_
12+
yarn-debug.log*
13+
yarn-error.log*
14+
lerna-debug.log*
15+
.pnpm-debug.log*
16+
17+
# Diagnostic reports (https://nodejs.org/api/report.html)
18+
19+
report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
20+
21+
# Runtime data
22+
23+
pids
24+
_.pid
25+
_.seed
26+
\*.pid.lock
27+
28+
# Directory for instrumented libs generated by jscoverage/JSCover
29+
30+
lib-cov
31+
32+
# Coverage directory used by tools like istanbul
33+
34+
coverage
35+
\*.lcov
36+
37+
# nyc test coverage
38+
39+
.nyc_output
40+
41+
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
42+
43+
.grunt
44+
45+
# Bower dependency directory (https://bower.io/)
46+
47+
bower_components
48+
49+
# node-waf configuration
50+
51+
.lock-wscript
52+
53+
# Compiled binary addons (https://nodejs.org/api/addons.html)
54+
55+
build/Release
56+
57+
# Dependency directories
58+
59+
node_modules/
60+
jspm_packages/
61+
62+
# Snowpack dependency directory (https://snowpack.dev/)
63+
64+
web_modules/
65+
66+
# TypeScript cache
67+
68+
\*.tsbuildinfo
69+
70+
# Optional npm cache directory
71+
72+
.npm
73+
74+
# Optional eslint cache
75+
76+
.eslintcache
77+
78+
# Optional stylelint cache
79+
80+
.stylelintcache
81+
82+
# Microbundle cache
83+
84+
.rpt2_cache/
85+
.rts2_cache_cjs/
86+
.rts2_cache_es/
87+
.rts2_cache_umd/
88+
89+
# Optional REPL history
90+
91+
.node_repl_history
92+
93+
# Output of 'npm pack'
94+
95+
\*.tgz
96+
97+
# Yarn Integrity file
98+
99+
.yarn-integrity
100+
101+
# dotenv environment variable files
102+
103+
.env
104+
.env.development.local
105+
.env.test.local
106+
.env.production.local
107+
.env.local
108+
109+
# parcel-bundler cache (https://parceljs.org/)
110+
111+
.cache
112+
.parcel-cache
113+
114+
# Next.js build output
115+
116+
.next
117+
out
118+
119+
# Nuxt.js build / generate output
120+
121+
.nuxt
122+
dist
123+
124+
# Gatsby files
125+
126+
.cache/
127+
128+
# Comment in the public line in if your project uses Gatsby and not Next.js
129+
130+
# https://nextjs.org/blog/next-9-1#public-directory-support
131+
132+
# public
133+
134+
# vuepress build output
135+
136+
.vuepress/dist
137+
138+
# vuepress v2.x temp and cache directory
139+
140+
.temp
141+
.cache
142+
143+
# Docusaurus cache and generated files
144+
145+
.docusaurus
146+
147+
# Serverless directories
148+
149+
.serverless/
150+
151+
# FuseBox cache
152+
153+
.fusebox/
154+
155+
# DynamoDB Local files
156+
157+
.dynamodb/
158+
159+
# TernJS port file
160+
161+
.tern-port
162+
163+
# Stores VSCode versions used for testing VSCode extensions
164+
165+
.vscode-test
166+
167+
# yarn v2
168+
169+
.yarn/cache
170+
.yarn/unplugged
171+
.yarn/build-state.yml
172+
.yarn/install-state.gz
173+
.pnp.\*
174+
175+
# wrangler project
176+
177+
.dev.vars
178+
.wrangler/

‎apps/workers-bindings/README.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# Remote MCP Server on Cloudflare
2+
3+
Let's get a remote MCP server up-and-running on Cloudflare Workers complete with OAuth login!
4+
5+
## Develop locally
6+
7+
```bash
8+
# clone the repository
9+
git clone [email protected]:cloudflare/ai.git
10+
11+
# install dependencies
12+
cd ai
13+
npm install
14+
15+
# run locally
16+
npx nx dev remote-mcp-server
17+
```
18+
19+
You should be able to open [`http://localhost:8787/`](http://localhost:8787/) in your browser
20+
21+
## Connect the MCP inspector to your server
22+
23+
To explore your new MCP api, you can use the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector).
24+
25+
- Start it with `npx @modelcontextprotocol/inspector`
26+
- [Within the inspector](http://localhost:5173), switch the Transport Type to `SSE` and enter `http://localhost:8787/sse` as the URL of the MCP server to connect to, and click "Connect"
27+
- You will navigate to a (mock) user/password login screen. Input any email and pass to login.
28+
- You should be redirected back to the MCP Inspector and you can now list and call any defined tools!
29+
30+
<div align="center">
31+
<img src="img/mcp-inspector-sse-config.png" alt="MCP Inspector with the above config" width="600"/>
32+
</div>
33+
34+
<div align="center">
35+
<img src="img/mcp-inspector-successful-tool-call.png" alt="MCP Inspector with after a tool call" width="600"/>
36+
</div>
37+
38+
## Connect Claude Desktop to your local MCP server
39+
40+
The MCP inspector is great, but we really want to connect this to Claude! Follow [Anthropic's Quickstart](https://modelcontextprotocol.io/quickstart/user) and within Claude Desktop go to Settings > Developer > Edit Config to find your configuration file.
41+
42+
Open the file in your text editor and replace it with this configuration:
43+
44+
```json
45+
{
46+
"mcpServers": {
47+
"math": {
48+
"command": "npx",
49+
"args": ["mcp-remote", "http://localhost:8787/sse"]
50+
}
51+
}
52+
}
53+
```
54+
55+
This will run a local proxy and let Claude talk to your MCP server over HTTP
56+
57+
When you open Claude a browser window should open and allow you to login. You should see the tools available in the bottom right. Given the right prompt Claude should ask to call the tool.
58+
59+
<div align="center">
60+
<img src="img/available-tools.png" alt="Clicking on the hammer icon shows a list of available tools" width="600"/>
61+
</div>
62+
63+
<div align="center">
64+
<img src="img/claude-does-math-the-fancy-way.png" alt="Claude answers the prompt 'I seem to have lost my calculator and have run out of fingers. Could you use the math tool to add 23 and 19?' by invoking the MCP add tool" width="600"/>
65+
</div>
66+
67+
## Deploy to Cloudflare
68+
69+
1. `npx wrangler kv namespace create OAUTH_KV`
70+
2. Follow the guidance to add the kv namespace ID to `wrangler.jsonc`
71+
3. `npm run deploy`
72+
73+
## Call your newly deployed remote MCP server from a remote MCP client
74+
75+
Just like you did above in "Develop locally", run the MCP inspector:
76+
77+
`npx @modelcontextprotocol/inspector@latest`
78+
79+
Then enter the `workers.dev` URL (ex: `worker-name.account-name.workers.dev/sse`) of your Worker in the inspector as the URL of the MCP server to connect to, and click "Connect".
80+
81+
You've now connected to your MCP server from a remote MCP client.
82+
83+
## Connect Claude Desktop to your remote MCP server
84+
85+
Update the Claude configuration file to point to your `workers.dev` URL (ex: `worker-name.account-name.workers.dev/sse`) and restart Claude
86+
87+
```json
88+
{
89+
"mcpServers": {
90+
"math": {
91+
"command": "npx",
92+
"args": ["mcp-remote", "https://worker-name.account-name.workers.dev/sse"]
93+
}
94+
}
95+
}
96+
```
97+
98+
## Debugging
99+
100+
Should anything go wrong it can be helpful to restart Claude, or to try connecting directly to your
101+
MCP server on the command line with the following command.
102+
103+
```bash
104+
npx mcp-remote http://localhost:8787/sse
105+
```
106+
107+
In some rare cases it may help to clear the files added to `~/.mcp-auth`
108+
109+
```bash
110+
rm -rf ~/.mcp-auth
111+
```

‎apps/workers-bindings/package.json‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{
2+
"name": "workers-bindings",
3+
"version": "0.0.0",
4+
"private": true,
5+
"scripts": {
6+
"check:lint": "run-eslint-workers",
7+
"check:types": "run-tsc",
8+
"deploy": "wrangler deploy",
9+
"dev": "wrangler dev",
10+
"start": "wrangler dev",
11+
"types": "wrangler types",
12+
"test": "vitest"
13+
},
14+
"devDependencies": {
15+
"@cloudflare/vitest-pool-workers": "0.8.14",
16+
"@cloudflare/workers-types": "4.20250410.0",
17+
"@types/node": "22.14.1",
18+
"marked": "15.0.7",
19+
"typescript": "5.5.4",
20+
"vitest": "3.0.9",
21+
"wrangler": "4.10.0"
22+
},
23+
"dependencies": {
24+
"@cloudflare/workers-oauth-provider": "0.0.2",
25+
"@modelcontextprotocol/sdk": "1.8.0",
26+
"@repo/mcp-common": "workspace:*",
27+
"agents": "0.0.49",
28+
"hono": "4.7.6",
29+
"zod": "3.24.2"
30+
}
31+
}

0 commit comments

Comments
 (0)