MCP 服务器门户

MCP 服务器门户将多个模型上下文协议 (MCP) 服务器 ↗集中到单个 HTTP 端点上。

本指南介绍如何将 MCP 服务器添加到 Cloudflare Access，创建一个包含自定义工具和策略的 MCP 门户，以及使用 MCP 客户端将用户连接到该门户。

MCP 服务器门户提供以下功能：

• 简化对多个 MCP 服务器的访问：MCP 服务器门户支持未通过身份验证的 MCP 服务器以及使用 OAuth 安全保护的 MCP 服务器（例如，通过 Access for SaaS 或第三方 OAuth 提供商）。用户通过 Cloudflare Access 登录到门户 URL，并会被提示单独向每个需要 OAuth 的服务器进行身份验证。

• 按门户定制工具：管理员可以通过选择他们希望通过门户提供给用户的特定工具和提示模板，来为特定用例定制 MCP 门户。这允许用户访问一组精选的工具和提示——向 AI 模型暴露的外部上下文越少，AI 的响应往往越好。

• 工具和提示别名：管理员可以在门户或服务器级别重命名工具和提示并编辑其描述，而无需修改上游 MCP 服务器。别名有助于最终用户找到正确的工具，也有助于 AI 代理选择正确的工具。

• 上下文优化：门户支持查询参数选项，通过最小化或隐藏工具定义来减少上下文窗口的使用。有关详细信息，请参阅优化上下文。

• 非浏览器客户端支持：MCP 客户端通过托管 OAuth（managed OAuth），使用标准的 OAuth 2.0 授权码流程向门户进行身份验证。此托管 OAuth 配置适用于门户的 Access 应用程序。它与门户中单个 MCP 服务器使用的上游 OAuth 是分开的。非浏览器客户端将收到一个包含指向 Access 的 OAuth 发现端点的 WWW-Authenticate 标头的 401 响应，而不是浏览器重定向。您也可以使用Access 服务令牌进行机器对机器访问。

• 代码模式：所有门户默认都提供代码模式。它将所有上游工具折叠为单个 code 工具。AI 代理编写调用每个工具的类型化方法的 JavaScript，代码在隔离的 Dynamic Worker 环境中运行。这使得无论有多少个可用工具，上下文窗口的使用量都保持固定。有关连接说明，请参阅代码模式。

• 可观测性：一旦用户的 AI 代理连接到门户，Cloudflare Access 就会记录使用门户中工具发起的单个请求。您可以选择将门户流量路由到 Cloudflare Gateway，以获得更丰富的 HTTP 日志记录和数据防泄露（DLP）扫描。

下图展示了请求如何流经 MCP 服务器门户。

1. MCP 客户端连接到门户 URL 并接收到一个带有 OAuth 发现元数据的 401 响应。
2. 用户通过其身份提供商在 Cloudflare Access 进行身份验证，或者使用服务令牌标头。
3. Access 验证用户的身份，门户建立 MCP 会话并返回来自已启用的上游服务器的可用工具。
4. 当用户调用工具时，门户从工具命名空间识别目标服务器，附加适当的凭据并代理请求。如果启用了 Gateway 路由，请求将通过 Cloudflare Gateway 以进行 HTTP 日志记录和 DLP 检查。
5. 上游服务器处理请求并通过相同路径返回响应。

工具和提示的后台同步大约每两小时使用管理员凭据运行一次。此同步直接连接到上游服务器，不通过 Gateway 路由。

门户使用 Streamable HTTP ↗ 或 SSE ↗ 传输方式连接到上游 MCP 服务器。您不需要指定上游服务器使用哪种传输方式。门户通过按顺序尝试多种连接策略来自动检测正确的传输方式：

如果连接尝试返回 404、405 或 406 错误，门户将回退到下一个策略。所有其他错误都将停止连接尝试。

除了上游服务器工具外，每个门户还向 MCP 客户端公开以下内置工具：

启用上下文优化时，会根据模式公开其他工具：

每个 MCP 客户端连接都会创建一个会话，该会话将一直持续到用户断开连接或会话因处于非活动状态而过期。会话在处于非活动状态 24 小时后过期。

在会话中，用户可以在不断开连接的情况下启用或停用单个服务器。服务器切换的范围仅限于该会话，不会影响同一门户上的其他用户或会话。

在某些语境中，MCP 服务器门户以前被称为 Agents Gateway。API 路径、Terraform 资源和内部代码库可能仍会使用 agents_gateway 或 agw 前缀。产品名称为 MCP server portals（MCP 服务器门户），仪表板导航为 AI controls（AI 控制）。

• 在 Cloudflare 上的活动域名
• 域使用完全设置或部分 (CNAME) 设置
• 在 Cloudflare Zero Trust 上配置的身份提供商

将单个 MCP 服务器添加到 Cloudflare Access，以便将其纳入集中管理。

若要添加 MCP 服务器：

1. 在 Cloudflare 仪表板 ↗中，转到 Zero Trust > Access controls（访问控制）> AI controls（AI 控制）。

2. 转到 **MCP servers（MCP 服务器）**选项卡。

3. 选择 Add MCP server（添加 MCP 服务器）。

4. 输入服务器的任意名称。

5. （可选）为 **Server ID（服务器 ID）**输入自定义字符串。

6. 在 HTTP URL（HTTP 地址） 中，输入您的 MCP 服务器的完整 URL。例如，如果您想添加 Cloudflare 文档 MCP 服务器 ↗，请输入 https://docs.mcp.cloudflare.com/mcp。

7. 添加 Access 策略以在 MCP 服务器门户中显示或隐藏该服务器。对于匹配 Allow（允许）策略的用户，该 MCP 服务器的链接才会出现在门户中。未通过 Allow 策略的用户将无法通过任何门户看到此服务器。

