|
1 | | -# Model Context Protocol (MCP) Server + Cloudflare OAuth |
| 1 | +# Cloudflare DEX MCP Server 📡 |
2 | 2 |
|
3 | | -This is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server that supports remote MCP connections, with Cloudflare OAuth built-in. |
| 3 | +This is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server that supports remote MCP |
| 4 | +connections, with Cloudflare OAuth built-in. |
4 | 5 |
|
5 | | -You can deploy it to your own Cloudflare account, and after you create your own Cloudflare OAuth client app, you'll have a fully functional remote MCP server that you can build off. Users will be able to connect to your MCP server by signing in with their Cloudflare account. |
| 6 | +It integrates tools powered by the [Cloudflare DEX API](https://developers.cloudflare.com/api/resources/zero_trust/subresources/dex/) to provide visibility into device, network, and application performance across your Zero Trust organization |
6 | 7 |
|
7 | | -You can use this as a reference example for how to integrate other OAuth providers with an MCP server deployed to Cloudflare, using the [`workers-oauth-provider` library](https://github.com/cloudflare/workers-oauth-provider). |
| 8 | +## 🔨 Available Tools |
8 | 9 |
|
9 | | -The MCP server (powered by [Cloudflare Workers](https://developers.cloudflare.com/workers/)): |
| 10 | +Currently available tools: |
10 | 11 |
|
11 | | -- Acts as OAuth _Server_ to your MCP clients |
12 | | -- Acts as OAuth _Client_ to your _real_ OAuth server (in this case, Cloudflare) |
| 12 | +| **Category** | **Tool** | **Description** | |
| 13 | +| ------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | |
| 14 | +| **Synthetic Application Monitoring** | `dex_test_statistics` | Analyze Cloudflare DEX Test Results by quartile given a Test ID | |
| 15 | +| | `dex_list_tests` | List configured Cloudflare DEX tests along with overview performance metrics. | |
| 16 | +| | `dex_http_test_details` | Retrieve detailed time series results for an HTTP DEX test by id. | |
| 17 | +| | `dex_traceroute_test_details` | Retrieve detailed time series results for a Traceroute DEX test by id. | |
| 18 | +| | `dex_traceroute_test_network_path` | Retrieve detailed time series results for the network path of a traceroute test by test id and device id. | |
| 19 | +| | `dex_traceroute_test_result_network_path` | Retrieve the hop-by-hop network path for a specific Traceroute DEX test result by id. Use `dex_traceroute_test_network_path` to obain test result ids. | |
| 20 | +| **Remote Captures** | `dex_list_remote_capture_eligible_devices` | Retrieve a list of devices eligible for remote captures like packet captures or WARP diagnostics. | |
| 21 | +| | `dex_create_remote_capture` | Initiate a remote capture on a specific device by id. | |
| 22 | +| | `dex_list_remote_captures` | Retrieve a list of previously created remote captures along with their details and status. | |
| 23 | +| **Fleet Status** | `dex_fleet_status_live` | View live metrics for your fleet of zero trust devices for up to the past 1 hour. | |
| 24 | +| | `dex_fleet_status_over_time` | View historical metrics for your fleet of zero trust devices over time. | |
| 25 | +| | `dex_fleet_status_logs` | View historical logs for your fleet of zero trust devices for up to the past 7 days. | |
| 26 | +| | `dex_list_warp_change_events` | View logs of users toggling WARP connection or changing configuration. | |
| 27 | +| **Misc** | `dex_list_colos` | List Cloudflare colos, optionally sorted by their frequency of appearance in DEX test or fleet status results. | |
13 | 28 |
|
14 | | -## Getting Started |
| 29 | +This MCP server is still a work in progress, and we plan to add more tools in the future. |
15 | 30 |
|
16 | | -### For Production |
| 31 | +### Prompt Examples |
17 | 32 |
|
18 | | -- Set secrets via Wrangler |
| 33 | +- `Are there any anomolies in the DEX test to the internal wiki in the past 24 hours?` |
| 34 | +- `Can you see any bottlenecks in [email protected]'s network path for Zoom today between 1 and 2 PM?` |
| 35 | +- `How many macOS devices are connected right now in DFW?` |
| 36 | +- `Do you notice any unusual performance metrics for [email protected]'s device in the past few hours?` |
| 37 | +- `Capture a WARP diag for [email protected] and make sure to test all routes` |
| 38 | +- `Which users have toggled off WARP recently?` |
| 39 | +- `Which Cloudflare colo is most used by my users in the EU running DEX application tests?` |
19 | 40 |
|
20 | | -```bash |
21 | | -wrangler secret put CLOUDFLARE_CLIENT_ID |
22 | | -wrangler secret put CLOUDFLARE_CLIENT_SECRET |
23 | | -``` |
24 | | - |
25 | | -#### Set up a KV namespace |
26 | | - |
27 | | -- Create the KV namespace: |
28 | | - `wrangler kv:namespace create "OAUTH_KV"` |
29 | | -- Update the Wrangler file with the KV ID |
30 | | - |
31 | | -#### Deploy & Test |
32 | | - |
33 | | -Deploy the MCP server to make it available on your workers.dev domain |
34 | | -` wrangler deploy` |
35 | | - |
36 | | -Test the remote server using [Inspector](https://modelcontextprotocol.io/docs/tools/inspector): |
37 | | - |
38 | | -``` |
39 | | -npx @modelcontextprotocol/inspector@latest |
40 | | -``` |
41 | | - |
42 | | -Enter `https://mcp-cloudflare-staging.<your-subdomain>.workers.dev/sse` and hit connect. Once you go through the authentication flow, you'll see the Tools working: |
| 41 | +## Access the remote MCP server from any MCP Client |
43 | 42 |
|
44 | | -<img width="640" alt="image" src="https://github.com/user-attachments/assets/7973f392-0a9d-4712-b679-6dd23f824287" /> |
| 43 | +If your MCP client has first class support for remote MCP servers, the client will provide a way to accept the server URL (`https://dex.mcp.cloudflare.com`) directly within its interface (for example in [Cloudflare AI Playground](https://playground.ai.cloudflare.com/)). |
45 | 44 |
|
46 | | -You now have a remote MCP server deployed! |
| 45 | +If your client does not yet support remote MCP servers, you will need to set up its respective configuration file using [mcp-remote](https://www.npmjs.com/package/mcp-remote) to specify which servers your client can access. |
47 | 46 |
|
48 | | -#### Access the remote MCP server from Claude Desktop |
| 47 | +Replace the content with the following configuration: |
49 | 48 |
|
50 | | -Open Claude Desktop and navigate to Settings -> Developer -> Edit Config. This opens the configuration file that controls which MCP servers Claude can access. |
51 | | - |
52 | | -Replace the content with the following configuration. Once you restart Claude Desktop, a browser window will open showing your OAuth login page. Complete the authentication flow to grant Claude access to your MCP server. After you grant access, the tools will become available for you to use. |
53 | | - |
54 | | -``` |
| 49 | +```json |
55 | 50 | { |
56 | | - "mcpServers": { |
57 | | - "cloudflare": { |
58 | | - "command": "npx", |
59 | | - "args": [ |
60 | | - "mcp-remote", |
61 | | - "https://<your-subdomain>.workers.dev/sse" |
62 | | - ] |
63 | | - } |
64 | | - } |
| 51 | + "mcpServers": { |
| 52 | + "cloudflare": { |
| 53 | + "command": "npx", |
| 54 | + "args": ["mcp-remote", "https://dex.mcp.cloudflare.com/sse"] |
| 55 | + } |
| 56 | + } |
65 | 57 | } |
66 | 58 | ``` |
67 | 59 |
|
68 | | -Once the Tools (under 🔨) show up in the interface, you can ask Claude to use them. 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. |
69 | | - |
70 | | -### For Local Development |
71 | | - |
72 | | -If you'd like to iterate and test your MCP server, you can do so in local development. This will require you to create another OAuth App on Cloudflare: |
73 | | - |
74 | | -- Create a `.dev.vars` file in your project root with: |
75 | | - |
76 | | -``` |
77 | | -CLOUDFLARE_CLIENT_ID=your_development_cloudflare_client_id |
78 | | -CLOUDFLARE_CLIENT_SECRET=your_development_cloudflare_client_secret |
79 | | -``` |
80 | | - |
81 | | -#### Develop & Test |
82 | | - |
83 | | -Run the server locally to make it available at `http://localhost:8788` |
84 | | -`wrangler dev` |
85 | | - |
86 | | -To test the local server, enter `http://localhost:8788/sse` into Inspector and hit connect. Once you follow the prompts, you'll be able to "List Tools". |
87 | | - |
88 | | -#### Using Claude and other MCP Clients |
89 | | - |
90 | | -When using Claude to connect to your remote MCP server, you may see some error messages. This is because Claude Desktop doesn't yet support remote MCP servers, so it sometimes gets confused. To verify whether the MCP server is connected, hover over the 🔨 icon in the bottom right corner of Claude's interface. You should see your tools available there. |
91 | | - |
92 | | -#### Using Cursor and other MCP Clients |
93 | | - |
94 | | -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-subdomain>.workers.dev/sse`). |
95 | | - |
96 | | -Note that while Cursor supports HTTP+SSE servers, it doesn't support authentication, so you still need to use `mcp-remote` (and to use a STDIO server, not an HTTP one). |
97 | | - |
98 | | -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. |
99 | | - |
100 | | -## How does it work? |
101 | | - |
102 | | -#### OAuth Provider |
103 | | - |
104 | | -The OAuth Provider library serves as a complete OAuth 2.1 server implementation for Cloudflare Workers. It handles the complexities of the OAuth flow, including token issuance, validation, and management. In this project, it plays the dual role of: |
105 | | - |
106 | | -- Authenticating MCP clients that connect to your server |
107 | | -- Managing the connection to Cloudflare's OAuth services |
108 | | -- Securely storing tokens and authentication state in KV storage |
109 | | - |
110 | | -#### Durable MCP |
111 | | - |
112 | | -Durable MCP extends the base MCP functionality with Cloudflare's Durable Objects, providing: |
113 | | - |
114 | | -- Persistent state management for your MCP server |
115 | | -- Secure storage of authentication context between requests |
116 | | -- Access to authenticated user information via `this.props` |
117 | | -- Support for conditional tool availability based on user identity |
118 | | - |
119 | | -#### MCP Remote |
120 | | - |
121 | | -The MCP Remote library enables your server to expose tools that can be invoked by MCP clients like the Inspector. It: |
| 60 | +Once you've set up your configuration file, restart MCP client and a browser window will open showing your OAuth login page. Proceed through the authentication flow to grant the client access to your MCP server. After you grant access, the tools will become available for you to use. |
122 | 61 |
|
123 | | -- Defines the protocol for communication between clients and your server |
124 | | -- Provides a structured way to define tools |
125 | | -- Handles serialization and deserialization of requests and responses |
126 | | -- Maintains the Server-Sent Events (SSE) connection between clients and your server |
| 62 | +Interested in contributing, and running this server locally? See [CONTRIBUTING.md](CONTRIBUTING.md) to get started. |
0 commit comments