跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

MCP 服务器门户

最后更新 查看 MarkdownAgent 设置

MCP server portal 将多个 Model Context Protocol (MCP) server ↗ 集中到单个 HTTP 端点。

MCP client 通过 MCP portal 连接,以访问内部 MCP server 和 SaaS MCP server。

本指南介绍如何将 MCP server 添加到 Cloudflare Access、创建具有自定义工具和策略的 MCP portal,以及如何使用 MCP client 将用户连接到 portal。

主要功能

MCP server portal 提供以下功能:

  • 简化对多个 MCP server 的访问:MCP server portal 同时支持未经身份验证的 MCP server,以及使用 OAuth 保护的 MCP server(例如通过 Access for SaaS 或第三方 OAuth provider 进行保护)。用户通过 Cloudflare Access 登录 portal URL,之后系统会提示用户分别向每个需要 OAuth 的 server 进行身份验证。
  • MCP 协议兼容性:portal 支持无状态 MCP 2026-07-28,以及更早的 2025 Streamable HTTP client 和 server。portal 会为每个连接选择受支持的协议,无需配置协议设置。
  • 为每个 portal 自定义工具:管理员可以选择希望通过 portal 向用户提供的特定工具和 prompt 模板,使 MCP portal 适应具体用例。这样,用户可以访问经过筛选的工具和 prompt 集;向 AI 模型暴露的外部上下文越少,AI 响应通常越好。
  • 工具和 prompt 别名:管理员可以在 portal 或 server 级别重命名工具和 prompt 并编辑其描述,而无需修改上游 MCP server。别名可帮助最终用户找到正确的工具,也能帮助 AI Agent 选择正确的工具。
  • 上下文优化:portal 支持通过查询参数选项最大限度减少或隐藏工具定义,从而降低上下文窗口用量。有关详细信息,请参阅优化上下文。
  • 支持非浏览器 client:MCP client 通过 managed OAuth 使用标准 OAuth 2.0 授权码流程向 portal 进行身份验证。此 managed OAuth 配置应用于 portal 的 Access application,与 portal 中各个 MCP server 使用的上游 OAuth 相互独立。非浏览器 client 会收到包含 WWW-Authenticate 标头的 401 响应,该标头指向 Access 的 OAuth 发现端点,而不是浏览器重定向。对于机器到机器访问,你也可以使用 Access service token 进行连接。
  • Code Mode:Code Mode 将所有上游工具合并为两个工具,用于搜索和执行代码。AI Agent 编写 JavaScript,调用每个工具的类型化方法。代码在隔离的 Dynamic Worker 环境中运行。管理员可以控制 Code Mode 是不可用、可选、默认启用还是强制使用。有关配置和连接说明,请参阅 Code Mode。
  • 可观测性:用户的 AI Agent 连接到 portal 后,Cloudflare Access 会记录使用 portal 中工具发出的各个请求。你可以选择通过 Cloudflare Gateway 路由 portal 流量,以获得更丰富的 HTTP 日志记录和数据丢失防护 (DLP) 扫描。

工作原理

下图显示请求如何流经 MCP server portal。

请求流图,显示 MCP client 如何通过 Cloudflare Access 和 MCP server portal 连接到上游 MCP server,以及用于 DLP 检查的可选 Gateway 路径。
  1. MCP client 连接到 portal URL,并收到包含 OAuth 发现元数据的 401 响应。
  2. 用户通过其身份提供商在 Cloudflare Access 中进行身份验证,或使用 service token 标头。
  3. Access 验证用户身份,portal 返回已启用上游 server 中的可用工具。
  4. 用户调用工具时,portal 通过工具命名空间 识别目标 server,附加适当的凭据,并代理请求。如果启用了 Gateway 路由,请求会经过 Cloudflare Gateway,以进行 HTTP 日志记录和 DLP 检查。
  5. 上游 server 处理请求,并通过同一路径返回响应。

对于使用 Dynamic Client Registration (DCR) 的 server,工具和 prompt 的后台同步大约每两小时使用管理员凭据运行一次。启用 server 级 Gateway 路由后,DCR 和后台同步会通过 Gateway 路由。

传输

portal 在其 /mcp 端点接受无状态 MCP 2026-07-28 ↗ 和更早的 2025 Streamable HTTP client。portal 会根据每个请求选择协议。你无需配置协议版本。

portal 使用 Streamable HTTP ↗ 或 SSE ↗ 传输连接到上游 MCP server。对于 Streamable HTTP server,portal 会检查是否支持 MCP 2026-07-28,并在可用时使用无状态协议。如果上游 server 不支持该协议,portal 会在同一连接上回退到 2025 握手。SSE 连接始终使用旧版协议。

client 和上游协议的选择相互独立。例如,2025 client 可以通过 portal 连接到无状态上游 server。无状态 client 也可以连接到旧版上游 server。

你无需指定上游 server 使用的传输。portal 会按顺序尝试多种连接策略,自动检测正确的传输:

上游 URL 模式 连接策略(按顺序)
以 /mcp 结尾 仅 Streamable HTTP
以 /sse 结尾 SSE(如果启用了 Gateway 路由,则使用 Streamable HTTP)
所有其他 URL 先在原始 URL 上使用 Streamable HTTP,然后在原始 URL 上使用 SSE,接着在 {url}/mcp 上使用 Streamable HTTP,最后在 {url}/sse 上使用 SSE

如果连接尝试返回 404、405 或 406 错误,portal 会回退到下一种策略。所有其他错误都会终止连接尝试。

Client 身份标头

portal 向上游 MCP server 发送请求时,会添加用于标识下游 MCP client 的 X-Forwarded-User-Agent 标头。

portal 按以下顺序选择标头值:

来源 行为
clientInfo.name 当 MCP client 发送有效值时优先使用。portal 会先移除 (via mcp-remote <VERSION>) 后缀,再转发名称。
HTTP User-Agent 无法获取有效的 MCP client 信息时使用。
两者都不存在 portal 省略 X-Forwarded-User-Agent 并继续处理请求。

上游 server 可以在日志中记录此标头,或将其用于诊断。不要将其用于身份验证或授权,因为 MCP client 可以控制该值。

Portal 内置工具

除上游 server 工具外,每个 portal 还会向 MCP client 公开以下内置工具:

工具 说明
portal_list_servers 列出所有可用的上游 server,包括其 ID、名称以及当前是否启用。
portal_toggle_servers 打开基于 URL 的 server 选择页面,你可以在其中启用或停用 server。
portal_toggle_single_server 按 server ID 启用或停用单个 server,无需离开 MCP client。

启用上下文优化 后,系统会根据模式公开其他工具:

模式 其他工具
minimize_tools portal_query_tools — 按正则表达式模式搜索工具并返回完整定义。
search_and_execute portal_query_tools 和 portal_execute — 搜索工具并通过代理执行它们。

会话生命周期

MCP 2026-07-28 请求是无状态的,不会创建 MCP 协议 session。portal 会为用户的 portal 授权许可保留身份验证、server 选择和上游 OAuth 状态。

更早的 2025 client 会创建 session;该 session 会一直保留,直到用户断开连接,或因 24 小时无活动而过期。

用户无需断开连接即可启用或停用各个 server。对于无状态请求,server 开关会应用于使用同一 portal 授权许可的每个请求。对于旧版 client,开关的作用域限定为 MCP session。开关不会影响其他用户。

命名

在某些上下文中,MCP server portal 以前称为 Agents Gateway。API 路径、Terraform 资源和内部代码库可能仍使用 agents_gateway 或 agw 前缀。产品名称为 MCP server portals,仪表板导航项为 MCP Portals。

先决条件

添加 MCP server

将各个 MCP server 添加到 Cloudflare Access,以进行集中管理。