8. 选择 Save and connect server（保存并连接服务器）。

9. 如果 MCP 服务器支持 OAuth，您将被重定向以登录到您的 OAuth 提供商。您可以登录 MCP 服务器上的任何账户。用于进行身份验证的账户将用作该 MCP 服务器的管理员凭据。您可以配置 MCP 门户以使用此管理员凭据来发起请求。

Cloudflare Access 将验证服务器连接并检索资源、提示和工具的列表。服务器成功连接后，服务器状态将更改为 Ready（准备就绪）。现在您可以将该 MCP 服务器添加到 MCP 服务器门户中。

MCP 应用 (MCP Apps)——在其描述中声明了 UI 资源的工具——在成功连接到 MCP 服务器后也将可用。支持 MCP 应用的 MCP 客户端列表可在 扩展支持矩阵 (Extension Support Matrix) ↗ 中找到。

MCP 服务器状态表示 MCP 服务器与 Cloudflare Access 的同步状态。

当 MCP 服务器处于 Error 或 Sync Required 状态时，Cloudflare Access 会提供结构化信息以帮助您诊断问题。在仪表板中，将鼠标悬停在服务器的状态上以查看错误消息、错误类别（上游或连接）、HTTP 状态码以及 MCP 协议错误码（如果适用）。API 也会将相同的详细信息作为 error_details 对象返回：

导致服务器错误的常见原因包括 OAuth 凭据过期、服务器 URL 无法访问以及上游服务器配置错误。如果错误类型是 upstream_error，请检查 HTTP 和 MCP 错误码以确定上游服务器上的问题。如果类型为 unreachable，请确认服务器 URL 正确且可访问。

若要在 Cloudflare Access 中重新验证 MCP 服务器：

1. 在 Cloudflare 仪表板 ↗中，转到 Zero Trust > Access controls（访问控制）> AI controls（AI 控制）。
2. 转到 **MCP servers（MCP 服务器）**选项卡。
3. 选择您要重新验证的服务器，然后选择 Edit（编辑）。
4. 选择 Verify server（验证服务器）。

您将被重定向以登录到您的 OAuth 提供商。用于验证的账户将作为该 MCP 服务器的新管理员凭据。

Cloudflare Access 大约每两小时自动同步一次您的 MCP 服务器中的工具和提示。在同步期间，Cloudflare 使用管理员凭据连接到您的 MCP 服务器，并获取当前的工具和提示列表。如果管理员凭据的 OAuth 访问令牌已过期，Cloudflare 会在连接前使用存储的刷新令牌自动刷新它。

若要在 Zero Trust 中手动刷新 MCP 服务器：

1. 在 Cloudflare 仪表板 ↗中，转到 Zero Trust > Access controls（访问控制）> AI controls（AI 控制）。
2. 转到 **MCP servers（MCP 服务器）**选项卡，找到您要刷新的服务器。
3. 选择三个点 > Sync capabilities（同步功能）。

MCP 服务器页面将显示更新后的工具和提示列表。新的工具和提示会自动在 MCP 服务器门户中启用。

您还可以通过 API 触发同步。同步端点在同步后会返回当前的服务器状态，包括更新后的服务器状态、工具数量以及在同步失败时的错误详细信息。

当用户授权需要针对每个用户进行 OAuth 的上游 MCP 服务器时，门户会代表用户与上游服务器执行 OAuth 授权码流程。作为该流程的一部分，门户在上游服务器上注册一个回调 URL（redirect_uri）。在用户授权访问后，上游服务器将重定向到此 URL。

默认情况下，门户会使用您的门户域上的回调 URL：

https://<your-portal-hostname>/servers-callback

在较上游的 OAuth 提供商处将此 URL 添加为重定向 URI 的白名单。OAuth 提供商通常会对包括路径在内的完整 URI 进行精确匹配。

如果您启用了门户的共享回调 URL，门户将改用 Cloudflare 拥有的 URL：

https://oauth-callbacks.cloudflareaccess.com/cdn-cgi/access/outbound-oauth-callback

当上游供应商在其白名单中仅允许少量重定向 URI，或者您希望在多个门户中共享使用单个 Cloudflare 拥有的 URL 时，请使用共享回调 URL。只有在为门户显式启用时，才会使用共享回调 URL。

若要创建 MCP 服务器门户：

1. 在 Cloudflare 仪表板 ↗中，转到 Zero Trust > Access controls（访问控制）> AI controls（AI 控制）。

2. 选择 Add MCP server portal（添加 MCP 服务器门户）。

3. 输入门户的任意名称。

4. 在 Custom domain（自定义域） 下，为门户 URL 选择一个域。域必须属于您 Cloudflare 账户中的活动区域。您还可以选择指定一个子域。

5. 添加 MCP 服务器到门户。

6. （可选）在 **MCP servers（MCP 服务器）**下，配置通过门户可用的工具和提示。

7. （可选）为支持 OAuth 的服务器配置 Require user auth（要求用户身份验证）：

   • Enabled（已启用）：（默认）将提示用户使用其自己的登录凭据来与 MCP 服务器建立连接。
   • Disabled（已禁用）：连接到门户的用户将自动通过该服务器的管理员凭据访问 MCP 服务器。

8. 添加 Access 策略以定义可以连接到门户 URL 的用户。

9. 选择 Add MCP server portal（添加 MCP 服务器门户）。

10. （可选）为门户自定义登录体验。

现在，用户可以使用 MCP 客户端在 https://<subdomain>.<domain>/mcp 连接到门户。

Cloudflare Access 会为每个 MCP 服务器门户自动创建一个 Access 应用程序。您可以通过更新 Access 应用程序设置来自定义门户登录体验：

