Skip to content

Commit d910047

Browse files
ranbelranbel
committed
incorporate Workers example
1 parent 97ac489 commit d910047

File tree

1 file changed

+129
-20
lines changed
  • src/content/docs/cloudflare-one/applications/configure-apps/mcp-servers

1 file changed

+129
-20
lines changed

‎src/content/docs/cloudflare-one/applications/configure-apps/mcp-servers/saas-mcp.mdx‎

Lines changed: 129 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -8,40 +8,149 @@ sidebar:
88

99
import { Render, GlossaryTooltip } from "~/components"
1010

11-
You can secure <GlossaryTooltip term="MCP server">Model Context Protocol (MCP) servers</GlossaryTooltip> by using Cloudflare Access as the Single Sign-On (SSO) provider. When users connect to the remote MCP server using an <GlossaryTooltip term="MCP client">MCP client</GlossaryTooltip>, they will be prompted to log in to your [identity provider](/cloudflare-one/identity/idp-integration/) and are only granted access if they pass your [Access policies](/cloudflare-one/policies/access/#selectors).
11+
You can secure <GlossaryTooltip term="MCP server">Model Context Protocol (MCP) servers</GlossaryTooltip> by using Cloudflare Access as an OAuth Single Sign-On (SSO) provider.
12+
13+
This guide walks through how to deploy a remote MCP server on [Cloudflare Workers](/workers/) that requires Cloudflare Access for authentication. When users connect to the MCP server using an <GlossaryTooltip term="MCP client">MCP client</GlossaryTooltip>, they will be prompted to log in to your [identity provider](/cloudflare-one/identity/idp-integration/) and are only granted access if they pass your [Access policies](/cloudflare-one/policies/access/#selectors).
1214

1315
## Prerequisites
1416

15-
- An [identity provider](/cloudflare-one/identity/idp-integration/) configured in Cloudflare Zero Trust
17+
- Add an [identity provider](/cloudflare-one/identity/idp-integration/) to Cloudflare Zero Trust
18+
- Install [npm](https://docs.npmjs.com/getting-started)
19+
- Install [Node.js](https://nodejs.org/en/)
20+
21+
## 1. Deploy an example MCP server
22+
23+
To deploy our [example MCP server](https://github.com/cloudflare/ai/tree/main/demos/remote-mcp-cf-access) on Workers:
24+
25+
1. Open a terminal and clone our example project:
26+
27+
```sh
28+
npm create cloudflare@latest -- mcp-server-cf-access --template=cloudflare/ai/demos/remote-mcp-cf-access
29+
```
30+
31+
When asked if you want to deploy to Cloudflare, select **No**.
32+
33+
2. Go to the project directory:
34+
35+
```sh
36+
cd mcp-server-cf-access
37+
```
38+
39+
3. Create a [Workers KV namespace](/kv/concepts/kv-namespaces/) to store the key. The binding name should be `OAUTH_KV` if you want to run the example as written.
40+
41+
```sh
42+
npx wrangler kv namespace create "OAUTH_KV"
43+
```
44+
45+
The command will output the binding name and KV namespace ID:
46+
47+
```sh output
48+
{
49+
"kv_namespaces": [
50+
{
51+
"binding": "OAUTH_KV",
52+
"id": "<YOUR_KV_NAMESPACE_ID>"
53+
}
54+
]
55+
}
56+
```
57+
58+
4. Open `wrangler.jsonc` in an editor and insert your `OAUTH_KV` namespace ID:
59+
60+
```jsonc
61+
"kv_namespaces": [
62+
{
63+
"binding": "OAUTH_KV",
64+
"id": "<YOUR_KV_NAMESPACE_ID>"
65+
}
66+
],
67+
```
68+
69+
70+
5. You can now deploy the Worker to Cloudflare's global network:
71+
72+
```sh
73+
npx wrangler deploy
74+
```
1675

17-
## 1. Create an Access for SaaS app
76+
The Worker will be deployed to your `*.workers.dev` subdomain at `mcp-server-cf-access.<YOUR_SUBDOMAIN>.workers.dev`.
77+
78+
## 2. Create an Access for SaaS app
1879

1980
1. In [Zero Trust](https://one.dash.cloudflare.com), go to **Access** > **Applications**.
2081
2. Select **SaaS**.
2182
3. In **Application**, enter a custom name (for example, `MCP server`) and select the textbox that appears below.
2283
4. Select **OIDC** as the authentication protocol.
2384
5. Select **Add application**.
24-
6. In **Redirect URLs**, enter the authorization callback URL for your MCP server (for example, `https://<SERVER-NAME>.<SUBDOMAIN>.workers.dev/callback`). Refer to your MCP server documentation for instructions on obtaining this value.
25-
7. Copy the following values to input into your MCP server's OAuth configuration. Different MCP servers may require different sets of input values.
26-
- **Client secret**
27-
- **Client ID**
28-
- **Configuration endpoint**
29-
- **Issuer**
30-
- **Token endpoint**
31-
- **Authorization endpoint**
32-
- **Key endpoint**
33-
- **Userinfo endpoint**
34-
8. (Optional) Under **Advanced settings**, turn on [**Refresh tokens**](/cloudflare-one/applications/configure-apps/saas-apps/generic-oidc-saas/#advanced-settings) to reduce the number of times a user needs to log in to the identity provider.
35-
9. Configure [Access policies](/cloudflare-one/policies/access/) to define the users can access the MCP server.
85+
6. In **Redirect URLs**, enter the authorization callback URL for your MCP server. The callback URL for our [example MCP server](#1-deploy-an-example-mcp-server) is
86+
```txt
87+
https://mcp-server-cf-access.<YOUR_SUBDOMAIN>.workers.dev/callback
88+
```
89+
7. Copy the following values to input into our example MCP server. Other MCP servers may require different sets of input values.
90+
- **Client secret**
91+
- **Client ID**
92+
- **Token endpoint**
93+
- **Authorization endpoint**
94+
- **Key endpoint**
95+
96+
8. (Optional) Under **Advanced settings**, turn on [**Refresh tokens**](/cloudflare-one/applications/configure-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.
97+
9. Configure [Access policies](/cloudflare-one/policies/access/) to define the users who can access the MCP server.
3698
10. Save the application.
3799

38-
This SaaS application now acts as the SSO provider for your MCP server.
100+
## 3. Configure your MCP server
101+
102+
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.
103+
104+
To add OAuth endpoints and credentials to our [example MCP server](#1-deploy-an-example-mcp-server):
105+
106+
1. Create the following [Workers secrets](/workers/configuration/secrets/):
107+
108+
```sh
109+
wrangler secret put ACCESS_CLIENT_ID
110+
wrangler secret put ACCESS_CLIENT_SECRET
111+
wrangler secret put ACCESS_TOKEN_URL
112+
wrangler secret put ACCESS_AUTHORIZATION_URL
113+
wrangler secret put ACCESS_JWKS_URL
114+
```
115+
116+
2. When prompted to enter a secret value, paste the corresponding values from your SaaS app:
117+
118+
| Workers secret | SaaS app field |
119+
| ------------- | -------------- |
120+
| `ACCESS_CLIENT_ID`| Client ID |
121+
| `ACCESS_CLIENT_SECRET` | Client secret |
122+
| `ACCESS_TOKEN_URL` | Token endpoint |
123+
| `ACCESS_AUTHORIZATION_URL` | Authorization endpoint |
124+
| `ACCESS_JWKS_URL` | Key endpoint |
125+
126+
3. Configure a cookie encryption key:
127+
128+
a. Generate a random string:
129+
130+
```sh
131+
openssl rand -hex 32
132+
```
133+
134+
b. Store the string in a Workers secret:
135+
136+
```sh
137+
wrangler secret put COOKIE_ENCRYPTION_KEY
138+
```
139+
140+
## 4. Test the connection
141+
142+
You should now be able to connect to your MCP server running at `https://mcp-server-cf-access.<YOUR_SUBDOMAIN>.workers.dev/sse` 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.
143+
144+
To test in Workers AI Playground:
145+
146+
1. Go to [Workers AI Playground](https://playground.ai.cloudflare.com/).
39147

40-
## 2. Configure your MCP server
148+
2. Under **MCP Servers**, enter `https://mcp-server-cf-access.<YOUR_SUBDOMAIN>.workers.dev/sse` for the MCP server URL.
41149

42-
Configure the OAuth client on your MCP server to use the OAuth endpoints and credentials from the SaaS app created in [Step 1](#1-create-an-access-for-saas-app). The MCP server should successfully obtain an `access_token` after the user authenticates to Access.
150+
3. Select **Connect**.
43151

44-
For a practical example of how to configure the OAuth client, refer to [Deploy an example MCP server](#deploy-an-example-mcp-server).
152+
4. A popup window will appear requesting access to the MCP server. Select **Approve**.
45153

46-
## Deploy an example MCP server
154+
5. Follow the prompts to log in to your identity provider.
47155

156+
Workers AI Playground will show a **Connected** status. The MCP server should successfully obtain an `access_token` from Cloudflare Access.

0 commit comments

Comments
 (0)