Skip to content

Commit 7c0eae5

Browse files
ranbelpatriciasantaana
ranbel
and
patriciasantaana
authored
[Agents+ZT] Refine remote MCP instructions (#28331)
* refine remote mcp instructions * refine access for saas steps * use npx * update mcp URL * delete outdated screenshots * update MCP inspector instructions * Update src/content/docs/agents/guides/remote-mcp-server.mdx Co-authored-by: Patricia Santa Ana <[email protected]> --------- Co-authored-by: Patricia Santa Ana <[email protected]>
1 parent 38e9967 commit 7c0eae5

File tree

5 files changed

+71
-28
lines changed

5 files changed

+71
-28
lines changed

‎src/assets/images/agents/mcp-inspector-authenticated.png‎

-118 KB
Binary file not shown.

‎src/assets/images/agents/mcp-inspector-enter-url.png‎

-68.7 KB
Binary file not shown.

‎src/content/docs/agents/guides/remote-mcp-server.mdx‎

Lines changed: 19 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,12 @@ You can use the [Wrangler CLI](/workers/wrangler) to create a new MCP Server on
4040
args={"remote-mcp-server-authless --template=cloudflare/ai/demos/remote-mcp-authless"}
4141
/>
4242

43+
During setup, select the following options:
44+
- For _Do you want to add an AGENTS.md file to help AI coding tools understand
45+
Cloudflare APIs?_, choose `No`.
46+
- For _Do you want to use git for version control?_, choose `No`.
47+
- For _Do you want to deploy your application?_, choose `No` (we will be testing the server before deploying).
48+
4349
Now, you have the MCP server setup, with dependencies installed.
4450

4551
2. Move into the project folder:
@@ -59,22 +65,29 @@ You can use the [Wrangler CLI](/workers/wrangler) to create a new MCP Server on
5965
[wrangler:info] Ready on http://localhost:8788
6066
```
6167

62-
Your MCP server is now running on `http://localhost:8788/mcp`.
68+
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`.
69+
:::note
70+
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.
71+
:::
6372

6473
4. To test the server locally:
74+
6575
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.
6676

6777
```sh
6878
npx @modelcontextprotocol/inspector@latest
6979
```
7080

71-
2. Open the MCP inspector in your web browser:
81+
```sh output
82+
🚀 MCP Inspector is up and running at:
83+
http://localhost:5173/?MCP_PROXY_AUTH_TOKEN=46ab..cd3
7284

73-
```sh
74-
open http://localhost:5173
85+
🌐 Opening browser...
7586
```
7687

77-
3. 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.
88+
The MCP inspector will launch in your web browser. You can also launch it manually by opening a browser and going to `https://localhost:<PORT>`. Check the command output for the local port where MCP Inspector is running. In this example, the MCP server is served on port `5173`.
89+
90+
3. 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.
7891

7992
5. You can now deploy your MCP server to Cloudflare. From your project directory, run:
8093

@@ -84,8 +97,7 @@ You can use the [Wrangler CLI](/workers/wrangler) to create a new MCP Server on
8497

8598
If you have already [connected a git repository](/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.
8699

87-
The MCP server will be deployed to your `*.workers.dev` subdomain at `remote-mcp-server-authless.your-account.workers.dev/mcp`.
88-
100+
The MCP server will be deployed to your `*.workers.dev` subdomain at `https://remote-mcp-server-authless.your-account.workers.dev/mcp`.
89101

90102
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`.
91103

‎src/content/docs/agents/guides/test-remote-mcp-server.mdx‎

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -17,19 +17,31 @@ This guide will show you options for how to start using your remote MCP server w
1717

1818
The [`@modelcontextprotocol/inspector` package](https://github.com/modelcontextprotocol/inspector) is a visual testing tool for MCP servers.
1919

20-
You can run it locally by running the following command:
20+
1. Open a terminal and run the following command:
2121

22-
```bash
23-
npx @modelcontextprotocol/inspector
24-
```
22+
```sh
23+
npx @modelcontextprotocol/inspector
24+
```
25+
26+
```sh output
27+
🚀 MCP Inspector is up and running at:
28+
http://localhost:5173/?MCP_PROXY_AUTH_TOKEN=46ab..cd3
29+
30+
🌐 Opening browser...
31+
```
32+
33+
The MCP inspector will launch in your web browser. You can also launch it manually by opening a browser and going to `https://localhost:<PORT>`. Check the command output for the local port where MCP Inspector is running. In this example, the MCP server is served on port `5173`.
2534

26-
Then, enter the URL of your remote MCP server. You can use an MCP server running on your local machine on localhost, or you can use a remote MCP server running on Cloudflare.
35+
2. In the MCP inspector, enter the URL of your MCP server (for example, `http://localhost:8788/mcp`). Select **Connect**.
2736

28-
![MCP inspector](~/assets/images/agents/mcp-inspector-enter-url.png)
37+
You can connect to an MCP server running on your local machine or a remote MCP server running on Cloudflare.
2938

30-
Once you have authenticated, 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.
39+
3. If your server requires authentication, the connection will fail. To authenticate:
40+
1. In MCP Inspector, select **Open Auth settings**.
41+
2. Select **Quick OAuth Flow**.
42+
3. Once you have authenticated with the OAuth provider, you will be redirected back to MCP Inspector. Select **Connect**.
3143

32-
![MCP inspector — authenticated](~/assets/images/agents/mcp-inspector-authenticated.png)
44+
You should see the **List tools** button, which will list the tools that your MCP server exposes.
3345

3446
## Connect your remote MCP server to Cloudflare Workers AI Playground
3547

‎src/content/docs/cloudflare-one/access-controls/ai-controls/saas-mcp.mdx‎

Lines changed: 32 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,11 @@ You can use the [Wrangler CLI](/workers/wrangler) to create the MCP server on yo
6767
npm create cloudflare@latest -- mcp-server-cf-access --template=cloudflare/ai/demos/remote-mcp-cf-access
6868
```
6969

70-
When asked if you want to deploy to Cloudflare, select **No**.
70+
During setup, select the following options:
71+
- For _Do you want to add an AGENTS.md file to help AI coding tools understand
72+
Cloudflare APIs?_, choose `No`.
73+
- For _Do you want to use git for version control?_, choose `No`.
74+
- For _Do you want to deploy your application?_, choose `No` (we will be making some changes before deploying).
7175

7276
2. Go to the project directory:
7377

@@ -137,7 +141,8 @@ The Worker will be deployed to your `*.workers.dev` subdomain at `mcp-server-cf-
137141

138142
9. (Optional) Under **Advanced settings**, turn on [**Refresh tokens**](/cloudflare-one/access-controls/applications/http-apps/saas-apps/generic-oidc-saas/#advanced-settings) if you want to reduce the number of times a user needs to log in to the identity provider.
139143
10. Configure [Access policies](/cloudflare-one/access-controls/policies/) to define the users who can access the MCP server.
140-
11. Save the application.
144+
11. <Render file="access/access-choose-idps" product="cloudflare-one" params={{ appType: "saas" }}/>
145+
12. Save the application.
141146

142147
</TabItem>
143148
<TabItem label="API">
@@ -166,14 +171,20 @@ The Worker will be deployed to your `*.workers.dev` subdomain at `mcp-server-cf-
166171
/>
167172

168173
2. Copy the `client_id` and `client_secret` returned in the response.
169-
3. To determine the OAuth endpoint URLs for the SaaS application, refer to the [generic OIDC documentation](/cloudflare-one/access-controls/applications/http-apps/saas-apps/generic-oidc-saas/#2-add-your-application-to-access).
174+
3. Build the OAuth endpoint URLs using your <GlossaryTooltip term="team name">team name</GlossaryTooltip> and the `client_id` returned in the response:
175+
176+
| Endpoint | URL |
177+
| ---------------------- | ----------------------------------------------------------------------------------------------- |
178+
| Token endpoint | `https://<TEAM_NAME>.cloudflareaccess.com/cdn-cgi/access/sso/oidc/<CLIENT_ID>/token` |
179+
| Authorization endpoint | `https://<TEAM_NAME>.cloudflareaccess.com/cdn-cgi/access/sso/oidc/<CLIENT_ID>/authorization` |
180+
| Key endpoint | `https://<TEAM_NAME>.cloudflareaccess.com/cdn-cgi/access/sso/oidc/<CLIENT_ID>/jwks` |
170181

171182
</TabItem>
172183
</Tabs>
173184

174185
## 3. Configure your MCP server
175186

176-
Your MCP server needs to perform an OAuth 2.0 authorization flow to get an `access_token` from the SaaS app created in [Step 1](#1-create-an-access-for-saas-app). When setting up the OAuth client on your MCP server, you will need to paste in the OAuth endpoints and credentials from the SaaS app.
187+
Your MCP server needs to perform an OAuth 2.0 authorization flow to get an `access_token` from the SaaS app created in [Step 1](#1-create-an-access-for-saas-app). When setting up the OAuth client on your MCP server, you will need to paste in the OAuth endpoints and credentials from the Access for SaaS app.
177188

178189
To add OAuth endpoints and credentials to our [example MCP server](#1-deploy-an-example-mcp-server):
179190

@@ -185,7 +196,7 @@ To add OAuth endpoints and credentials to our [example MCP server](#1-deploy-an-
185196
<DashButton url="/?to=/:account/workers-and-pages" />
186197
2. Select the `mcp-server-cf-access` Worker.
187198
3. Go to **Settings**.
188-
4. Under **Variables and Secrets**, update each secret with the corresponding value from your SaaS app:
199+
4. Under **Variables and Secrets**, update each secret with the corresponding value obtained from the [Access for SaaS app](#2-create-an-access-for-saas-app).
189200

190201
| Workers secret | SaaS app field |
191202
| -------------------------- | ---------------------- |
@@ -195,6 +206,10 @@ To add OAuth endpoints and credentials to our [example MCP server](#1-deploy-an-
195206
| `ACCESS_AUTHORIZATION_URL` | Authorization endpoint |
196207
| `ACCESS_JWKS_URL` | Key endpoint |
197208

209+
:::note
210+
Use the Client ID, Client secret, and OAuth endpoints copied from the Cloudflare One dashboard. Do not use the OAuth values from your [third-party identity provider](/cloudflare-one/integrations/identity-providers/generic-oidc/).
211+
:::
212+
198213
5. For `COOKIE_ENCRYPTION_KEY`, you can use the following command to generate a random string:
199214

200215
```sh
@@ -208,14 +223,14 @@ To add OAuth endpoints and credentials to our [example MCP server](#1-deploy-an-
208223
1. Create the following [Workers secrets](/workers/configuration/secrets/):
209224

210225
```sh
211-
wrangler secret put ACCESS_CLIENT_ID
212-
wrangler secret put ACCESS_CLIENT_SECRET
213-
wrangler secret put ACCESS_TOKEN_URL
214-
wrangler secret put ACCESS_AUTHORIZATION_URL
215-
wrangler secret put ACCESS_JWKS_URL
226+
npx wrangler secret put ACCESS_CLIENT_ID
227+
npx wrangler secret put ACCESS_CLIENT_SECRET
228+
npx wrangler secret put ACCESS_TOKEN_URL
229+
npx wrangler secret put ACCESS_AUTHORIZATION_URL
230+
npx wrangler secret put ACCESS_JWKS_URL
216231
```
217232

218-
2. When prompted to enter a secret value, paste the corresponding values from your SaaS app:
233+
2. When prompted to enter a secret value, paste the corresponding values obtained from the [Access for SaaS app](#2-create-an-access-for-saas-app).
219234

220235
| Workers secret | SaaS app field |
221236
| -------------------------- | ---------------------- |
@@ -225,6 +240,10 @@ To add OAuth endpoints and credentials to our [example MCP server](#1-deploy-an-
225240
| `ACCESS_AUTHORIZATION_URL` | Authorization endpoint |
226241
| `ACCESS_JWKS_URL` | Key endpoint |
227242

243+
:::note
244+
Use the Client ID, Client secret, and OAuth endpoints copied from the Cloudflare One dashboard. Do not use the OAuth values from your [third-party identity provider](/cloudflare-one/integrations/identity-providers/generic-oidc/).
245+
:::
246+
228247
3. Generate a random string for the cookie encryption key:
229248

230249
```sh
@@ -234,14 +253,14 @@ To add OAuth endpoints and credentials to our [example MCP server](#1-deploy-an-
234253
Store the output of this command in a Workers secret:
235254

236255
```sh
237-
wrangler secret put COOKIE_ENCRYPTION_KEY
256+
npx wrangler secret put COOKIE_ENCRYPTION_KEY
238257
```
239258
</TabItem>
240259
</Tabs>
241260

242261
## 4. Test the connection
243262

244-
You should now be able to connect to your MCP server using [Workers AI Playground](https://playground.ai.cloudflare.com/), [MCP inspector](https://github.com/modelcontextprotocol/inspector), or [other MCP clients](/agents/guides/remote-mcp-server/#connect-your-mcp-server-to-claude-and-other-mcp-clients) that support remote MCP servers. The demo MCP server [supports connections](https://github.com/cloudflare/ai/blob/main/demos/remote-mcp-cf-access/src/index.ts#L63-L69) via either `https://mcp-server-cf-access.<YOUR_SUBDOMAIN>.workers.dev/mcp` or `https://mcp-server-cf-access.<YOUR_SUBDOMAIN>.workers.dev/sse`.
263+
You can now connect to your MCP server at `https://mcp-server-cf-access.<YOUR_SUBDOMAIN>.workers.dev/mcp` using [Workers AI Playground](https://playground.ai.cloudflare.com/), [MCP inspector](https://github.com/modelcontextprotocol/inspector), or [other MCP clients](/agents/guides/remote-mcp-server/#connect-your-mcp-server-to-claude-and-other-mcp-clients) that support remote MCP servers.
245264

246265
To test in Workers AI Playground:
247266

0 commit comments

Comments
 (0)