1. 在 Cloudflare 仪表板 ↗中，转到 Zero Trust > Access controls（访问控制）> Applications（应用程序）。
2. 找到您要配置的门户，然后选择三个点 > Edit（编辑）。
3. 为门户配置身份提供商：
   1. 转到 Authentication（身份验证）。
   2. 选择您要为应用程序启用的身份提供商。
   3. （推荐）如果您计划仅允许通过单个身份提供商进行访问，请启用 Apply instant authentication（应用即时身份验证）。最终用户将不会看到 Cloudflare Access 登录页面。相反，Cloudflare 将把用户直接重定向到您的 SSO 登录流程。
4. 自定义阻止页面：
   1. 转到 Additional settings（其他设置）。

   2. 自定义拦截页面：选择用户被拒绝访问应用程序时将看到的内容。

      • Cloudflare default（Cloudflare 默认）：重新加载登录页面，并在 Cloudflare Access 徽标下方显示拦截消息。默认消息为 That account does not have access，您也可以输入自定义消息。
      • Redirect URL（重定向 URL）：重定向到指定网站。
      • Custom page template（自定义页面模板）：显示托管在 Cloudflare One 中的自定义拦截页面。
5. 选择 Save（保存）。

当您将 MCP 服务器添加到门户时，默认情况下其所有工具和提示都会对门户用户可用。您可以自定义公开哪些工具和提示、使用别名重命名它们以及覆盖其描述。

若要对门户用户隐藏特定的工具或提示：

1. 在 Cloudflare 仪表板 ↗中，转到 Zero Trust > Access controls（访问控制）> AI controls（AI 控制）。
2. 找到您要配置的门户，然后选择三个点 > Edit（编辑）。
3. 在 **MCP servers（MCP 服务器）**下，找到您要管理其工具的服务器。
4. 关闭您想对用户隐藏的任何工具或提示旁边的切换开关。
5. 选择 Save（保存）。

关闭的工具将不会出现在门户的工具列表中。用户将无法调用它们。

默认情况下，MCP 服务器中的所有工具和提示在门户中都是可用的。您可以反转此行为，使所有工具默认隐藏，并且仅公开显式启用的工具。当 MCP 服务器有许多工具但您只想公开精选子集时，这很有用。

要通过 API 配置白名单，请在服务器到门户的映射上将 default_disabled 设置为 true，然后显式列出您想要在 updated_tools 中公开的工具：

{
	"servers": [
		{
			"id": "example-server",
			"default_disabled": true,
			"updated_tools": [
				{
					"name": "search_documents",
					"enabled": true
				},
				{
					"name": "list_projects",
					"enabled": true
				}
			]
		}
	]
}

将 default_disabled 设置为 true 后，门户用户只能使用 search_documents 和 list_projects。此服务器中的所有其他工具都将被隐藏。

别名使您能够在门户中为工具和提示提供更清晰的名称。使用别名可以：

• 用符合您组织术语的名称替换不清晰的工具名称。
• 添加或改进描述，以便 AI 代理选择正确的工具。
• 标准化门户中多个 MCP 服务器之间的命名。

别名名称必须为 1-40 个字符，且只能包含字母、数字、连字符和下划线。名称必须以字母数字字符开头和结尾。值必须符合 ^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$ 的格式。例如，search_customer_records 或 get-user-profile。同一服务器上不能有两个工具或提示共享相同的名称，无论该名称是别名还是原始的上游名称。

您可以在两个级别设置别名。门户级别的别名优先级高于服务器级别的别名。

当存在多个名称时，门户按以下顺序解析它们：portal_alias > server_alias > alias > 原始工具名称。

如果没有设置别名，门户将使用上游服务器的原始名称和描述。

自定义描述遵循相同的优先级。通过在 updated_tools 或 updated_prompts 的条目中包含 description 字段来设置描述。在 API 响应中，服务器级别的描述将作为 server_description 返回，门户级别的描述将作为 portal_description 返回。当两者都设置时，门户级别的描述优先于服务器级别的描述。

已修改的工具和提示将在仪表板中显示 **Modified（已修改）**标签。

向更新 MCP 门户端点发送一个 PUT 请求。为您想要重命名的每个工具或提示包含 alias 字段。

curl "https://api.cloudflare.com/client/v4/accounts/%7Baccount_id%7D/access/ai-controls/mcp/portals/%7Bid%7D" \
	--request PUT \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"servers": [
				{
						"server_id": "example-server",
						"updated_tools": [
								{
										"name": "original_tool_name",
										"enabled": true,
										"description": "A clearer description of what this tool does.",
										"alias": "renamed_tool"
								}
						],
						"updated_prompts": [
								{
										"name": "original_prompt_name",
										"enabled": true,
										"description": "An updated description for this prompt.",
										"alias": "renamed_prompt"
								}
						]
				}
		]
	}'

要设置适用于所有门户的服务器级别别名，请向更新 MCP 服务器端点发送具有相同 updated_tools 和 updated_prompts 字段的 PUT 请求。

要将工具或提示重置为其原始的上游名称，请在仪表板中打开该工具或提示的编辑模式窗口，然后选择“重置为服务器定义”。使用 API 时，请在 updated_tools 或 updated_prompts 的相应条目中省略 alias 字段。

MCP 客户端会收到起别名后的名称和描述，而不是原始名称。最终用户不会看到原始名称。

如果您在用户拥有活动会话时更改了别名，则该用户必须重新验证才能看到更新。有关重新验证选项，请参阅管理门户会话。

通过门户公开的所有工具和提示都会自动以服务器 ID 作为前缀添加命名空间。格式为 {server_id}_{original_name}。例如，在 ID 为 github 的服务器上名为 list_issues 的工具在门户中将显示为 github_list_issues。当多个 MCP 服务器公开具有相同名称的工具时，这可以防止名称冲突。

提示遵循相同的模式。在 ID 为 github 的服务器上名为 summarize 的提示在门户中显示为 github_summarize。

用于命名空间的服务器 ID 来自您在添加 MCP 服务器时设置的 Server ID（服务器 ID） 字段。您可以在设置过程的第 5 步中输入自定义服务器 ID，或者让 Cloudflare 自动生成一个。

如果您计划通过门户公开服务器，请选择简短且具有描述性的服务器 ID。服务器 ID 会成为 MCP 客户端和 AI 代理所看到的每个工具名称的一部分。

门户仅在第一个下划线处拆分已添加命名空间的名称。第一个下划线之前的全部内容是服务器 ID，其后的全部内容是工具或提示名称。这意味着工具名称可以包含下划线而不会产生歧义。

由于拆分发生在第一个下划线处，因此服务器 ID 本身不能包含下划线。当您需要一个包含多个单词的服务器 ID 时，请改用连字符（例如，my-server）。

如果您使用别名重命名了工具，该别名将在已包含命名空间的格式中替换原始工具名称。服务器 ID 前缀仍然适用。

例如，如果您将 ID 为 github 的服务器上的工具 list_issues 的别名设置为 issues，那么命名空间化名称将变为 github_issues。

当代码模式处于活动状态时，门户会应用额外的转换，以使包含命名空间的工具名称能够安全地用作 JavaScript 标识符。命名空间化名称中的连字符和点会被替换为下划线，以数字开头的名称会获得 _ 前缀，JavaScript 保留字会获得 _ 后缀。例如，ID 为 my-server 且包含名为 get-data 的工具的服务器在代码模式沙箱中将显示为 my_server_get_data。

这种净化是自动进行的。作为最终用户使用代码模式时，您不需要调用任何辅助函数。

如果您正在使用 Agents SDK 构建 MCP 客户端，该 SDK 提供了用于处理服务器 ID 和工具名称的辅助函数：

• normalizeServerId（自 agents/mcp/client 导出）将调用者提供的服务器 ID 规范化为安全字符串。例如，\"GitHub MCP!\" 会变为 \"github-mcp\"。当您向 addMcpServer() 传递 id 选项时，SDK 会自动调用此函数。

• sanitizeToolName（自 @cloudflare/codemode 导出）通过将连字符和点替换为下划线，将工具名称转换为有效的 JavaScript 标识符。这在代码模式上下文中会被自动调用。有关详细信息，请参阅代码模式 SDK 参考。

除了上游 MCP 服务器工具外，门户还公开了其自己的内置工具，让 AI 代理能够在会话期间管理服务器连接并发现工具。这些工具使用 portal_ 前缀，并且与任何上游服务器无关。

无论连接模式如何，以下工具在每个门户会话中都是可用的：

这些工具为本指南后面介绍的会话管理功能提供支持。当您请求启用服务器、停用服务器或返回服务器选择页面时，AI 代理会自动调用它们。

当您使用 optimize_context 查询参数连接时，门户会公开用于发现和调用上游工具的附加工具：

在启用代码模式进行连接时，门户会将所有上游工具替换为两个代码执行工具：

有关为这些工具编写代码的详细信息，请参阅代码模式 SDK 参考。

除了仪表板之外，您还可以使用 Cloudflare API 以编程方式管理 MCP 服务器门户。以下示例展示了常见操作。

curl "https://api.cloudflare.com/client/v4/accounts/%7Baccount_id%7D/access/ai-controls/mcp/portals" \
	--request GET \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

curl "https://api.cloudflare.com/client/v4/accounts/%7Baccount_id%7D/access/ai-controls/mcp/portals" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"name": "Engineering Portal",
		"hostname": "mcp.example.com",
		"allow_code_mode": true,
		"secure_web_gateway": false
	}'

curl "https://api.cloudflare.com/client/v4/accounts/%7Baccount_id%7D/access/ai-controls/mcp/servers" \
	--request GET \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

curl "https://api.cloudflare.com/client/v4/accounts/%7Baccount_id%7D/access/ai-controls/mcp/servers" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"name": "GitHub MCP Server",
		"hostname": "https://github-mcp.example.workers.dev/mcp",
		"auth_type": "oauth"
	}'

auth_type 字段接受以下值：

若要手动触发上游 MCP 服务器的工具和提示的同步：

curl "https://api.cloudflare.com/client/v4/accounts/%7Baccount_id%7D/access/ai-controls/mcp/servers/%7Bserver_id%7D/sync" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

curl "https://api.cloudflare.com/client/v4/accounts/%7Baccount_id%7D/access/ai-controls/mcp/portals/%7Bid%7D" \
	--request DELETE \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

您可以使用 Cloudflare Terraform 提供商管理 MCP 服务器门户。使用 cloudflare_zero_trust_access_mcp_server_portal 资源以编程方式创建和配置门户。

以下示例创建了一个包含 CNAME 记录的 MCP 服务器门户：

# 创建 MCP 服务器门户
resource "cloudflare_zero_trust_access_mcp_server_portal" "example" {
  account_id = var.cloudflare_account_id
  name       = "Engineering Portal"
  hostname   = "mcp.example.com"
}

# 必需：为门户主机名创建 CNAME 记录
resource "cloudflare_dns_record" "mcp_portal" {
  zone_id = var.cloudflare_zone_id
  name    = "mcp"
  content = "gateway.agents.cloudflare.com"
  type    = "CNAME"
  proxied = true
}

有关受支持资源参数的完整列表，请参阅 Terraform 提供商文档 ↗。

