diff --git a/src/assets/images/agents/mcp-inspector-authenticated.png b/src/assets/images/agents/mcp-inspector-authenticated.png deleted file mode 100644 index 7029fc27bc42807..000000000000000 Binary files a/src/assets/images/agents/mcp-inspector-authenticated.png and /dev/null differ diff --git a/src/assets/images/agents/mcp-inspector-enter-url.png b/src/assets/images/agents/mcp-inspector-enter-url.png deleted file mode 100644 index ed3596f4045bab9..000000000000000 Binary files a/src/assets/images/agents/mcp-inspector-enter-url.png and /dev/null differ diff --git a/src/content/docs/agents/guides/remote-mcp-server.mdx b/src/content/docs/agents/guides/remote-mcp-server.mdx index df82a0c9c1aeb8d..fff20ba1f66a7e1 100644 --- a/src/content/docs/agents/guides/remote-mcp-server.mdx +++ b/src/content/docs/agents/guides/remote-mcp-server.mdx @@ -40,6 +40,12 @@ You can use the [Wrangler CLI](/workers/wrangler) to create a new MCP Server on args={"remote-mcp-server-authless --template=cloudflare/ai/demos/remote-mcp-authless"} /> + 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 testing the server before deploying). + Now, you have the MCP server setup, with dependencies installed. 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 [wrangler:info] Ready on http://localhost:8788 ``` - Your MCP server is now running on `http://localhost:8788/mcp`. + 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`. + :::note + 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. + ::: 4. To test the server locally: + 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. ```sh npx @modelcontextprotocol/inspector@latest ``` - 2. Open the MCP inspector in your web browser: + ```sh output + 🚀 MCP Inspector is up and running at: + http://localhost:5173/?MCP_PROXY_AUTH_TOKEN=46ab..cd3 - ```sh - open http://localhost:5173 + 🌐 Opening browser... ``` - 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. + The MCP inspector will launch in your web browser. You can also launch it manually by opening a browser and going to `https://localhost:`. Check the command output for the local port where MCP Inspector is running. In this example, the MCP server is served on port `5173`. + + 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. 5. You can now deploy your MCP server to Cloudflare. From your project directory, run: @@ -84,8 +97,7 @@ You can use the [Wrangler CLI](/workers/wrangler) to create a new MCP Server on 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. - The MCP server will be deployed to your `*.workers.dev` subdomain at `remote-mcp-server-authless.your-account.workers.dev/mcp`. - + The MCP server will be deployed to your `*.workers.dev` subdomain at `https://remote-mcp-server-authless.your-account.workers.dev/mcp`. 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`. diff --git a/src/content/docs/agents/guides/test-remote-mcp-server.mdx b/src/content/docs/agents/guides/test-remote-mcp-server.mdx index de0f897aba03210..9199ece88cbce70 100644 --- a/src/content/docs/agents/guides/test-remote-mcp-server.mdx +++ b/src/content/docs/agents/guides/test-remote-mcp-server.mdx @@ -17,19 +17,31 @@ This guide will show you options for how to start using your remote MCP server w The [`@modelcontextprotocol/inspector` package](https://github.com/modelcontextprotocol/inspector) is a visual testing tool for MCP servers. -You can run it locally by running the following command: +1. Open a terminal and run the following command: -```bash -npx @modelcontextprotocol/inspector -``` + ```sh + npx @modelcontextprotocol/inspector + ``` + + ```sh output + 🚀 MCP Inspector is up and running at: + http://localhost:5173/?MCP_PROXY_AUTH_TOKEN=46ab..cd3 + + 🌐 Opening browser... + ``` + + The MCP inspector will launch in your web browser. You can also launch it manually by opening a browser and going to `https://localhost:`. Check the command output for the local port where MCP Inspector is running. In this example, the MCP server is served on port `5173`. -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. +2. In the MCP inspector, enter the URL of your MCP server (for example, `http://localhost:8788/mcp`). Select **Connect**. -![MCP inspector](~/assets/images/agents/mcp-inspector-enter-url.png) + You can connect to an MCP server running on your local machine or a remote MCP server running on Cloudflare. -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. +3. If your server requires authentication, the connection will fail. To authenticate: + 1. In MCP Inspector, select **Open Auth settings**. + 2. Select **Quick OAuth Flow**. + 3. Once you have authenticated with the OAuth provider, you will be redirected back to MCP Inspector. Select **Connect**. -![MCP inspector — authenticated](~/assets/images/agents/mcp-inspector-authenticated.png) +You should see the **List tools** button, which will list the tools that your MCP server exposes. ## Connect your remote MCP server to Cloudflare Workers AI Playground diff --git a/src/content/docs/cloudflare-one/access-controls/ai-controls/saas-mcp.mdx b/src/content/docs/cloudflare-one/access-controls/ai-controls/saas-mcp.mdx index 2d6f3a93bca40b0..f0499b8b400e6b5 100644 --- a/src/content/docs/cloudflare-one/access-controls/ai-controls/saas-mcp.mdx +++ b/src/content/docs/cloudflare-one/access-controls/ai-controls/saas-mcp.mdx @@ -67,7 +67,11 @@ You can use the [Wrangler CLI](/workers/wrangler) to create the MCP server on yo npm create cloudflare@latest -- mcp-server-cf-access --template=cloudflare/ai/demos/remote-mcp-cf-access ``` - When asked if you want to deploy to Cloudflare, select **No**. + 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: @@ -137,7 +141,8 @@ The Worker will be deployed to your `*.workers.dev` subdomain at `mcp-server-cf- 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. 10. Configure [Access policies](/cloudflare-one/access-controls/policies/) to define the users who can access the MCP server. -11. Save the application. +11. +12. Save the application. @@ -166,14 +171,20 @@ The Worker will be deployed to your `*.workers.dev` subdomain at `mcp-server-cf- /> 2. Copy the `client_id` and `client_secret` returned in the response. -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). +3. Build the OAuth endpoint URLs using your team name and the `client_id` returned in the response: + + | Endpoint | URL | + | ---------------------- | ----------------------------------------------------------------------------------------------- | + | Token endpoint | `https://.cloudflareaccess.com/cdn-cgi/access/sso/oidc//token` | + | Authorization endpoint | `https://.cloudflareaccess.com/cdn-cgi/access/sso/oidc//authorization` | + | Key endpoint | `https://.cloudflareaccess.com/cdn-cgi/access/sso/oidc//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](#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. +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. To add OAuth endpoints and credentials to our [example MCP server](#1-deploy-an-example-mcp-server): @@ -185,7 +196,7 @@ To add OAuth endpoints and credentials to our [example MCP server](#1-deploy-an- 2. Select the `mcp-server-cf-access` Worker. 3. Go to **Settings**. -4. Under **Variables and Secrets**, update each secret with the corresponding value from your SaaS app: +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). | Workers secret | SaaS app field | | -------------------------- | ---------------------- | @@ -195,6 +206,10 @@ To add OAuth endpoints and credentials to our [example MCP server](#1-deploy-an- | `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 @@ -208,14 +223,14 @@ To add OAuth endpoints and credentials to our [example MCP server](#1-deploy-an- 1. Create the following [Workers secrets](/workers/configuration/secrets/): ```sh - wrangler secret put ACCESS_CLIENT_ID - wrangler secret put ACCESS_CLIENT_SECRET - wrangler secret put ACCESS_TOKEN_URL - wrangler secret put ACCESS_AUTHORIZATION_URL - wrangler secret put ACCESS_JWKS_URL + 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 ``` -2. When prompted to enter a secret value, paste the corresponding values from your SaaS app: +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). | Workers secret | SaaS app field | | -------------------------- | ---------------------- | @@ -225,6 +240,10 @@ To add OAuth endpoints and credentials to our [example MCP server](#1-deploy-an- | `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/). + ::: + 3. Generate a random string for the cookie encryption key: ```sh @@ -234,14 +253,14 @@ To add OAuth endpoints and credentials to our [example MCP server](#1-deploy-an- Store the output of this command in a Workers secret: ```sh - wrangler secret put COOKIE_ENCRYPTION_KEY + npx wrangler secret put COOKIE_ENCRYPTION_KEY ``` ## 4. Test the connection -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..workers.dev/mcp` or `https://mcp-server-cf-access..workers.dev/sse`. +You can now connect to your MCP server at `https://mcp-server-cf-access..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. To test in Workers AI Playground: