From e2f2d169bbc354dfc65cbf0f1cec7466c7fdc4f0 Mon Sep 17 00:00:00 2001 From: Kenneth Johnson Date: Thu, 21 May 2026 20:51:35 -0500 Subject: [PATCH 1/4] [Access] Add API reference examples for MCP portal CRUD operations --- .../ai-controls/mcp-portals.mdx | 71 +++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/src/content/docs/cloudflare-one/access-controls/ai-controls/mcp-portals.mdx b/src/content/docs/cloudflare-one/access-controls/ai-controls/mcp-portals.mdx index 1cef39bcdab2d35..1e4cd1822436769 100644 --- a/src/content/docs/cloudflare-one/access-controls/ai-controls/mcp-portals.mdx +++ b/src/content/docs/cloudflare-one/access-controls/ai-controls/mcp-portals.mdx @@ -192,6 +192,77 @@ Alias values must be 1-40 characters and can only contain letters, numbers, hyph All tools exposed through a portal are automatically namespaced with the server ID as a prefix. For example, a tool named `list_issues` on a server with ID `github` will appear as `github_list_issues` in the portal. This prevents name collisions when multiple MCP servers expose tools with the same name. +## Manage portals via API + +In addition to the dashboard, you can manage MCP server portals programmatically using the Cloudflare API. The following examples show common operations. + +:::caution +Unlike the dashboard, the API does not automatically create a DNS record for your portal hostname. After creating a portal via the API, you must create a proxied CNAME record that points your portal subdomain to `gateway.agents.cloudflare.com`. Without this record, the portal will return `522` errors. +::: + +### List portals + + + +### Create a portal + + + +### List MCP servers + + + +### Create an MCP server + + + +The `auth_type` field accepts the following values: + +| Value | Description | +| ----- | ----------- | +| `oauth` | The server requires OAuth authentication. After creating the server, you will need to authenticate via the dashboard to establish admin credentials. | +| `bearer` | The server uses a static bearer token for authentication. Provide the token in `auth_credentials`. | +| `unauthenticated` | The server does not require authentication. | + +### Force sync an MCP server + +To manually trigger a synchronization of tools and prompts from an upstream MCP server: + + + +### Delete a portal + + + ## Code mode [Code mode](/agents/api-reference/codemode/) is turned on by default on all MCP server portals. It reduces context window usage by collapsing all tools in the portal into a single `code` tool. Instead of loading a separate tool definition for each upstream MCP server tool, the connected AI agent writes JavaScript that calls typed `codemode.*` methods. The generated code runs in an isolated [Dynamic Worker](/workers/runtime-apis/bindings/worker-loader/) environment, which keeps authentication credentials and environment variables out of the model context. From 485d665defee01d421d1c043c907a3aefed3b9f3 Mon Sep 17 00:00:00 2001 From: Kenneth Johnson Date: Fri, 22 May 2026 15:37:53 -0500 Subject: [PATCH 2/4] [Access] Fix build: use CURL for portal create/update to avoid schema validation issue --- .../access-controls/ai-controls/mcp-portals.mdx | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/src/content/docs/cloudflare-one/access-controls/ai-controls/mcp-portals.mdx b/src/content/docs/cloudflare-one/access-controls/ai-controls/mcp-portals.mdx index 1e4cd1822436769..01ca32b3a5ed2b5 100644 --- a/src/content/docs/cloudflare-one/access-controls/ai-controls/mcp-portals.mdx +++ b/src/content/docs/cloudflare-one/access-controls/ai-controls/mcp-portals.mdx @@ -11,7 +11,7 @@ sidebar: label: MCP server portals --- -import { Render, Tabs, TabItem, APIRequest } from "~/components"; +import { Render, Tabs, TabItem, APIRequest, CURL } from "~/components"; An MCP server portal centralizes multiple [Model Context Protocol (MCP) servers](https://www.cloudflare.com/learning/ai/what-is-model-context-protocol-mcp/) onto a single HTTP endpoint. @@ -209,9 +209,10 @@ Unlike the dashboard, the API does not automatically create a DNS record for you ### Create a portal - Date: Fri, 22 May 2026 15:58:31 -0500 Subject: [PATCH 3/4] [Access] Fix build: use CURL for MCP server create (same schema id issue) --- .../access-controls/ai-controls/mcp-portals.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/content/docs/cloudflare-one/access-controls/ai-controls/mcp-portals.mdx b/src/content/docs/cloudflare-one/access-controls/ai-controls/mcp-portals.mdx index 01ca32b3a5ed2b5..5b9465e13f6f78d 100644 --- a/src/content/docs/cloudflare-one/access-controls/ai-controls/mcp-portals.mdx +++ b/src/content/docs/cloudflare-one/access-controls/ai-controls/mcp-portals.mdx @@ -230,9 +230,10 @@ Unlike the dashboard, the API does not automatically create a DNS record for you ### Create an MCP server - Date: Fri, 22 May 2026 19:16:59 -0500 Subject: [PATCH 4/4] [Access] Replace all APIRequest with CURL for MCP endpoints not in pinned schema --- .../ai-controls/mcp-portals.mdx | 27 +++++++++++-------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/src/content/docs/cloudflare-one/access-controls/ai-controls/mcp-portals.mdx b/src/content/docs/cloudflare-one/access-controls/ai-controls/mcp-portals.mdx index 5b9465e13f6f78d..3939b3e80e8e495 100644 --- a/src/content/docs/cloudflare-one/access-controls/ai-controls/mcp-portals.mdx +++ b/src/content/docs/cloudflare-one/access-controls/ai-controls/mcp-portals.mdx @@ -11,7 +11,7 @@ sidebar: label: MCP server portals --- -import { Render, Tabs, TabItem, APIRequest, CURL } from "~/components"; +import { Render, Tabs, TabItem, CURL } from "~/components"; An MCP server portal centralizes multiple [Model Context Protocol (MCP) servers](https://www.cloudflare.com/learning/ai/what-is-model-context-protocol-mcp/) onto a single HTTP endpoint. @@ -202,9 +202,10 @@ Unlike the dashboard, the API does not automatically create a DNS record for you ### List portals - ### Create a portal @@ -223,9 +224,10 @@ Unlike the dashboard, the API does not automatically create a DNS record for you ### List MCP servers - ### Create an MCP server @@ -253,16 +255,18 @@ The `auth_type` field accepts the following values: To manually trigger a synchronization of tools and prompts from an upstream MCP server: - ### Delete a portal - ## Code mode @@ -318,9 +322,10 @@ To turn off code mode for a portal: 1. Get your existing MCP portal configuration: - 2. Send a `PUT` request to the [Update a MCP Portal](/api/resources/zero_trust/subresources/access/subresources/ai_controls/subresources/mcp/subresources/portals/methods/update/) endpoint with `allow_code_mode` set to `false`. To avoid overwriting your existing configuration, the `PUT` request body should contain all fields returned by the previous `GET` request.