默认情况下，所有 MCP 服务器门户都会启用代码模式（Code Mode）。它通过将门户中的所有工具折叠为单个 code 工具来减少上下文窗口的使用。连接的 AI 代理不是为每个上游 MCP 服务器工具加载单独的工具定义，而是编写调用类型化 codemode.* 方法的 JavaScript。生成的代码在隔离的 Dynamic Worker 环境中运行，这使得身份验证凭据和环境变量不会进入模型上下文中。

要使用代码模式，MCP 客户端必须在连接到门户 URL 时对其发起请求。有关所需的查询参数，请参阅使用代码模式连接。

代码模式适用于聚合了许多 MCP 服务器或公开了大量工具的服务器门户。无论通过门户可用的工具有多少，上下文窗口的使用量都保持固定。

要使用代码模式，请在从 MCP 客户端连接时将 ?codemode=search_and_execute 查询字符串参数附加到您的门户 URL。

例如，如果您的门户 URL 是 https://<subdomain>.<domain>/mcp，请连接到：

https://<subdomain>.<domain>/mcp?codemode=search_and_execute

对于具有服务器配置文件的主机 MCP 客户端，请使用带有查询字符串参数的门户 URL：

{
	"mcpServers": {
		"example-portal": {
			"command": "npx",
			"args": [
				"-y",
				"mcp-remote@latest",
				"https://<subdomain>.<domain>/mcp?codemode=search_and_execute"
			]
		}
	}
}

当代码模式处于活动状态时，门户向连接的 MCP 客户端播发单个 code 工具。AI 代理通过检查 Dynamic Worker 环境中的类型化方法签名来发现可用的工具，并将多个工具调用编写进单次代码执行中。

有关使用代码模式进行构建的更多信息，请参阅代码模式 SDK 参考。

若要为门户关闭代码模式：

启用 Gateway 路由后，指向由您的 MCP 服务器门户所保护的 MCP 服务器的调用将通过 Cloudflare Gateway 进行路由。这使得门户流量与您组织的其他 HTTP 流量一起显示在您的 Gateway HTTP 日志中。然后，您可以创建数据防泄露（DLP）策略，以检测并阻止将敏感数据发送到您的上游 MCP 服务器。

当用户通过门户调用工具时，门户将请求代理到上游 MCP 服务器。启用 Gateway 路由后，此传出请求会在到达上游服务器之前通过 Cloudflare Gateway。Gateway 会检查流量并应用任何匹配的 HTTP 策略，包括 DLP 扫描。

因为门户流量通过 Gateway 进行路由，它也遵循 Gateway 出口策略（egress policies）。这意味着上游 MCP 服务器的传出请求将源自您的专用出口 IP 或 Gateway IP 范围，而不是通用的 Cloudflare IP。如果您的上游 MCP 服务器按源 IP 限制入站流量（例如限制为 VPN 或公司 IP 范围），则可以使用出口策略来确保门户流量来自一组可预测的 IP。

DLP 检查需要 Gateway 解密 TLS 流量。对于门户流量，Gateway 会自动解密并检查有效负载——您无需开启账户级别的 TLS 解密设置。因为门户终止了来自 MCP 客户端的连接并通过 Gateway 重新发起请求，所以无论全局 TLS 解密设置是否开启，Gateway 都会解密门户流量。

此自动解密仅适用于流经门户的流量。要检查不通过门户的 MCP 流量——例如，运行 WARP 客户端的设备上的代理直接连接到上游 MCP 服务器——您必须像对任何其他 HTTP 策略一样开启 TLS 解密。

Gateway 路由仅支持 Streamable HTTP ↗ 连接。如果上游 MCP 服务器配置了服务器发送事件（SSE）端点（以 /sse 结尾的 URL），门户将自动尝试改用 Streamable HTTP 进行连接。如果上游服务器不支持 Streamable HTTP，启用 Gateway 路由后连接将会失败。

若要将 MCP 服务器门户流量路由到 Gateway：

1. 在 Cloudflare 仪表板 ↗中，转到 Zero Trust > Access controls（访问控制）> AI controls（AI 控制）。
2. 找到您要配置的门户，然后选择三个点 > Edit（编辑）。
3. 在 **Basic information（基本信息）**下，启用 Route traffic through Cloudflare Gateway（通过 Cloudflare Gateway 路由流量）。
4. 选择 Save（保存）。

门户流量现在将显示在您的 Gateway HTTP 日志中。若要应用 DLP 扫描，请创建 Gateway HTTP 策略。

要扫描敏感数据流量，请创建 Gateway HTTP 策略，使其同时匹配 MCP 服务器和预定义或自定义的 DLP 配置文件。

用于 MCP 门户流量的 Gateway HTTP 策略必须显式针对上游 MCP 服务器。确保您的策略匹配上游 MCP 服务器的主机名（例如 example-mcp-server.example.workers.dev），而不是门户 URL（<subdomain>.<domain>）。

例如，以下策略会阻止包含凭据与机密或财务信息的流量：

当工具调用匹配阻止（Block）DLP 策略时，Gateway 将阻止该调用，并且门户会作为错误将阻止情况显现给 MCP 客户端，而不是完成该工具调用。这双向适用：

• 工具调用请求：如果代理发送给工具的数据符合 DLP 配置文件，Gateway 将阻止传出请求，并且代理将收到指出请求已被阻止的错误。
• 工具调用响应：如果上游服务器返回的数据符合 DLP 配置文件，Gateway 将阻止响应，并且门户将返回错误，而不是匹配的内容。

代理可以重试该请求，但直到内容不再符合策略，请求才会停止被阻止。

