Skip to content

saas-mcp.mdx

Latest commit

 

History

History
277 lines (207 loc) · 11.4 KB

saas-mcp.mdx

File metadata and controls

277 lines (207 loc) · 11.4 KB
pcx_content_type how-to
title Secure MCP servers with Access for SaaS
tags
MCP
sidebar
order label
2
Secure MCP servers with Access for SaaS

import { Render, GlossaryTooltip, Tabs, TabItem, APIRequest, DashButton } from "~/components";

You can secure Model Context Protocol (MCP) servers by using Cloudflare Access as an OAuth Single Sign-On (SSO) provider.

This guide walks through how to deploy a remote MCP server on Cloudflare Workers that requires Cloudflare Access for authentication. When users connect to the MCP server using an MCP client, they will be prompted to log in to your identity provider and are only granted access if they pass your Access policies.

Prerequisites

1. Deploy an example MCP server

To deploy our example MCP server to your Cloudflare account:

  1. Select the following button to launch the quickstart flow:

    Deploy to Workers

  2. Select the account that contains your Zero Trust organization.

  3. On the Create an application page, configure the following fields:

    • Git account: Select an existing account or connect a new GitHub or GitLab account.
    • Create private Git repository: Choose whether the project repository should be public or private.
    • Project name: mcp-server-cf-access
    • Select KV namespace: Create new
    • Name your KV namespace: OAUTH_KV

    We will configure ACCESS_CLIENT_ID and the other secret values in a later step.

  4. Select Create and deploy.

The MCP server will be deployed to your *.workers.dev subdomain at mcp-server-cf-access.<YOUR_SUBDOMAIN>.workers.dev. A new git repository will be set up on your GitHub or GitLab account for your MCP server, configured to automatically deploy to Cloudflare each time you push a change or merge a pull request to the main branch of the repository.

You can use the Wrangler CLI to create the MCP server on your local machine and deploy it to Cloudflare.

:::note[Prerequisites]

  1. Open a terminal and clone our example project:

    ```sh
npm create cloudflare@latest -- mcp-server-cf-access --template=cloudflare/ai/demos/remote-mcp-cf-access
```

    During setup, select the following options: - For Do you want to add an AGENTS.md file to help AI coding tools understand Cloudflare APIs?, choose No. - For Do you want to use git for version control?, choose No. - For Do you want to deploy your application?, choose No (we will be making some changes before deploying).

  2. Go to the project directory:

    cd mcp-server-cf-access

  3. Create a Workers KV namespace to store the key. The binding name should be OAUTH_KV if you want to run the example as written.

    npx wrangler kv namespace create "OAUTH_KV"
    The command will output the binding name and KV namespace ID:

```sh output
{
	"kv_namespaces": [
		{
			"binding": "OAUTH_KV",
			"id": "<YOUR_KV_NAMESPACE_ID>"
		}
	]
}
```

  4. Open wrangler.jsonc in an editor and insert your OAUTH_KV namespace ID:

    "kv_namespaces": [
	{
		"binding": "OAUTH_KV",
		"id": "<YOUR_KV_NAMESPACE_ID>"
	}
],

  5. You can now deploy the Worker to Cloudflare's global network:

    npx wrangler deploy

The Worker will be deployed to your *.workers.dev subdomain at mcp-server-cf-access.<YOUR_SUBDOMAIN>.workers.dev.

2. Create an Access for SaaS app

  1. In Cloudflare One, go to Access controls > Applications.

  2. Select Add an application.

  3. Select SaaS.

  4. In Application, enter a custom name (for example, MCP server) and select the textbox that appears below.

  5. Select OIDC as the authentication protocol.

  6. Select Add application.

  7. In Redirect URLs, enter the authorization callback URL for your MCP server. The callback URL for our example MCP server is https://mcp-server-cf-access.<YOUR_SUBDOMAIN>.workers.dev/callback.

  8. Copy the following values to input into our example MCP server. Other MCP servers may require different sets of input values.

    • Client secret
    • Client ID
    • Token endpoint
    • Authorization endpoint
    • Key endpoint

  9. (Optional) Under Advanced settings, turn on Refresh tokens if you want to reduce the number of times a user needs to log in to the identity provider.

  10. Configure Access policies to define the users who can access the MCP server.

  11. <Render file="access/access-choose-idps" product="cloudflare-one" params={{ appType: "saas" }}/>

  12. Save the application.

  1. Make a POST request to the Access applications endpoint:

    <APIRequest path="/accounts/{account_id}/access/apps" method="POST" json={{ name: "MCP server", type: "saas", saas_app: { auth_type: "oidc", redirect_uris: [ "https://mcp-server-cf-access.<YOUR_SUBDOMAIN>.workers.dev/callback", ], grant_type: ["authorization_code", "refresh_tokens"], refresh_token_options: { lifetime: "90d", }, }, policies: ["f174e90a-fafe-4643-bbbc-4a0ed4fc8415"], allowed_idps: [], }} />

  2. Copy the client_id and client_secret returned in the response.

  3. Build the OAuth endpoint URLs using your team name and the client_id returned in the response:

    Endpoint URL
    Token endpoint https://<TEAM_NAME>.cloudflareaccess.com/cdn-cgi/access/sso/oidc/<CLIENT_ID>/token
    Authorization endpoint https://<TEAM_NAME>.cloudflareaccess.com/cdn-cgi/access/sso/oidc/<CLIENT_ID>/authorization
    Key endpoint https://<TEAM_NAME>.cloudflareaccess.com/cdn-cgi/access/sso/oidc/<CLIENT_ID>/jwks

3. Configure your MCP server

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. 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.

To add OAuth endpoints and credentials to our example MCP server:

  1. In the Cloudflare dashboard, go to the Workers & Pages page.

  2. Select the mcp-server-cf-access Worker.

  3. Go to Settings.

  4. Under Variables and Secrets, update each secret with the corresponding value obtained from the Access for SaaS app.

    Workers secret SaaS app field
    ACCESS_CLIENT_ID Client ID
    ACCESS_CLIENT_SECRET Client secret
    ACCESS_TOKEN_URL Token endpoint
    ACCESS_AUTHORIZATION_URL Authorization endpoint
    ACCESS_JWKS_URL Key endpoint 
     :::note
 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/).
 :::

  5. For COOKIE_ENCRYPTION_KEY, you can use the following command to generate a random string:

     ```sh
 openssl rand -hex 32
 ```

    Enter the output of this command into COOKIE_ENCRYPTION_KEY.

1. Create the following [Workers secrets](/workers/configuration/secrets/): 
```sh
npx wrangler secret put ACCESS_CLIENT_ID
npx wrangler secret put ACCESS_CLIENT_SECRET
npx wrangler secret put ACCESS_TOKEN_URL
npx wrangler secret put ACCESS_AUTHORIZATION_URL
npx wrangler secret put ACCESS_JWKS_URL
```

  1. When prompted to enter a secret value, paste the corresponding values obtained from the Access for SaaS app.

    Workers secret SaaS app field
    ACCESS_CLIENT_ID Client ID
    ACCESS_CLIENT_SECRET Client secret
    ACCESS_TOKEN_URL Token endpoint
    ACCESS_AUTHORIZATION_URL Authorization endpoint
    ACCESS_JWKS_URL Key endpoint 
    :::note
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/).
:::

  2. Generate a random string for the cookie encryption key:

    ```sh
openssl rand -hex 32
```

Store the output of this command in a Workers secret:

```sh
npx wrangler secret put COOKIE_ENCRYPTION_KEY
```

4. Test the connection

You can now connect to your MCP server at https://mcp-server-cf-access.<YOUR_SUBDOMAIN>.workers.dev/mcp using Workers AI Playground, MCP inspector, or other MCP clients that support remote MCP servers.

To test in Workers AI Playground:

  1. Go to Workers AI Playground.

  2. Under MCP Servers, enter https://mcp-server-cf-access.<YOUR_SUBDOMAIN>.workers.dev/mcp for the MCP server URL.

  3. Select Connect.

  4. A popup window will appear requesting access to the MCP server. Select Approve.

  5. Follow the prompts to log in to your identity provider.

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