添加 MCP server:

  1. 在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls > MCP Portals。

  2. 转到 MCP servers 选项卡。

  3. 选择 Add MCP server。

  4. 为 server 输入任意名称。

  5. (可选)为 Server ID 输入自定义字符串。

  6. 在 HTTP URL 中,输入 MCP server 的完整 URL。例如,如果你要添加 Cloudflare Documentation MCP server ↗,请输入 https://docs.mcp.cloudflare.com/mcp。

  7. 添加 Access 策略,以在 MCP server portal 中显示或隐藏 server。只有匹配 Allow 策略的用户才能在 portal 中看到 MCP server 链接。未通过 Allow 策略的用户无法通过任何 portal 看到此 server。

  8. 在 OAuth credentials 下,选择 Automatic (recommended) 以使用 DCR。将仪表板 callback URL 添加到 OAuth provider 的重定向 URI allowlist。

  9. 选择 Save and connect server。

  10. 如果 MCP server 支持 OAuth,系统会将你重定向到 OAuth provider 进行登录。你可以登录 MCP server 上的任意账户。用于身份验证的账户将作为该 MCP server 的管理员凭据。你可以配置 MCP portal,使用此管理员凭据发出请求。

Cloudflare Access 将验证 server 连接并检索 prompt 和工具列表。server 成功连接后,server 状态将更改为 Ready。你现在可以将该 MCP server 添加到 MCP server portal。

连接私有 MCP server

MCP server portal 可以连接到仅在私有网络中可用的 MCP server。启用 server 级 Gateway 路由后,MCP server URL、OAuth 受保护资源元数据 ↗和 DCR 端点可以使用私有 hostname。OAuth 授权端点和 token 端点必须可通过公共 Internet 访问。

添加 server 前,请将其网络连接到 Cloudflare。使用 Cloudflare Tunnel 或其他 Cloudflare One connector。为 server 配置私有 hostname 路由或 CIDR 路由。

添加私有 MCP server:

  1. 按照添加 MCP server 中的步骤操作,并在 HTTP URL 中输入私有 URL。
  2. 启用 Route traffic through Cloudflare Gateway。私有 server 注册和功能同步需要此设置。
  3. 选择 Save and connect server。
  4. 如果需要,请完成上游 OAuth 流程。
  5. 等待 server 状态更改为 Ready。然后,你可以将 server 添加到 portal。

配置手动 OAuth 凭据

当上游 provider 不支持 OAuth Dynamic Client Registration ↗ 时,请使用手动 OAuth 凭据。此流程使用你在上游 provider 中注册的 OAuth application。

  1. 添加 MCP server,并将 OAuth 设为其身份验证方法。
  2. 在 Zero Trust > Access controls > MCP Portals 中,转到 MCP servers 选项卡。
  3. 找到 server,选择三个点 > Edit,然后转到 Authentication。
  4. 在 OAuth credentials 下,选择 Manual credentials。
  5. 复制显示的 Redirect URI to register at the upstream provider。将其添加到 OAuth application 允许的重定向 URI 中。有关详细信息,请参阅共享 Cloudflare callback URL。
  6. 选择 Discover OAuth endpoints。如果发现失败,请展开 Show OAuth endpoints (advanced),然后输入 Authorization endpoint 和 Token endpoint。你还可以输入可选的 Revocation endpoint 和 Issuer。
  7. 输入 OAuth application 的 Client ID 和 Client secret。
  8. (可选)输入以空格分隔的 Scope 值,以向用户请求这些 scope。
  9. (可选)输入 provider 所需的 Token endpoint auth method。支持的值为 client_secret_post 和 client_secret_basic。
  10. 选择 Save server。

Cloudflare 会加密存储 client secret,且不会通过仪表板或 API 返回该值。编辑 server 时,将 Client secret 留空即可保留现有值。要轮换 secret,请在上游 provider 中创建或激活替代值,输入新值,然后保存 server。

手动凭据要求每个用户单独进行身份验证。将 server 添加到 portal 时,请保持启用 Require user auth。在第一个用户完成上游 OAuth 之前,server 会一直处于 Waiting 状态。随后,Cloudflare 会检索 server 的工具和 prompt,并将其状态更改为 Ready。

MCP Apps

成功连接到 MCP server 后,也可以使用 MCP Apps ↗(即在其描述中声明 UI 资源的工具)。Extension Support Matrix ↗ 中提供支持 MCP Apps 的 MCP client 列表。

Server 状态

MCP server 状态表示该 server 在 Cloudflare Access 中的连接状态,以及工具和 prompt 的同步状态。

状态 说明
错误 无法访问 server,或 server 返回错误。请参阅错误详细信息以确定并修复原因。
需要同步 server 的 OAuth 凭据无法再刷新,需要重新进行身份验证。要修复此问题,请重新验证 server。
等待中 正在同步 server 的工具和 prompt。使用手动 OAuth 凭据的 server 会一直保持此状态,直到第一个用户完成上游 OAuth。
就绪 server 已成功连接,其工具和 prompt 已同步。此状态不能保证查询时 server 一定能连接或返回资源。

错误详细信息

当 MCP server 处于 Error 或 Sync Required 状态时,将鼠标悬停在仪表板中的状态上,即可查看可用的诊断信息。API 会在 error_details 对象中返回这些详细信息:

字段 说明
status_code MCP server 返回的 HTTP 状态码(如果有)。
mcp_code 如果 server 返回 MCP 错误,则为 MCP 协议错误代码。
retryable 错误是否可能为暂时性错误,以及是否值得重试连接。
is_upstream 如果错误由 MCP server 返回,则为 true;如果连接 MCP server 失败,则为 false。
cause 底层错误消息。

如果 is_upstream 为 true,请使用 status_code、mcp_code 和 cause 对 MCP server 进行故障排除。如果为 false,请验证 server URL 是否正确且可以访问。当 retryable 为 true 时重试同步;否则,请先修复报告的原因,再重试。仅当错误指向凭据过期或无效时,才重新验证 server。

重新验证 MCP server

要在 Cloudflare Access 中重新验证 MCP server:

  1. 在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls > MCP Portals。
  2. 转到 MCP servers 选项卡。
  3. 选择要重新验证的 server,然后选择 Edit。
  4. 选择 Authenticate server。

系统会将你重定向到 OAuth provider 进行登录。用于身份验证的账户将作为此 MCP server 的新管理员凭据。

同步 MCP server

对于使用 DCR 的 server,Cloudflare Access 大约每两小时同步一次工具和 prompt。同步期间,Cloudflare 使用管理员凭据连接到 MCP server,并获取当前工具和 prompt 列表。如果管理员凭据的 OAuth access token 已过期,Cloudflare 会先使用存储的 refresh token 自动刷新,再进行连接。

系统不会同步或存储资源。当 MCP client 发送 resources/list 请求时,portal 会从上游 server 实时获取资源。无法连接或响应的 server 会从结果中省略。

要在 Zero Trust 中手动刷新 MCP server:

  1. 在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls > MCP Portals。
  2. 转到 MCP servers 选项卡,找到要刷新的 server。
  3. 选择三个点 > Sync capabilities。

MCP server 页面将显示更新后的工具和 prompt 列表。默认情况下,新工具和 prompt 会自动启用。对于将 default_disabled 设为 true 的映射,它们会保持隐藏,直到明确启用。

你也可以通过 API 触发同步。同步端点会返回同步后的当前 server 状态,包括更新后的 server 状态、工具数量,以及同步失败时的错误详细信息。

上游 OAuth callback URL

MCP server portal 使用上游 OAuth callback URL 为管理员和最终用户授权,使其能够访问 MCP server。

OAuth provider 通常会精确匹配完整 URI,包括路径。

如果上游 OAuth provider 限制重定向 URI,请添加与 server 配置匹配的 URL:

OAuth 配置 是否启用 Use the Cloudflare-hosted OAuth callback? 需要在上游 provider 中加入 allowlist 的重定向 URI
自动 (DCR) 否 用于管理员授权的仪表板 callback URL。如果用户使用自己的凭据进行授权,还要为使用此 server 的每个 portal 添加 https://<your-portal-hostname>/servers-callback。
自动 (DCR) 是 用于管理员授权的仪表板 callback URL。如果用户使用自己的凭据进行授权,还要添加 https://oauth-callbacks.cloudflareaccess.com/cdn-cgi/access/outbound-oauth-callback。
手动 OAuth 凭据 不可用 https://oauth-callbacks.cloudflareaccess.com/cdn-cgi/access/outbound-oauth-callback。此配置不使用仪表板 DCR callback URL。

对于自动 (DCR) server,展开 Advanced settings 以访问 Use the Cloudflare-hosted OAuth callback 设置。