• DLP AI 提示配置文件不适用于 MCP 服务器门户流量。AI 提示配置文件是专为特定 Web 客户端 API 路径设计的，与 MCP 协议格式不匹配。请改用标准 DLP 配置文件。
• 不支持通过 Gateway 进行 SSE 传输。如果您的上游 MCP 服务器仅支持 SSE，Gateway 路由将不适用于该服务器。
• 工具和提示的后台同步不通过 Gateway 路由。仅检查实时的用户请求。

用户可以使用 Workers AI Playground ↗、MCP 检查器 (MCP inspector) ↗ 或其他支持远程 MCP 服务器的 MCP 客户端连接到运行在 https://<subdomain>.<domain>/mcp 的 MCP 服务器。

若要在 Workers AI Playground 中进行测试：

1. 转到 Workers AI Playground ↗。
2. 在 **MCP Servers（MCP 服务器）**下，为门户 URL 输入 https://<subdomain>.<domain>/mcp。
3. 选择 Connect（连接）。
4. 在弹出的窗口中，登录到您的 Cloudflare Access 身份提供商。
5. 弹出窗口将列出门户中需要身份验证的 MCP 服务器。对于每一个 MCP 服务器，选择 **Connect（连接）**并按照登录提示操作。
6. 选择 **Done（完成）**以完成门户身份验证流程。

Workers AI Playground 将显示 **Connected（已连接）**状态并列出可用工具。现在，您可以要求 AI 模型使用可用工具来完成任务。发往 MCP 服务器的请求将显示在您的门户日志中。

对于具有服务器配置文件的主机 MCP 客户端，我们建议将 npx 命令与 mcp-remote@latest 参数结合使用：

{
	"mcpServers": {
		"example-mcp-server": {
			"command": "npx",
			"args": [
				"-y",
				"mcp-remote@latest",
				"https://<subdomain>.<domain>.com/mcp"
			]
		}
	}
}

我们不建议使用 serverURL 参数，因为这可能会导致门户会话的创建和管理出现问题。

当用户在浏览器中访问门户域（https://<subdomain>.<domain>/）时，门户将显示一个包含连接详细信息和设置说明的主页。

主页显示：

• 门户名称和您的组织品牌标识（如果在 Cloudflare Access 中进行了配置）
• 带有复制按钮的 MCP 端点 URL
• 针对 Claude Desktop、Workers AI Playground、OpenCode、Windsurf 以及其他包含特定操作系统文件路径的 MCP 客户端的单个客户端连接说明

已通过身份验证的用户会在会话栏中看到其电子邮件地址和 **Sign out（注销）**按钮。未通过身份验证的用户仍可以查看主页和连接说明。

若要结束门户会话，请从门户主页（https://<subdomain>.<domain>/）中选择 Sign out（注销）。注销流程：

1. 撤销为您的用户授予的所有门户级别 OAuth 授权。
2. 删除与您的会话相关联的所有上游 MCP 服务器的 OAuth 状态。
3. 重定向到 Cloudflare Access 注销流。

注销后，门户将显示一个确认页面，其中包含已撤销会话的摘要。若要重新连接，请访问门户主页并再次进行身份验证。

您可以使用 Access 服务令牌连接到 MCP 门户以进行机器对机器访问。服务令牌会绕过基于浏览器的 OAuth 流程，并使用 CF-Access-Client-Id 和 CF-Access-Client-Secret 标头进行身份验证。

服务令牌会话会获得两次授权：一次在门户 URL 处，另一次在它尝试通过门户访问的每个上游 MCP 服务器处。这两次检查都需要匹配的 Service Auth（服务身份验证）策略。

如果链接 the 的 MCP 服务器没有与该令牌匹配的 Service Auth 策略，那么该服务器将从聊天机器人的工具列表中隐藏。

1. 在您的 Zero Trust 账户中创建服务令牌。
2. 打开门户的 Access 应用程序，添加包含该服务令牌的 Service Auth 策略。
3. 对于您希望聊天机器人访问的每个上游 MCP 服务器：
   1. 打开服务器的 Access 应用程序，添加包含相同服务令牌的 Service Auth 策略。
   2. 打开门户并编辑服务器。关闭 Require user auth（要求用户身份验证），以便门户对该服务器使用管理员凭据。
4. 从您的 MCP 客户端使用服务令牌标头进行连接。

对于 CLI 客户端，直接设置标头：

curl https://<subdomain>.<domain>/mcp \
  -H "CF-Access-Client-Id: <CLIENT_ID>" \
  -H "CF-Access-Client-Secret: <CLIENT_SECRET>"

对于 mcp-remote，使用 --header 传递标头：

{
	"mcpServers": {
		"example-portal": {
			"command": "npx",
			"args": [
				"-y",
				"mcp-remote@latest",
				"https://<subdomain>.<domain>/mcp",
				"--header",
				"CF-Access-Client-Id: <CLIENT_ID>",
				"--header",
				"CF-Access-Client-Secret: <CLIENT_SECRET>"
			]
		}
	}
}

MCP 服务器门户需要基于浏览器的身份验证流程。MCP 门户目前不支持设备身份验证（即在没有浏览器重定向的情况下从 Cloudflare One 客户端获取身份）。用户在首次连接时必须在浏览器中完成 Access 登录流程。

MCP 服务器门户支持上下文优化选项，这些选项可以减少模型上下文窗口中工具定义所消耗的令牌数量。当门户聚合了许多 MCP 服务器或公开了大量工具的服务器时，这些选项非常有用。

要使用上下文优化，在从 MCP 客户端连接时，请将 optimize_context 查询参数附加到您的门户 URL 中。

minimize_tools 选项会从所有上游工具中剥离工具描述和 input 架构，仅留下它们的名称。门户公开了一个特殊的 query 工具，代理可以使用它按需搜索和检索完整的工具定义。代理可以在不预先加载所有定义的情况下发现工具。