对于通过 API 配置的手动 OAuth,请在上游 provider 中注册共享 Cloudflare callback URL。将 is_shared_oauth_callback_enabled 设为 true。无论 registration_info.redirect_uris 的值如何,Cloudflare 都会使用共享 callback URL,因此你可以省略此字段。你无法覆盖共享 callback URL。

仪表板 callback URL

当 Cloudflare 使用 DCR 注册 OAuth client 时,仪表板使用以下 callback URL:

https://dash.cloudflare.com/<account-tag>/one/access-controls/ai-controls/mcp-server/oauth-callback/<server-id>

仪表板 callback URL 的作用域限定为账户和 server。

授权上游 MCP server 前,请将仪表板 callback URL 添加到 OAuth provider 的重定向 URI allowlist。否则,授权可能会失败。

即使启用了 Use the Cloudflare-hosted OAuth callback 设置,DCR 仍使用仪表板 callback URL。

最终用户绝不会使用仪表板 callback URL 授权上游 MCP server。

Portal callback URL

当用户授权需要每用户 OAuth 的上游 MCP server 时,portal 会代表用户与上游 server 执行 OAuth 授权码流程。在此流程中,portal 会向上游 server 注册 callback URL (redirect_uri)。用户授权访问后,上游 server 会重定向到此 URL。

关闭 Use the Cloudflare-hosted OAuth callback 设置时,portal 会使用你的 portal 域名上的 callback URL:

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

将 callback URL 添加到 OAuth provider 的重定向 URI allowlist。

当共享 callback 设置关闭时,自动 (DCR) server 应使用 /servers-callback,而不是 /server-callback。手动 OAuth server 则使用共享 Cloudflare callback URL。

共享 Cloudflare callback URL

在仪表板中使用手动 OAuth 凭据配置 MCP server 时,Cloudflare 会对仪表板授权和每用户授权使用以下共享 callback URL:

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

在仪表板中配置手动 OAuth 凭据时,Use the Cloudflare-hosted OAuth callback 设置不可用。

当 Cloudflare 使用 DCR 注册 OAuth client 时,启用 Use the Cloudflare-hosted OAuth callback,即可使用共享 callback URL 进行每用户授权。如果关闭此设置,每用户授权将使用 portal 作用域 callback URL。

如果上游 OAuth provider 限制允许的重定向 URI 数量,或者你希望一个 server 在多个 portal 中使用同一 callback URL,请使用共享 callback URL。无论是否启用 Use the Cloudflare-hosted OAuth callback 设置,DCR 仍会使用仪表板 callback URL 进行管理员授权。此设置默认关闭。请为每个使用 DCR 的 MCP server 分别配置。

要启用此设置,请转到 Zero Trust > Access controls > MCP Portals > MCP servers,添加或编辑使用 DCR 的 MCP server,然后在 Basic information > Advanced settings 下启用 Use the Cloudflare-hosted OAuth callback。

创建 portal

创建 MCP server portal:

  1. 在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls > MCP Portals。

  2. 选择 Add MCP server portal。

  3. 为 portal 输入任意名称。

  4. 在 Custom domain 下,从账户中的活跃 zone 选择一个域名。你也可以选择指定子域。

  5. 将 MCP server 添加到 portal。

  6. (可选)在 MCP servers 下,配置可通过 portal 使用的工具和 prompt。

  7. (可选)为支持 OAuth 的 server 配置 Require user auth:- Enabled:(默认)系统会提示用户使用自己的登录凭据与 MCP server 建立连接。- Disabled:连接到 portal 的用户将通过 server 的管理员凭据自动获得 MCP server 访问权限。

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

  9. 选择 Add an MCP server portal。

  10. (可选)自定义 portal 的登录体验。

用户现在可以使用 MCP client 在 https://<subdomain>.<domain>/mcp 连接到 portal。

自定义登录设置

Cloudflare Access 会自动为每个 MCP server portal 创建 Access application。你可以更新 Access application 设置,自定义 portal 登录体验:

  1. 在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls > Applications。
  2. 找到要配置的 portal,然后选择三个点 > Edit。
  3. 为 portal 配置身份提供商:
    1. 转到 Authentication(身份验证)。
    2. 选择要为 application 启用的身份提供商。
    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(保存)。

管理工具和 prompt

将 MCP server 添加到 portal 时,portal 用户默认可以使用其所有工具和 prompt。你可以自定义公开哪些工具和 prompt,使用别名重命名,并覆盖其描述。

停用单个工具或 prompt

向 portal 用户隐藏特定工具或 prompt:

  1. 在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls > MCP Portals。

  2. 找到要配置的 portal,然后选择三个点 > Edit。

  3. 在 Servers 下,选择 server 名称以打开其工具面板。

  4. 向下滚动到 Tools 部分,然后关闭要对用户隐藏的任何工具或 prompt 旁边的开关。

    MCP server 的工具面板显示工具列表,每个工具旁边都有一个开关。
  5. 选择 Save(保存)。

已停用的工具不会出现在 portal 的工具列表中。用户将无法调用这些工具。

使用 allowlist 模式

默认情况下,portal 中可以使用 MCP server 的所有工具和 prompt。你可以反转此行为,使所有功能默认隐藏,仅公开明确启用的工具和 prompt。当 MCP server 有很多功能,而你只想公开经过筛选的子集时,此功能非常有用。

要通过 API 配置 allowlist,请在 server 到 portal 的映射上将 default_disabled 设为 true,然后在 updated_tools 中明确列出要公开的工具。要公开 prompt,请以相同方式在 updated_prompts 中列出。

当 portal 更新包含 servers 时,提供的数组会替换完整的 server 到 portal 映射。请包含每个已附加的 server,并保留其现有映射字段。省略 server 会将其从 portal 中移除,省略映射字段会将该字段重置为默认值。

API request body (portal update)json
{
    "servers": [
        {
            "server_id": "example-server",
            "default_disabled": true,
            "updated_tools": [
                {
                    "name": "search_documents",
                    "enabled": true
                },
                {
                    "name": "list_projects",
                    "enabled": true
                }
            ]
        }
    ]
}

将 default_disabled 设为 true 后,portal 用户只能使用 search_documents 和 list_projects。此 server 的所有其他工具和所有 prompt 都将隐藏。

使用别名重命名工具和 prompt

别名可让你在 portal 中为工具和 prompt 指定更清晰的名称。使用别名可以:

  • 将含义不清的工具名称替换为符合组织术语的名称。
  • 添加或改进描述,以便 AI Agent 选择正确的工具。
  • 统一 portal 中多个 MCP server 的命名。

别名长度必须为 1-40 个字符,并且只能包含字母、数字、连字符和下划线。名称必须以字母或数字开头和结尾。值必须匹配 ^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$。例如,search_customer_records 或 get-user-profile。同一 server 上的两个工具或 prompt 不能使用相同名称,无论该名称是别名还是原始上游名称。

别名优先级

你可以在两个级别设置别名。portal 级别别名的优先级高于 server 级别别名。

级别 (Level) 字段 范围
Server 级别 alias 应用于包含此 server 的所有 portal
Portal 级别 portal_alias 仅应用于特定 portal;覆盖 server 级别设置

存在多个名称时,portal 按以下顺序解析:portal_alias > server_alias > alias > 原始工具名称。

如果未设置别名,portal 将使用上游 server 提供的原始名称和描述。

自定义描述遵循相同的优先级。在 updated_tools 或 updated_prompts 的条目中包含 description 字段即可设置描述。在 API 响应中,server 级别描述以 server_description 返回,portal 级别描述以 portal_description 返回。同时设置两者时,portal 级别描述优先。

在仪表板中设置别名

设置仅应用于特定 portal 的别名:

  1. 在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls > MCP Portals。
  2. 找到要配置的 portal,然后选择三个点 > Edit。
  3. 转到 Servers 选项卡。
  4. 为要配置的 server 选择 Tools authorized 或 Prompts authorized 值(例如 10/10)。
  5. 找到要修改的工具或 prompt,然后选择三个点 > Edit。
  6. 在模态窗口中,根据需要更新 Name 和 Description。
  7. 选择 Confirm(确认)。

设置应用于使用某个 server 的所有 portal 的别名:

  1. 在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls > MCP Portals。
  2. 转到 MCP servers 选项卡。
  3. 找到要配置的 server,然后选择三个点 > Edit。
  4. 转到 Tools 或 Prompts 选项卡。
  5. 找到要修改的工具或 prompt,然后选择三个点 > Edit。
  6. 在模态窗口中,根据需要更新 Name 和 Description。
  7. 选择 Confirm(确认)。
  8. 滚动到页面底部,然后选择 Save server。

经过修改的工具和 prompt 会在仪表板中显示 Modified 标签。

使用 API 设置别名

向更新 MCP portal 端点发送 PUT 请求。为要重命名的每个工具或 prompt 包含 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"
								}
						]
				}
		]
	}'

要设置应用于所有 portal 的 server 级别别名,请向更新 MCP server 端点发送 PUT 请求,并使用相同的 updated_tools 和 updated_prompts 字段。

重置别名

要将工具或 prompt 重置为其原始上游名称,请在仪表板中打开该工具或 prompt 的编辑模态窗口,然后选择“Reset to server definition”。使用 API 时,从 updated_tools 或 updated_prompts 中的相应条目省略 alias 字段。

别名如何影响最终用户

MCP client 会收到别名和自定义描述,而不是原始名称和描述。最终用户看不到原始名称。

如果在用户有活动 session 时更改别名,该用户必须重新进行身份验证才能看到更新。有关重新进行身份验证的选项,请参阅管理 portal session。

工具和 prompt 命名空间

通过 portal 公开的所有工具和 prompt 都会自动以 server ID 为前缀划分命名空间。格式为 {server_id}_{original_name}。例如,ID 为 github 的 server 上名为 list_issues 的工具会在 portal 中显示为 github_list_issues。这可防止多个 MCP server 公开同名工具时发生名称冲突。

prompt 遵循相同模式。ID 为 github 的 server 上名为 summarize 的 prompt 会显示为 github_summarize。

如何确定 server ID

用于命名空间的 server ID 来自添加 MCP server 时设置的 Server ID 字段。你可以在设置流程的第 5 步输入自定义 server ID,也可以让 Cloudflare 自动生成。

计划通过 portal 公开 server 时,请选择简短且描述明确的 server ID。server ID 会成为 MCP client 和 AI Agent 看到的每个工具名称的一部分。

解析带命名空间的名称

portal 仅在第一个下划线处分割带命名空间的名称。第一个下划线之前的部分是 server ID,之后的所有内容都是工具或 prompt 名称。这意味着工具名称可以包含下划线而不会产生歧义。

带命名空间的名称 Server ID 工具名称
github_list_issues github list_issues
github_create_pull_request github create_pull_request
sentry_get_issue_details sentry get_issue_details

由于分割发生在第一个下划线处,server ID 本身不能包含下划线。如果需要多单词 server ID,请改用连字符(例如 my-server)。

使用别名的命名空间

如果你使用别名重命名工具,别名会在命名空间格式中替换原始工具名称。server ID 前缀仍然适用。

例如,如果在 ID 为 github 的 server 上将工具 list_issues 的别名设为 issues,命名空间名称将变为 github_issues。

Code Mode 中的命名空间

启用 Code Mode 时,portal 会执行额外转换,使带命名空间的工具名称可以安全地用作 JavaScript 标识符。名称中的连字符和点会替换为下划线,以数字开头的名称会添加 _ 前缀,JavaScript 保留字会添加 _ 后缀。例如,ID 为 my-server 且工具名为 get-data 的 server 会在 Code Mode sandbox 中显示为 my_server_get_data。

此清理过程会自动完成。最终用户使用 Code Mode 时无需调用任何辅助函数。

Agents SDK 中的辅助函数

如果你使用 Agents SDK 构建 MCP client,SDK 提供了处理 server ID 和工具名称的辅助函数:

  • normalizeServerId(从 agents/mcp/client 导出)会将调用方提供的 server ID 规范化为安全字符串。例如,"GitHub MCP!" 会变为 "github-mcp"。将 id 选项传递给 addMcpServer() 时,SDK 会自动调用此函数。
  • sanitizeToolName(从 @cloudflare/codemode 导出)通过将连字符和点替换为下划线,把工具名称转换为有效的 JavaScript 标识符。在 Code Mode 上下文中会自动调用此函数。有关详细信息,请参阅 Code Mode SDK 参考。

Portal 原生工具

除上游 MCP server 工具外,portal 还会公开自己的内置工具,使 AI Agent 能够在 session 期间管理 server 连接并发现工具。这些工具使用 portal_ 前缀,不与任何上游 server 关联。

始终可用

无论连接模式如何,以下工具在每个 portal session 中都可用:

工具 说明
portal_list_servers 列出所有上游 MCP server,包括其 ID、名称以及当前是否在 session 中启用。
portal_toggle_servers 打开 server 选择流程。返回一个 URL,用户可在浏览器中访问该 URL,以启用或停用 server 并管理 OAuth 凭据。
portal_toggle_single_server 无需访问浏览器即可启用或停用单个 server。接受 server_id 和 action(toggle 或 untoggle)。如果 server 需要 OAuth 且用户尚未进行身份验证,portal 会回退到基于浏览器的 portal_toggle_servers 流程。

这些工具支持本指南后文介绍的 session 管理功能。当你请求启用 server、停用 server 或返回 server 选择页面时,AI Agent 会自动调用这些工具。

上下文优化工具

使用 optimize_context 查询参数连接时,portal 会公开用于发现和调用上游工具的其他工具:

工具 可用模式 说明
portal_query_tools minimize_tools, search_and_execute 使用正则表达式模式按名称、描述或 schema 搜索上游工具。返回完整工具定义,以便 Agent 调用。在 minimize_tools 模式下必须使用,因为该模式会移除上游工具 schema 以减小上下文大小。
portal_execute search_and_execute 按名称并使用提供的参数调用上游工具。在 search_and_execute 模式下,上游工具会从工具列表中完全隐藏,因此 Agent 必须使用 portal_query_tools 发现工具,并使用 portal_execute 调用工具。

Code Mode 工具

启用 Code Mode 进行连接时,portal 会将所有上游工具替换为两个代码执行工具:

工具 说明
portal_codemode_search 通过在 sandboxed Worker 中运行 JavaScript 来搜索可用工具。sandbox 提供 codemode.tools() 函数,该函数返回名称经过清理的所有上游工具定义。
portal_codemode_execute 通过在 sandboxed Worker 中运行 JavaScript 来调用上游工具。sandbox 提供 codemode 代理对象,其每个属性都映射到一个上游工具。支持使用 Promise.all() 并行调用工具。

有关为这些工具编写代码的详细信息,请参阅 Code Mode SDK 参考。

通过 API 管理 portal

除仪表板外,你还可以使用 Cloudflare API 以编程方式管理 MCP server portal。以下示例展示常见操作。

列出 portal

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

创建 portal

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",
		"code_mode": "opt_in",
		"secure_web_gateway": false
	}'

列出 MCP server

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

创建 MCP server

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 字段接受以下值:

值 说明
oauth server 需要 OAuth 身份验证。你可以使用 DCR 或提供手动 OAuth 凭据。
bearer server 使用静态 bearer token 或自定义身份验证标头。在 auth_credentials 中提供凭据(请参阅 Bearer 身份验证凭据)。
unauthenticated server 不需要身份验证。

手动 OAuth 凭据

要使用预注册的 OAuth client 创建 MCP server,请将 auth_type 设为 oauth,并同时提供 auth_credentials 和 client_secret。auth_credentials 值为必填项,且必须是 JSON 编码的字符串:

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 '{
		"id": "github",
		"name": "GitHub MCP Server",
		"hostname": "https://github-mcp.example.com/mcp",
		"auth_type": "oauth",
		"auth_credentials": "{\"auth_mode\":\"manual\",\"config\":{\"authorization_endpoint\":\"https://github.com/login/oauth/authorize\",\"token_endpoint\":\"https://github.com/login/oauth/access_token\"},\"registration_info\":{\"client_id\":\"<client-id>\",\"token_endpoint_auth_method\":\"client_secret_basic\",\"scope\":\"repo read:user\"}}",
		"client_secret": "<client-secret>",
		"is_shared_oauth_callback_enabled": true
	}'