此选项最多可节省 5 倍的令牌使用量，但在使用前查询工具定义会增加少量的开销。

要结合 minimize_tools 连接，请使用以下门户 URL：

https://<subdomain>.<domain>/mcp?optimize_context=minimize_tools

对于具有服务器配置文件的主机 MCP 客户端：

{
	"mcpServers": {
		"example-portal": {
			"command": "npx",
			"args": [
				"-y",
				"mcp-remote@latest",
				"https://<subdomain>.<domain>/mcp?optimize_context=minimize_tools"
			]
		}
	}
}

search_and_execute 选项会隐藏所有上游工具，并且只向代理公开两个工具：query 和 execute。query 工具用于搜索和检索工具定义。execute 工具运行上游工具。生成的代码在隔离的 Dynamic Worker 环境中运行，这使得身份验证凭据和环境变量不会进入模型上下文中。

此选项将门户工具的初始令牌成本降低到很小的常数，无论有多少可用工具。然而，代理会变得完全依赖于 query 来发现工具，然后才能调用它们。

要结合 search_and_execute 连接，请使用以下门户 URL：

https://<subdomain>.<domain>/mcp?optimize_context=search_and_execute

对于具有服务器配置文件的主机 MCP 客户端：

{
	"mcpServers": {
		"example-portal": {
			"command": "npx",
			"args": [
				"-y",
				"mcp-remote@latest",
				"https://<subdomain>.<domain>/mcp?optimize_context=search_and_execute"
			]
		}
	}
}

有关 search_and_execute 背后的代码模式（Code Mode）的更多信息，请参阅代码模式。

一旦连接到门户，用户无需离开其 MCP 客户端即可管理其上游 MCP 服务器会话。门户使用 MCP 引导 (MCP elicitations) ↗ 提供一个服务器选择页面，在其中您可以启用或停用服务器、注销单个服务器以及重新进行验证。

要在活动会话期间管理您的服务器连接，请让您的 AI 代理带您返回到服务器选择页面。例如，向您的代理提示：

带我返回到服务器选择页面。

门户会返回一个授权 URL。在您的 Web 浏览器中打开此 URL 以访问服务器选择页面：

https://<subdomain>.<domain>/authorize?elicitationId=<ELICITATION_ID>

在此页面中，您可以：

• 启用或停用服务器 — 启用或关闭单个上游 MCP 服务器。停用服务器将从活动会话中移除其工具，从而减少上下文窗口使用量。
• 注销并重新验证 — 注销服务器并重新登录（如果您需要更改服务器可访问的数据）。例如，您可能需要使用不同的权限重新进行身份验证。

您还可以直接从 MCP 客户端启用或停用特定的服务器，而无需访问服务器选择页面。例如：

启用 Wiki 服务器。

停用我的 Jira 服务器。

门户将立即切换服务器并更新活动工具列表。停用服务器会从会话中移除其工具，从而减少上下文窗口的使用量。

当上游 MCP 服务器令牌过期时，门户将提示您在 MCP 客户端内进行重新验证。在浏览器中打开提供的 URL 并完成登录以恢复会话。

如果您的 MCP 客户端没有显示重新验证提示，您可以手动清除缓存的凭据：

rm -rf ~/.mcp-auth

在清除凭据后，请从您的 MCP 客户端重新连接到门户。

当管理员向门户添加新的上游 MCP 服务器时，门户会自动提示已连接的用户对该新服务器进行授权。门户会批量处理管理员所做的更改，并将您重定向到授权流程中一次，而不是因每次单独的服务器更新而中断您的操作。

门户日志允许您通过 MCP 服务器门户监视用户活动。您可以基于每个门户或每个服务器来查看日志。

1. 在 Cloudflare 仪表板 ↗中，转到 Zero Trust > Access controls（访问控制）> AI controls（AI 控制）。
2. 找到您要查看其日志的门户或服务器，然后选择三个点 > Edit（编辑）。
3. 选择 Logs（日志）。

您可以使用 Logpush 将 MCP 门户日志自动导出到第三方存储目的地或安全信息和事件管理（SIEM）工具中。这使您能够与现有的安全工作流集成，并按业务所需的时间保留日志。

若要为 MCP 门户日志设置 Logpush 作业，请参阅 Logpush 集成。有关可用日志字段的列表，请参阅 MCP 门户日志。

MCP 服务器门户具有以下已知限制：

• 仅支持远程 HTTP MCP 服务器。 仅使用 stdio 传输方式 ↗（例如 github/github-mcp-server）的 MCP 服务器不公开远程 HTTP 端点，因而无法被添加到 MCP 服务器门户。要使用仅 stdio 的服务器，您必须将其自托管在 HTTP 端点之后，并使用 Bearer 令牌或自定义标头进行身份验证。

• 某些 MCP 服务器会阻止基于代理的客户端。 某些 MCP 服务器会拒绝来自像 MCP 服务器门户这样的基于代理的客户端的请求，并在注册端点上返回 403 错误。在这些提供商将 Cloudflare 添加为受支持的 MCP 客户端之前，这些服务器与 MCP 服务器门户不兼容。

• 并非所有 MCP 服务器都支持 OAuth 动态客户端注册。 不支持 OAuth 动态客户端注册 ↗的 MCP 服务器不能使用门户's 的 OAuth 身份验证流程。对于这些服务器，请选择 **Custom Headers（自定义标头）**作为身份验证方法，并改用提供静态凭据（例如 API 密钥或个人访问令牌）。

• 管理员 OAuth 令牌可能会静默过期。 用于验证 MCP 服务器的管理员凭据受上游提供商令牌过期策略的约束。当令牌过期时，服务器状态将更改为 Error 或 Sync Required，并且该服务器不会出现在最终用户的门户中。管理员不会在此发生时收到通知。请定期检查服务器状态并重新验证显示错误的服务器。