解码后的 auth_credentials 对象必须包含:

  • auth_mode:必须为 manual。
  • config.authorization_endpoint 和 config.token_endpoint:上游 provider 的 OAuth 端点。issuer 和 revocation_endpoint 为可选项。
  • registration_info.client_id:上游 provider 签发的 client ID。
  • registration_info.redirect_uris:Cloudflare 仅使用数组中的第一个 URI。当 is_shared_oauth_callback_enabled 为 true 时,请省略此字段。Cloudflare 会添加共享 callback URL。
  • registration_info.token_endpoint_auth_method:可选。接受的值为 none、client_secret_post 和 client_secret_basic。
  • registration_info.scope:可选的空格分隔 scope 字符串。

创建 server 前,请将共享 callback URL 添加到上游 provider 允许的重定向 URI。将 is_shared_oauth_callback_enabled 设为 true。然后,Cloudflare 会将共享 callback 用于仪表板授权,以及通过包含该 server 的任何 portal 进行连接的用户。

不要在 auth_credentials 中包含 client_secret 或 OAuth token。请将 client_secret 作为上面所示的独立同级字段发送。

要更改 OAuth 元数据,请在发往更新 MCP server 端点的 PUT 请求中发送 auth_credentials。更新现有手动 OAuth server 时可以不提供 client_secret;存储的 secret 会保持不变。发送新的 client_secret 即可轮换。新的手动 OAuth server,或正在改为手动 OAuth 的 server,必须提供非空 client_secret。

client secret 为只写字段。Cloudflare 在存储前对其加密,绝不会在读取、创建或更新请求中返回。响应也会省略原始 auth_credentials 值。使用 auth_config_summary.has_client_secret 和 auth_config_summary.client_secret_version 确认已配置 secret 并识别其当前版本。

Bearer 身份验证凭据

auth_credentials 字段接受两种形式:

  • 原始 bearer token — portal 在发往上游 MCP server 的请求中,将该值作为 Authorization: Bearer <token> 标头发送:

    {
      "auth_type": "bearer",
      "auth_credentials": "your-bearer-token"
    }
  • 自定义标头的 JSON 编码对象 — 适用于需要多个标头或非标准标头名称的上游 MCP server:

    {
      "auth_type": "bearer",
      "auth_credentials": "{\"headers\":{\"X-Api-Key\":\"<api-key>\",\"X-Client-Id\":\"<client-id>\"}}"
    }

    auth_credentials 的值必须是 JSON 字符串。解析后的对象必须包含 headers 字段,将标头名称映射到字符串值。portal 会将所有标头原样转发到上游 MCP server。

查看工具调用分析

使用账户端点检索整个账户每日或每月的 MCP 工具调用次数:

默认情况下,这些计数仅包含成功的工具调用。要包含错误和缓存调用,请设置 response_status=all。使用 error 或 cached 可分别统计任一状态。

curl "https://api.cloudflare.com/client/v4/accounts/%7Baccount_id%7D/access/ai-controls/mcp/analytics/tool-calls/timeseries?granularity=daily&aggregate=false&tz=utc&days=30" \
	--request GET \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

每个端点都支持相同的查询参数:

参数 值和行为
granularity daily 或 monthly。默认为 daily。
aggregate true 或 false。默认为 false。设为 true 以请求聚合计数。
tz utc、Z,或固定的 +HH:MM 或 -HH:MM 偏移。默认为 utc。偏移范围为 -12:00 到 +14:00;+14:00 和 -12:00 是界限。该偏移用于按本地日期分组,不考虑窗口内的夏令时变化。
days 从 1 到 179 的整数。对于每日结果,此参数设置尾随窗口,默认值为 7。当 granularity=monthly 时忽略此参数。
response_status success、error、cached 或 all。默认为 success。设为 all 以包含所有状态。无效值(包括空值)会返回 400。

响应 result 包含所选的 granularity、aggregate、tz 和 response_status,窗口的 start 和 end(以 epoch 毫秒为单位),由 day 和 count 值组成的 series,以及 total 计数。窗口包含 start,但不包含 end。每日 day 值在所请求的时区偏移中使用 YYYY-MM-DD。

使用有作用域的端点限制计数:

  • Server:GET /accounts/{account_id}/access/ai-controls/mcp/analytics/servers/{server_id}/tool-calls/timeseries
  • Portal:GET /accounts/{account_id}/access/ai-controls/mcp/analytics/portals/{portal_id}/tool-calls/timeseries

强制同步 MCP server

手动触发从上游 MCP server 同步工具和 prompt:

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"

删除 portal

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"

通过 Terraform 配置

你可以使用 Cloudflare Terraform provider 管理 MCP server 和 portal。使用 cloudflare_zero_trust_access_ai_controls_mcp_server ↗ 和 cloudflare_zero_trust_access_ai_controls_mcp_portal ↗ 资源。

以下示例创建一个未经身份验证的上游 MCP server、一个 portal,以及 service token 通过 portal 使用该 server 所需的 Access 资源:

MCP server portal with service token accesshcl
resource "cloudflare_zero_trust_access_service_token" "mcp_bot" {
  account_id = var.cloudflare_account_id
  name       = "MCP bot"
  duration   = "8760h"
}

resource "cloudflare_zero_trust_access_policy" "mcp_bot" {
  account_id = var.cloudflare_account_id
  name       = "Allow MCP bot"
  decision   = "non_identity"

  include = [{
    service_token = {
      token_id = cloudflare_zero_trust_access_service_token.mcp_bot.id
    }
  }]
}

resource "cloudflare_zero_trust_access_ai_controls_mcp_server" "docs" {
  account_id = var.cloudflare_account_id
  id         = "cloudflare-docs"
  name       = "Cloudflare documentation"
  hostname   = "https://docs.mcp.cloudflare.com/mcp"
  auth_type  = "unauthenticated"
}

resource "cloudflare_zero_trust_access_application" "docs" {
  account_id = var.cloudflare_account_id
  name       = "Cloudflare documentation"
  type       = "mcp"

  destinations = [{
    type          = "via_mcp_server_portal"
    mcp_server_id = cloudflare_zero_trust_access_ai_controls_mcp_server.docs.id
  }]

  policies = [{
    id         = cloudflare_zero_trust_access_policy.mcp_bot.id
    precedence = 1
  }]
}

resource "cloudflare_zero_trust_access_ai_controls_mcp_portal" "engineering" {
  account_id = var.cloudflare_account_id
  id         = "engineering"
  name       = "Engineering Portal"
  hostname   = "mcp.example.com"

  servers = [{
    server_id = cloudflare_zero_trust_access_ai_controls_mcp_server.docs.id
    on_behalf = false
  }]
}

resource "cloudflare_zero_trust_access_application" "engineering" {
  account_id = var.cloudflare_account_id
  name       = "Engineering Portal"
  type       = "mcp_portal"
  domain     = cloudflare_zero_trust_access_ai_controls_mcp_portal.engineering.hostname

  destinations = [{
    type = "public"
    uri  = cloudflare_zero_trust_access_ai_controls_mcp_portal.engineering.hostname
  }]

  policies = [{
    id         = cloudflare_zero_trust_access_policy.mcp_bot.id
    precedence = 1
  }]
}

resource "cloudflare_dns_record" "mcp_portal" {
  zone_id = var.cloudflare_zone_id
  name    = "mcp"
  content = "gateway.agents.cloudflare.com"
  type    = "CNAME"
  proxied = true
  ttl     = 1
}

provider 会将 service token 的 client_secret 标记为敏感信息,但 Terraform 仍会将其存储在 state 中。请安全存储 Terraform state,并通过 secret manager 或环境变量将凭据传递给 MCP client。

代码模式

Code Mode 使用两个用于搜索和执行代码的工具替换上游工具定义,从而减少上下文窗口用量。连接的 AI Agent 会编写 JavaScript,调用带类型的 codemode.* 方法。生成的代码在隔离的 Dynamic Worker 环境中运行。身份验证凭据和环境变量保留在模型上下文之外。

Code Mode 适用于包含许多 MCP server 或工具的 portal。随着 portal 添加工具,上下文窗口用量保持固定。

Code Mode 策略

每个 portal 都有一个 Code Mode 策略。默认策略为 Opt-in。

策略 API 值 默认行为 Client 覆盖
关闭 off Code Mode 不可用 忽略查询参数
选择启用 opt_in Code Mode 已关闭 添加 ?codemode=search_and_execute 将其启用
默认启用 default_on Code Mode 已启用 添加 ?codemode=off 将其关闭
强制启用 enforced Code Mode 已启用 忽略查询参数

如果某些 client 运行自己的 Code Mode 实现,请使用 Opt-in 或 On by default。这些策略可让 client 避免嵌套执行代码。

已启用 Code Mode 的上游 server

MCP portal 不支持已启用自身 Code Mode 的上游 MCP server。将 server 添加到 portal 时,请连接到返回完整工具列表的 server 版本。如果上游 server 运行自己的 Code Mode,请使用该 server 的选择退出机制(如果有)。或者,考虑关闭 MCP portal 上的 Code Mode。

配置 Code Mode 策略

  1. 获取现有 MCP portal 配置:

    curl "https://api.cloudflare.com/client/v4/accounts/%7Baccount_id%7D/access/ai-controls/mcp/portals/%7Bid%7D" \
    	--request GET \
    	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
  2. 在响应正文中添加 code_mode。将值设为 off、opt_in、default_on 或 enforced。

  3. 在 PUT 请求中将完整正文发送到更新 MCP Portal 端点。包含完整正文可防止覆盖其他 portal 设置。

allow_code_mode API 字段已弃用。新集成请使用 code_mode。

使用 Code Mode 连接

portal 策略决定 MCP client 是否需要查询参数。对于 Opt-in,请将 ?codemode=search_and_execute 附加到 portal URL。对于 On by default,client 可以改为附加 ?codemode=off。

例如,位于 https://<subdomain>.<domain>/mcp 的 Opt-in portal 使用以下 URL:

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

对于使用 server 配置文件的 MCP client,请使用带查询字符串参数的 portal URL:

MCP client configuration with Code Modejson
{
    "mcpServers": {
        "example-portal": {
            "url": "https://<subdomain>.<domain>/mcp?codemode=search_and_execute"
        }
    }
}

Code Mode 处于活动状态时,portal 会公开 portal_codemode_search 和 portal_codemode_execute。AI Agent 可以发现工具,并在一次执行中组合多个工具调用。

有关使用 Code Mode 进行构建的详细信息,请参阅 Code Mode SDK 参考。

通过 Gateway 路由 portal 流量

启用 Gateway 路由后,对由 MCP server portal 保护的 MCP server 的调用会通过 Cloudflare Gateway 路由。portal 流量将与组织的其他 HTTP 流量一起显示在 Gateway HTTP 日志中。然后,你可以创建数据丢失防护 (DLP) 策略,以检测并阻止向上游 MCP server 发送敏感数据。

Gateway 路由的工作原理

用户通过 portal 调用工具时,portal 会将请求代理到上游 MCP server。启用 Gateway 路由后,此出站请求会在到达上游 server 前经过 Cloudflare Gateway。Gateway 会检查流量并应用任何匹配的 HTTP 策略,包括 DLP 扫描。

由于 portal 流量通过 Gateway 路由,因此也会遵循 Gateway egress 策略。这意味着发往上游 MCP server 的出站请求将来自专用 egress IP 或 Gateway IP 范围,而不是通用 Cloudflare IP。如果上游 MCP server 按源 IP 限制入站流量(例如限制为 VPN 或企业 IP 范围),你可以使用 egress 策略确保 portal 流量来自可预测的 IP 集。

TLS 解密

DLP 检查要求 Gateway 解密 TLS 流量。对于 portal 流量,Gateway 会自动解密并检查 payload,无需启用账户级 TLS 解密设置。由于 portal 会终止来自 MCP client 的连接,并通过 Gateway 重新发起请求,因此无论全局 TLS 解密设置是否启用,Gateway 都会解密 portal 流量。

此自动解密仅适用于流经 portal 的流量。要检查未经过 portal 的 MCP 流量(例如,运行 WARP client 的设备上的 Agent 直接连接到上游 MCP server),你必须像处理任何其他 HTTP 策略一样启用 TLS 解密。

支持的传输

Gateway 路由仅支持 Streamable HTTP ↗ 连接。如果上游 MCP server 配置了 Server-Sent Events (SSE) 端点(以 /sse 结尾的 URL),portal 会自动尝试改用 Streamable HTTP 连接。如果上游 server 不支持 Streamable HTTP,启用 Gateway 路由后连接将失败。

启用 Gateway 路由

你可以通过 Gateway 路由 portal 中的每个 server,也可以为单个 server 启用路由。如果在 portal 上启用 Gateway 路由,则无论 server 级别设置如何,该路由都会应用于此 portal 中的每个 server。

路由 portal 中的每个 server

通过 Gateway 路由 portal 中每个 MCP server 的流量:

  1. 在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls > MCP Portals。
  2. 找到要配置的 portal,然后选择三个点 > Edit。
  3. 在 Basic information 下,启用 Route traffic through Cloudflare Gateway。
  4. 选择 Save(保存)。

路由单个 server

在不为整个 portal 启用 Gateway 路由的情况下,通过 Gateway 路由一个 MCP server 的流量:

  1. 在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls > AI controls。
  2. 转到 MCP servers 选项卡。
  3. 找到要配置的 server,然后选择三个点 > Edit。
  4. 在 Basic information 下,启用 Route traffic through Cloudflare Gateway。
  5. 选择 Save(保存)。

server 级别设置的 API 字段为 secure_web_gateway。其默认值为 false。

portal 流量现在将显示在 Gateway HTTP 日志中。要应用 DLP 扫描,请创建 Gateway HTTP 策略。

Gateway 策略示例

要扫描流量中的敏感数据,请创建 Gateway HTTP 策略,同时匹配 MCP server 以及预定义或自定义 DLP profile。

用于 MCP portal 流量的 Gateway HTTP 策略必须明确指向上游 MCP server。确保策略匹配上游 MCP server hostname(例如 example-mcp-server.example.workers.dev),而不是 portal URL (<subdomain>.<domain>)。

例如,以下策略会阻止包含凭据和 secret 或财务信息的流量:

选择器 运算符 值 逻辑 操作
主机 属于 example-mcp-server.example.workers.dev 并且 拦截(Block)
DLP Profile 属于 Credentials and Secrets、Financial Information

请求被阻止时会发生什么

当工具调用匹配 Block DLP 策略时,Gateway 会将其阻止,portal 会向 MCP client 返回错误以说明阻止情况,而不会完成工具调用。此行为适用于两个方向:

  • 工具调用请求:如果 Agent 发送给工具的数据匹配 DLP profile,Gateway 会阻止出站请求,Agent 会收到说明请求已被阻止的错误。
  • 工具调用响应:如果上游 server 返回的数据匹配 DLP profile,Gateway 会阻止响应,portal 会返回错误,而不是返回匹配的内容。

Agent 可以重试请求,但在内容不再匹配策略之前,请求仍会被阻止。

限制

  • DLP AI prompt profile 不适用于 MCP server portal 流量。AI prompt profile 专为特定 Web client API 路径设计,与 MCP 协议格式不匹配。请改用标准 DLP profile。
  • Gateway 不支持 SSE 传输。如果上游 MCP server 仅支持 SSE,Gateway 路由将不适用于该 server。
  • Portal 级别 Gateway 路由不适用于 DCR 或后台同步。要通过 Gateway 路由这些操作,请为单个 server 启用 Gateway 路由。

连接到 portal

用户可以使用 Workers AI Playground ↗、MCP inspector ↗ 或其他支持远程 MCP server 的 MCP client,连接到在 https://<subdomain>.<domain>/mcp 运行的 MCP server。

在 Workers AI Playground 中测试:

  1. 转到 Workers AI Playground ↗。
  2. 在 MCP Servers 下,输入 https://<subdomain>.<domain>/mcp 作为 portal URL。
  3. 选择 Connect。
  4. 在弹出窗口中,登录 Cloudflare Access 身份提供商。
  5. 弹出窗口会列出 portal 中需要身份验证的 MCP server。对于其中每个 MCP server,选择 Connect 并按照登录提示操作。
  6. 选择 Done 以完成 portal 身份验证流程。