• 每个门户最多支持 40 个 MCP 服务器。 如果您需要将超过 40 个服务器聚合到单个门户中，请联系您的 Cloudflare 账户团队以请求更高的限制。当您接近限制时，仪表板会显示警告。

当通过门户授权服务器时，MCP 服务器会使用不支持以下 Access 策略功能的专用 Access 应用程序类型（mcp）。

• 独立 MFA — 无论是否启用了 MFA 全局强制执行，或者是否为服务器分配了 MFA 策略，用户在授权服务器时都不会被提示通过 Cloudflare Access 执行 MFA。
• 目的理由 — 用户在授权服务器时不会被提示提供目的理由。
• 临时身份验证 — 当用户授权服务器时，用户不会被提示申请访问权限，审批者也不会收到审批申请。

这些限制仅适用于正在通过门户进行授权的服务器。Access 策略选择器（如电子邮件、组、国家/地区和设备状态检查）仍将强制执行。

对于非通过门户授权的服务器，仍将强制执行独立 MFA、目的理由和临时身份验证。

1. MCP 门户和服务器都必须附有 Access 策略。确保分配给门户的所有 MCP 服务器都有其各自关联的策略。
2. 服务器的管理员身份验证可能已过期。检查 服务器状态 是否为 Ready（准备就绪）。如果状态显示为 **Error（错误）**或 Sync Required（需要同步），请重新验证服务器。

1. 验证门户是否已分配 Access 策略。
2. 验证门户 URL 是否没有任何应用的 Workers、页面规则 (Page Rules)、自定义主机名定义或任何其他可能干扰其连接到 MCP 客户端能力的配置。

522 错误表示 Cloudflare 无法访问门户的原点。这通常意味着门户主机名的 DNS 记录缺失或配置错误。

1. 验证是否存在将您的门户子域指向 gateway.agents.cloudflare.com 的 CNAME 记录。
2. 确保在 Cloudflare DNS 中将 CNAME 记录的 **Proxy status（代理状态）**开启。
3. 如果您使用 API 或 Terraform 提供商创建了门户，您必须单独创建 DNS 记录。与仪表板不同，API 和 Terraform 提供商不会自动创建 DNS 记录。

Waiting 状态表示 Cloudflare 正在尝试连接到上游 MCP 服务器并获取其工具和提示。如果服务器卡在此状态：

1. 验证上游 MCP 服务器 URL 是否正确且服务器可访问。
2. 检查上游服务器是否支持 Streamable HTTP ↗ 或 SSE 传输方式。门户会自动尝试多种连接策略。
3. 如果服务器需要身份验证，通过重新验证服务器来验证管理员凭据是否有效。
4. 选择三个点 > **Sync capabilities（同步功能）**以手动重试连接。

Stale 状态表示在上次同步尝试期间无法刷新服务器的管理员凭据。对于拥有自己 OAuth 令牌的用户（启用了 Require user auth（要求用户身份验证） 的服务器），该服务器的工具可能仍可使用，但管理员凭据需要刷新。

若要解决此问题，请使用有效的管理员凭据重新验证服务器。

1. 如果服务器使用单用户 OAuth（开启了 Require user auth（要求用户身份验证）），则用户的 OAuth 令牌可能已过期。要求用户在其 MCP 客户端中重新验证服务器。
2. 如果服务器使用管理员凭据，请检查服务器状态。状态为 **Error（错误）**或 **Sync Required（需要同步）**表示需要刷新管理员凭据。
3. 如果用户最近更改了上游服务的权限（例如撤销了 OAuth 范围），他们将需要重新进行身份验证。

invalid_redirect_uri、invalid_client_metadata 或 Redirect URI not allowed 等错误表示上游 MCP 服务器拒绝了门户在 OAuth 流程中注册的回调 URL。有关如何确定回调 URL 的背景信息，请参阅上游 OAuth 回调 URL。

1. 默认情况下，上游提供商必须在白名单中允许将 https://<your-portal-hostname>/servers-callback 作为重定向 URI（例如，https://my-portal.example.com/servers-callback）。OAuth 提供商通常会对包含路径在内的完整 URI 进行精确匹配。如果您不控制白名单，请联系上游 MCP 服务器供应商。
2. 如果门户配置为使用共享的 Cloudflare 回调 URL，上游提供商则必须在白名单中允许 https://oauth-callbacks.cloudflareaccess.com/cdn-cgi/access/outbound-oauth-callback。

1. 验证上游 MCP 服务器是否支持 Streamable HTTP 传输方式。不支持通过 Gateway 进行 SSE 传输。
2. 如果上游服务器 URL 以 /sse 结尾，门户会自动尝试改用 /mcp 路径上的 Streamable HTTP 进行连接。如果服务器不支持此路径，连接将失败。
3. 检查 Gateway HTTP 日志以了解 DLP 阻止事件。如果 DLP 策略阻止了流量，门户会向 MCP 客户端返回一个带有 DLP 规则 ID 的错误。

1. 确保您使用的是最新版本的 mcp-remote。运行 npx -y mcp-remote@latest 进行更新。
2. 在您的 MCP 客户端配置中使用 command 和 args 格式，而不是 serverURL 参数。serverURL 参数可能会导致门户会话创建出现问题。
3. 如果身份验证重复失败，通过运行 rm -rf ~/.mcp-auth 并重新连接来清除缓存的凭据。

门户主页显示您的 Access 组织名称和品牌标识。如果显示的名称不正确：

1. 在 Cloudflare 仪表板 ↗中，转到 Zero Trust > Settings（设置）> General（常规）> Team name（团队名称）。
2. 更新您的团队名称。该更改将在用户下次访问门户主页时生效。