Workers AI Playground 将显示 Connected 状态并列出可用工具。现在,你可以要求 AI 模型使用可用工具完成任务。向 MCP server 发出的请求将显示在 portal 日志中。

对于使用 server 配置文件的 MCP client,请将 portal 添加为远程 HTTP server。具体 URL 字段取决于 client。例如:

MCP client configuration for MCP portalsjson
{
    "mcpServers": {
        "example-mcp-server": {
            "url": "https://<subdomain>.<domain>/mcp"
        }
    }
}

Portal 主页

当用户在浏览器中访问 portal 域名 (https://<subdomain>.<domain>/) 时,portal 会显示包含连接详细信息和设置说明的主页。

主页显示:

  • portal 名称和组织品牌(如果在 Cloudflare Access 中配置)
  • 带复制按钮的 MCP 端点 URL
  • 适用于 Claude Desktop、Workers AI Playground、OpenCode、Windsurf 和其他 MCP client 的每 client 连接说明,其中包含特定于操作系统的文件路径

已通过身份验证的用户会在 session 栏中看到自己的电子邮件地址和 Sign out 按钮。尚未通过身份验证的用户仍可查看主页和连接说明。

退出 portal

要结束 portal session,请从 portal 主页 (https://<subdomain>.<domain>/) 选择 Sign out。退出流程会:

  1. 撤销该用户的所有 portal 级别 OAuth 授权许可。
  2. 删除与 session 关联的所有上游 MCP server OAuth 状态。
  3. 通过 Cloudflare Access 注销流程进行重定向。

退出后,portal 会显示确认页面,其中汇总已撤销的 session。要重新连接,请访问 portal 主页并再次进行身份验证。

使用 service token 连接

对于机器到机器访问,你可以使用 Access service token 连接到 MCP portal。Service token 会绕过基于浏览器的 OAuth 流程,并使用 CF-Access-Client-Id 和 CF-Access-Client-Secret 标头进行身份验证。

service token session 会接受两次授权:一次在 portal URL,另一次针对它尝试通过 portal 访问的每个上游 MCP server。这两项检查都需要匹配的 Service Auth 策略。

必需配置

位置 策略操作 Include 规则 用途
Portal Access application Service Auth(服务身份验证) 你的 service token 允许 bot 连接到 portal URL。
每个关联的 MCP server Access app Service Auth(服务身份验证) 你的 service token 允许 bot 通过 portal 查看和调用该 server 的工具。
Server 的 portal 映射 不适用 不适用 Require user auth 必须为 off,以便 portal 使用管理员凭据。

如果关联的 MCP server 没有与 token 匹配的 Service Auth 策略,该 server 会从 bot 的工具列表中隐藏。

设置 service token 连接

  1. 在 Zero Trust 账户中创建 service token。
  2. 打开 portal 的 Access application,并添加包含该 service token 的 Service Auth 策略。
  3. 对于希望 bot 访问的每个上游 MCP server:
    1. 打开 server 的 Access application,并添加包含同一 service token 的 Service Auth 策略。
    2. 打开 portal 并编辑 server。关闭 Require user auth,使 portal 对该 server 使用管理员凭据。
  4. 使用 service token 标头从 MCP client 连接。

要使用 API 配置此流程,请在 MCP portal 请求中将 servers[].on_behalf 设为 false。创建带有 service_token include 规则的 non_identity Access 策略。将该策略附加到 portal 以及每个关联的 server Access application。有关完整 Terraform 示例,请参阅通过 Terraform 配置。

要验证连接,请使用 service token 标头发送 MCP initialize 请求:

curl https://<subdomain>.<domain>/mcp \
  -H "CF-Access-Client-Id: <CLIENT_ID>" \
  -H "CF-Access-Client-Secret: <CLIENT_SECRET>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"service-token-test","version":"1.0.0"}}}'

对于 mcp-remote,请通过环境变量传递凭据,而不是将其存储在 MCP client 配置中:

MCP client configuration for service token connectionsjson
{
    "mcpServers": {
        "example-portal": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote@latest",
                "https://<subdomain>.<domain>/mcp",
                "--header",
                "CF-Access-Client-Id:${ACCESS_CLIENT_ID}",
                "--header",
                "CF-Access-Client-Secret:${ACCESS_CLIENT_SECRET}"
            ],
            "env": {
                "ACCESS_CLIENT_ID": "<CLIENT_ID>",
                "ACCESS_CLIENT_SECRET": "<CLIENT_SECRET>"
            }
        }
    }
}

设备身份验证

MCP server portal 需要基于浏览器的身份验证流程。MCP portal 目前不支持设备身份验证(无需浏览器重定向,直接从 Cloudflare One Client 获取身份)。用户首次连接时必须在浏览器中完成 Access 登录流程。

优化上下文

MCP server portal 支持上下文优化选项,可减少工具定义在模型上下文窗口中消耗的 token 数量。当 portal 聚合许多 MCP server,或 server 公开大量工具时,这些选项非常有用。

要使用上下文优化,请在从 MCP client 连接时,将 optimize_context 查询参数附加到 portal URL。

最小化工具

minimize_tools 选项会从所有上游工具中移除工具描述和输入 schema,只保留其名称。portal 会公开一个特殊的 query 工具,Agent 使用该工具按需搜索并检索完整工具定义。Agent 无需预先加载所有定义即可发现工具。

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

要使用 minimize_tools 连接,请使用以下 portal URL:

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

对于使用 server 配置文件的 MCP client:

MCP client configuration with minimize_toolsjson
{
    "mcpServers": {
        "example-portal": {
            "url": "https://<subdomain>.<domain>/mcp?optimize_context=minimize_tools"
        }
    }
}

搜索并执行

search_and_execute 选项会隐藏所有上游工具,只向 Agent 公开两个工具:query 和 execute。query 工具搜索并检索工具定义。execute 工具运行上游工具。生成的代码在隔离的 Dynamic Worker 环境中运行,使身份验证凭据和环境变量位于模型上下文之外。

无论有多少工具可用,此选项都会将 portal 工具的初始 token 成本降低到一个较小常数。但是,Agent 在调用工具前将完全依赖 query 来发现工具。

要使用 search_and_execute 连接,请使用以下 portal URL:

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

对于使用 server 配置文件的 MCP client:

MCP client configuration with search_and_executejson
{
    "mcpServers": {
        "example-portal": {
            "url": "https://<subdomain>.<domain>/mcp?optimize_context=search_and_execute"
        }
    }
}

有关 search_and_execute 背后的 Code Mode 模式的详细信息,请参阅 Code Mode。

管理 portal session

连接到 portal 后,用户无需离开 MCP client 即可管理其上游 MCP server session。portal 使用 MCP elicitations ↗ 提供 server 选择页面,你可以在其中启用或停用 server、退出各个 server 并重新进行身份验证。

返回 server 选择页面

要在活动 session 期间管理 server 连接,请要求 AI Agent 将你带回 server 选择页面。例如,向 Agent 提示:

将我带回 server 选择页面。

portal 会返回授权 URL。在 Web 浏览器中打开此 URL 以访问 server 选择页面:

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

在此页面中,你可以:

  • 启用或停用 server — 启用或停用各个上游 MCP server。停用 server 会从活动 session 中移除其工具,从而减少上下文窗口用量。
  • 退出并重新进行身份验证 — 如果需要更改 server 可访问的数据,请退出该 server 并重新登录。例如,你可能需要使用不同权限重新进行身份验证。

直接启用或停用 server

你还可以直接从 MCP client 启用或停用特定 server,无需访问 server 选择页面。例如:

启用 wiki server。

停用我的 Jira server。

portal 会切换 server 状态并立即刷新活动工具列表。结果列表仅包含 portal 策略允许的工具和 prompt。如果 allowlist 为空,server 可以处于启用状态,但不公开任何工具或 prompt。

重新验证 server

上游 MCP server token 过期时,portal 会提示你从 MCP client 中重新进行身份验证。在浏览器中打开提供的 URL 并完成登录,以恢复 session。

如果 MCP client 未显示重新身份验证提示,请使用其身份验证控件移除保存的 portal 凭据。然后重新连接到 portal。

授权新 server

管理员将新的上游 MCP server 添加到 portal 时,portal 会自动提示已连接的用户授权新 server。portal 会批量处理管理员更改,并仅将你重定向到授权流程一次,而不会因每个 server 更新逐一中断。

查看 portal 日志

portal 日志允许你监控通过 MCP server portal 进行的用户活动。你可以按 portal 或按 server 查看日志。

  1. 在 Cloudflare 仪表板 ↗中,转到 Zero Trust > Access controls > MCP Portals。
  2. 找到要查看日志的 portal 或 server,然后选择三个点 > Edit。
  3. 选择 Logs。

日志字段

字段 说明
时间 请求的日期和时间
状态 server 是否成功返回响应
Server 处理请求的 MCP server 名称
能力 用于处理请求的工具
时长 请求处理时间(毫秒)

使用 Logpush 导出日志

你可以使用 Logpush 自动将 MCP portal 日志导出到第三方存储目标或安全信息和事件管理 (SIEM) 工具。这样,你便可以与现有安全工作流集成,并根据业务需要长期保留日志。

要为 MCP portal 日志设置 Logpush job,请参阅 Logpush 集成。有关可用日志字段的列表,请参阅 MCP portal 日志。

已知限制

MCP server portal 有以下已知限制:

  • 仅支持远程 HTTP MCP server。 仅使用 stdio 传输 ↗ 的 MCP server(例如 github/github-mcp-server)不提供远程 HTTP 端点,因此无法添加到 MCP server portal。若要使用仅支持 stdio 的 server,必须自行托管并通过 HTTP 端点提供服务,然后使用 bearer token 或自定义标头进行身份验证。
  • 某些 MCP server 会阻止基于代理的客户端。 某些 MCP server 会拒绝来自 MCP server portal 等基于代理的客户端的请求,并在注册端点返回 403 错误。在这些提供商支持 Cloudflare 作为 MCP 客户端之前,这些 server 与 MCP server portal 不兼容。
  • 手动 OAuth 功能会在用户首次授权时记录。 使用手动 OAuth 凭据配置的 server 会一直处于 Waiting 状态,直到用户完成上游 OAuth。Cloudflare 会存储该连接返回的工具和提示。后台和手动功能同步不会刷新这些内容。
  • 管理员 OAuth token 可能会在未通知的情况下过期。 用于验证 MCP server的管理员凭据受上游提供商的 token 过期策略约束。token 过期后,server 状态会变为 Error 或 Sync Required,且最终用户在 portal 中看不到该 server。发生这种情况时不会通知管理员。请定期检查server 状态,并对显示错误的 server 重新进行身份验证。
  • 每个 portal 最多支持 80 个 MCP server。

策略限制

MCP server 使用专用的 Access 应用类型(mcp)。通过 portal 授权 server 时,此类型不支持以下 Access 策略功能:

  • 独立 MFA — 用户授权 server 时,不会通过 Cloudflare Access 提示执行 MFA,无论是否启用了 MFA 全局强制执行,也无论是否为该 server 分配了 MFA 策略。
  • 用途说明 — 用户授权 server 时,不会收到填写用途说明的提示。
  • 临时身份验证 — 用户授权 server 时,不会收到请求访问的提示,审批人也不会收到审批请求。

这些限制仅适用于通过 portal 授权的 server。电子邮件、组、国家/地区和设备状态检查等 Access 策略选择器仍会强制执行。

对于未通过 portal 授权的 server,仍会强制执行独立 MFA、用途说明和临时身份验证。

故障排除

zone hold 导致 portal 创建失败

Cloudflare 会为每个 portal 自定义域创建一个自定义主机名。如果适用于该主机名的 zone hold 包含子域名,portal 创建就会失败。

请为所选 zone 及其每个父级 zone 解除 zone hold,然后重新创建 portal。父级 zone 可能属于其他 Cloudflare 账户。

在 portal 完成身份验证后,用户收到错误 No allowed servers available, check your Zero Trust Policies。

  1. MCP portal 和 server 都必须关联 Access 策略。请确保分配给 portal 的所有 MCP server 都各自关联了策略。
  2. server 的管理员身份验证可能已过期。请检查 server 状态是否为 Ready。如果状态显示 Error 或 Sync Required,请重新验证 server。

将 portal URL 添加到 MCP 客户端时,没有出现身份验证提示。

  1. 确认 portal 已分配 Access 策略。
  2. 确认 portal URL 未应用任何 Workers、Page Rules、自定义主机名定义或其他可能干扰其连接 MCP 客户端的配置。

portal 返回 522 错误。

522 错误表示 Cloudflare 无法连接到 portal 的源站。这通常意味着 portal 主机名的 DNS 记录缺失或配置错误。

  1. 确认存在一条 CNAME 记录,将 portal 子域名指向 gateway.agents.cloudflare.com。
  2. 确保在 Cloudflare DNS 中已为该 CNAME 记录开启 Proxy status。
  3. 如果你通过 API 或 Terraform provider 创建 portal,则必须单独创建 DNS 记录。与仪表板不同,API 和 Terraform provider 不会自动创建 DNS 记录。

MCP server 卡在 Waiting 状态。

Waiting 状态表示 Cloudflare 正尝试连接上游 MCP server 并获取其工具和提示。如果 server 一直处于此状态:

  1. 确认上游 MCP server URL 正确且 server 可访问。
  2. 检查上游 server 是否支持 Streamable HTTP ↗ 或 SSE 传输。portal 会自动尝试多种连接策略。
  3. 如果 server 需要身份验证,请通过重新验证 server确认管理员凭据有效。
  4. 选择三点菜单 > Sync capabilities,手动重试连接。

MCP server 显示 Stale 状态。

Stale 状态表示在上次同步期间无法刷新 server 的管理员凭据。对于使用自己的 OAuth token 的用户,server 工具可能仍然可用(即开启了 Require user auth 的 server),但管理员凭据需要刷新。

若要解决此问题,请使用有效的管理员凭据重新验证 server。

工具调用失败并显示 unauthorized 错误。

  1. 如果 server 使用按用户进行的 OAuth(已开启 Require user auth),用户的 OAuth token 可能已过期。请让用户从其 MCP 客户端重新验证 server。
  2. 如果 server 使用管理员凭据,请检查 server 状态。状态为 Error 或 Sync Required 表示需要刷新管理员凭据。
  3. 如果用户最近更改了上游服务的权限(例如撤销了 OAuth 范围),则需要重新进行身份验证。

连接上游 MCP server 时,OAuth 身份验证因重定向 URI 错误而失败。

invalid_redirect_uri、invalid_client_metadata 或 Redirect URI not allowed 等错误表示上游 OAuth 提供商拒绝了 Cloudflare 用于回调的重定向 URI。请确认已将正确的回调 URL 添加到上游 OAuth 提供商的重定向 URI 允许列表。详情请参阅上游 OAuth 回调 URL。

如果你无法管理该允许列表,请联系上游 MCP server 供应商。

开启 Gateway 路由后,工具调用失败。

  1. 确认上游 MCP server 支持 Streamable HTTP 传输。Gateway 不支持 SSE 传输。
  2. 如果上游 server URL 以 /sse 结尾,portal 会自动尝试改用 /mcp 路径通过 Streamable HTTP 连接。如果 server 不支持该方式,连接将失败。
  3. 检查 Gateway HTTP 日志中是否有 DLP 阻止事件。如果 DLP 策略阻止了流量,portal 会向 MCP 客户端返回错误,其中包含 DLP 规则 ID。

用户无法从 MCP 客户端连接

  1. 确认客户端支持 Streamable HTTP 和 OAuth 发现。
  2. 将 portal URL 配置为远程 HTTP server。
  3. 如果身份验证反复失败,请使用客户端的身份验证控件移除已保存的 portal 凭据,然后重新连接。

portal 主页显示的名称或域名不正确。

portal 主页会显示你的 Access 组织名称和品牌信息。如果显示的名称不正确:

  1. 在 Cloudflare 仪表板 ↗中,前往 Zero Trust > Settings > General > Team name。
  2. 更新团队名称。用户下次访问 portal 主页时,更改就会生效。

这篇文档对您有帮助吗?