MCP 服务器门户

MCP 服务器门户将多个 Model Context Protocol (MCP) servers ↗ 集中到单个 HTTP 端点。

MCP 客户端通过 MCP 门户连接,以访问内部 MCP 服务器和 SaaS MCP 服务器。

本指南介绍如何向 Cloudflare Access 添加 MCP 服务器、创建带有自定义工具和策略的 MCP 门户,以及如何使用 MCP 客户端将用户连接到门户。

关键特性

MCP 服务器门户提供以下能力:

流畅访问多个 MCP 服务器:MCP 服务器门户同时支持未认证的 MCP 服务器和使用 OAuth 保护的 MCP 服务器(例如,通过 Access for SaaS 或第三方 OAuth provider)。用户通过 Cloudflare Access 登录到门户 URL,并被提示分别认证每个需要 OAuth 的服务器。
每个门户的自定义工具:管理员可以通过选择想要通过门户向用户公开的特定工具和提示模板,将 MCP 门户定制为特定用例。这允许用户访问精选的工具和提示集 — 暴露给 AI 模型的外部上下文越少,AI 响应通常越好。
上下文优化:门户支持查询参数选项,通过最小化或隐藏工具定义来减少上下文窗口的使用。详情请参阅 Optimize context。
非浏览器客户端支持:MCP 客户端通过 managed OAuth 使用标准 OAuth 2.0 授权码流程对门户进行认证。非浏览器客户端会收到带有指向 Access 的 OAuth 发现端点的 WWW-Authenticate 头的 401 响应,而不是浏览器重定向。
Code mode:Code mode 在所有门户上默认可用。它将所有上游工具折叠成单个 code 工具。AI agent 编写 JavaScript 调用每个工具的类型化方法,代码在隔离的 Dynamic Worker 环境中运行。这使得上下文窗口的使用保持固定,不论可用的工具数量。连接说明请参阅 code mode。
可观测性:一旦用户的 AI agent 连接到门户,Cloudflare Access 就会记录使用门户中工具发出的单个请求。你可以选择性地将门户流量通过 Cloudflare Gateway 路由,以获得更丰富的 HTTP 日志和数据丢失防护(DLP)扫描。

先决条件

一个在 Cloudflare 上活跃的域名
域名使用完整 setup 或部分 (CNAME) setup
在 Cloudflare Zero Trust 上配置的 identity provider

添加 MCP 服务器

向 Cloudflare Access 添加单个 MCP 服务器,以将它们纳入集中管理。

要添加 MCP 服务器:

在 Cloudflare 仪表板 ↗ 中,转到 Zero Trust > Access controls > AI controls。
转到 MCP servers 选项卡。
选择 Add an MCP server。
为服务器输入任何名称。
(可选)为 Server ID 输入自定义字符串。
在 HTTP URL 中,输入 MCP 服务器的完整 URL。例如,如果你想要添加 Cloudflare Documentation MCP server ↗,请输入 https://docs.mcp.cloudflare.com/mcp。
添加 Access policies 以在 MCP 服务器门户中显示或隐藏服务器。MCP 服务器链接只会在门户中向匹配 Allow 策略的用户显示。未通过 Allow 策略的用户将不会通过任何门户看到此服务器。警告被阻止的用户仍然可以使用其直接 URL 连接到服务器(并绕过你的 Access 策略)。如果你想强制通过 Cloudflare Access 进行认证,请将 Access 配置为服务器的 OAuth provider。
选择 Save and connect server。
如果 MCP 服务器支持 OAuth,你将被重定向到登录到你的 OAuth provider。你可以登录到 MCP 服务器上的任何账户。用于认证的账户将作为该 MCP 服务器的管理员凭据。你可以配置 MCP 门户来使用此管理员凭据发出请求。

Cloudflare Access 将验证服务器连接并获取工具和提示列表。一旦服务器成功连接,server status 将更改为 Ready。你现在可以将 MCP 服务器添加到 MCP 服务器门户。

服务器状态

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

状态	描述
Error	由于凭据过期或不正确,服务器的认证失败。要修复问题,请重新认证服务器。
Waiting	服务器的工具、提示和资源正在同步。
Ready	服务器已成功同步,所有工具、提示和资源都可用。

重新认证 MCP 服务器

要在 Cloudflare Access 中重新认证 MCP 服务器:

在 Cloudflare 仪表板 ↗ 中,转到 Zero Trust > Access controls > AI controls。
转到 MCP servers 选项卡。
选择要重新认证的服务器,然后选择 Edit。
选择 Authenticate server。

你将被重定向到登录到你的 OAuth provider。用于认证的账户将作为此 MCP 服务器的新管理员凭据。

同步 MCP 服务器

Cloudflare Access 每 24 小时自动与你的 MCP 服务器同步一次。要在 Zero Trust 中手动刷新 MCP 服务器:

在 Cloudflare 仪表板 ↗ 中,转到 Zero Trust > Access controls > AI controls。
转到 MCP servers 选项卡并找到要刷新的服务器。
选择三个点 > Sync capabilities。

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

创建门户

要创建 MCP 服务器门户:

在 Cloudflare 仪表板 ↗ 中,转到 Zero Trust > Access controls > AI controls。
选择 Add MCP server portal。
为门户输入任何名称。
在 Custom domain 下,选择门户 URL 的域名。域名必须属于你 Cloudflare 账户中的活跃区域。你可以选择性地指定子域名。
向门户添加 MCP 服务器。
(可选)在 MCP servers 下,配置通过门户可用的工具和提示。
(可选)为支持 OAuth 的服务器配置 Require user auth: - Enabled:(默认)用户将被提示使用自己的登录凭据建立与 MCP 服务器的连接。 - Disabled:连接到门户的用户将自动通过其管理员凭据访问 MCP 服务器。
添加 Access policies 以定义可以连接到门户 URL 的用户。
选择 Add an MCP server portal。
(可选)自定义门户的登录体验。

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

自定义登录设置

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

在 Cloudflare 仪表板 ↗ 中,转到 Zero Trust > Access controls > Applications。
找到要配置的门户,然后选择三个点 > Edit。
要为门户配置 identity provider:
1. 转到 Login methods 选项卡。
2. 选择要为应用启用的 identity providers。
3. (推荐)如果你计划只允许通过单个 identity provider 访问,请打开 Instant Auth。终端用户将不会看到 Cloudflare Access 登录页面。Cloudflare 将直接重定向用户到你的 SSO 登录事件。
要自定义阻止页面:
1. 转到 Experience settings 选项卡。
2. 在 Block page 下,选择终端用户在被拒绝访问应用时看到的内容:
  - Cloudflare default:重新加载登录页面并在 Cloudflare Access 标志下显示阻止消息。默认消息是 That account does not have access,或者你可以输入自定义消息。
  - Redirect URL:重定向到指定的网站。
  - Custom page template:显示托管在 Cloudflare One 中的自定义阻止页面。
选择 Save application。

Code mode 在所有 MCP 服务器门户上默认开启。它通过将门户中所有工具折叠成单个 code 工具来减少上下文窗口的使用。连接的 AI agent 不再为每个上游 MCP 服务器工具加载单独的工具定义,而是编写 JavaScript 调用类型化的 codemode.* 方法。生成的代码在隔离的 Dynamic Worker 环境中运行,这使得认证凭据和环境变量保持在模型上下文之外。

要使用 code mode,MCP 客户端必须在连接到门户 URL 时请求它。所需的查询参数请参阅 Connect with code mode。

Code mode 对于聚合许多 MCP 服务器或暴露大量工具的服务器的门户非常有用。无论门户提供多少工具,上下文窗口使用保持固定。

使用 code mode 连接

要使用 code mode,在从 MCP 客户端连接时,将 ?codemode=search_and_execute 查询字符串参数附加到你的门户 URL。

例如,如果你的门户 URL 是 https://<subdomain>.<domain>/mcp,连接到:


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

对于带有服务器配置文件的 MCP 客户端,使用带有查询字符串参数的门户 URL:

带有 code mode 的 MCP 客户端配置


{

  "mcpServers": {

    "example-portal": {

      "command": "npx",

      "args": [

        "-y",

        "mcp-remote@latest",

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

      ]

    }

  }

}

Explain Code

当 code mode 处于活动状态时,门户向连接的 MCP 客户端通告单个 code 工具。AI agent 通过检查 Dynamic Worker 环境中的类型化方法签名来发现可用工具,并将多个工具调用组合成单个代码执行。

有关使用 code mode 进行构建的更多信息,请参阅 code mode SDK 参考。

关闭 code mode

要为门户关闭 code mode:

Dashboard
API

在 Cloudflare 仪表板 ↗ 中,转到 Zero Trust > Access controls > AI controls。
找到要配置的门户,然后选择三个点 > Edit。
在 Basic information 下,关闭 Code mode。
获取你现有的 MCP 门户配置: 读取 MCP 门户的详细信息

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

向 Update a MCP Portal 端点发送 PUT 请求,并将 allow_code_mode 设置为 false。为了避免覆盖现有配置,PUT 请求体应包含先前 GET 请求返回的所有字段。更新 MCP 门户

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/access/ai-controls/mcp/portals/$ID" \
  --request PUT \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{
    "allow_code_mode": false
  }'

通过 Gateway 路由门户流量

启用 Gateway 路由时,通过 MCP 服务器门户保护的对 MCP 服务器的调用与组织其余 HTTP 流量一起出现在你的 Gateway HTTP 日志中。然后你可以创建 Data Loss prevention (DLP) policies 来检测并阻止敏感数据离开用户的设备并发送到上游 MCP 服务器。

启用 Gateway 路由

要将 MCP 服务器门户流量通过 Gateway 路由:

在 Cloudflare 仪表板 ↗ 中,转到 Zero Trust > Access controls > AI controls。
找到要配置的门户,然后选择三个点 > Edit。
在 Basic information 下,打开 Route traffic through Cloudflare Gateway。
选择 Save。

门户流量现在将出现在你的 Gateway HTTP 日志中。要应用 DLP 扫描,请创建 Gateway HTTP 策略。

Gateway 策略示例

要扫描流量中的敏感数据,请创建一个 Gateway HTTP 策略,该策略匹配 MCP 服务器和预定义或自定义的 DLP profile。

针对 MCP 门户流量的 Gateway HTTP 策略必须明确指向 MCP 服务器 — 这与典型的应用于所有被检查流量的 Gateway HTTP 策略不同。确保你的策略匹配上游 MCP 服务器(例如,https://example-mcp-server.example.workers.dev/mcp),而不是门户 URL(https://<subdomain>.<domain>/mcp)。

例如,以下策略阻止包含 credentials and secrets 或 financial information 的流量:

选择器	操作符	值	逻辑	操作
Host	in	example-mcp-server.example.workers.dev	And	Block
DLP Profile	in	Credentials and Secrets, Financial Information

注意

DLP AI prompt profiles 不适用于 MCP 服务器门户流量。

连接到门户

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

要在 Workers AI Playground 中测试:

转到 Workers AI Playground ↗。
在 MCP Servers 下,输入门户 URL https://<subdomain>.<domain>/mcp。
选择 Connect。
在弹出窗口中,登录到你的 Cloudflare Access identity provider。
弹出窗口将列出门户中需要认证的 MCP 服务器。对于这些 MCP 服务器中的每一个,选择 Connect 并按照登录提示操作。
选择 Done 完成门户认证过程。

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

对于带有服务器配置文件的 MCP 客户端,我们建议使用带有 mcp-remote@latest 参数的 npx 命令:

MCP 门户的 MCP 客户端配置


{

  "mcpServers": {

    "example-mcp-server": {

      "command": "npx",

      "args": [

        "-y",

        "mcp-remote@latest",

        "https://<subdomain>.<domain>.com/mcp"

      ]

    }

  }

}

Explain Code

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

优化上下文

MCP 服务器门户支持上下文优化选项,可以减少工具定义在模型上下文窗口中消耗的 token 数量。当门户聚合许多 MCP 服务器或暴露大量工具的服务器时,这些选项很有用。

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

最小化工具

minimize_tools 选项从所有上游工具中剥离工具描述和输入 schema,只留下名称。门户公开一个特殊的 query 工具,agent 用它来按需搜索和检索完整的工具定义。Agent 可以发现工具,而无需预先加载所有定义。

此选项可提供高达 5 倍的 token 使用量节省,虽然在使用前查询工具定义会增加少量开销。

要使用 minimize_tools 连接,使用以下门户 URL:


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

对于带有服务器配置文件的 MCP 客户端:

带有 minimize_tools 的 MCP 客户端配置


{

  "mcpServers": {

    "example-portal": {

      "command": "npx",

      "args": [

        "-y",

        "mcp-remote@latest",

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

      ]

    }

  }

}

Explain Code

搜索并执行

search_and_execute 选项隐藏所有上游工具,并仅向 agent 公开两个工具:query 和 execute。query 工具搜索并检索工具定义。execute 工具运行上游工具。生成的代码在隔离的 Dynamic Worker 环境中运行,这使得认证凭据和环境变量保持在模型上下文之外。

无论提供多少工具,此选项都将门户工具的初始 token 成本降低到一个小的常数。然而,agent 在调用工具之前完全依赖 query 来发现工具。

要使用 search_and_execute 连接,使用以下门户 URL:


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

对于带有服务器配置文件的 MCP 客户端:

带有 search_and_execute 的 MCP 客户端配置


{

  "mcpServers": {

    "example-portal": {

      "command": "npx",

      "args": [

        "-y",

        "mcp-remote@latest",

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

      ]

    }

  }

}

Explain Code

有关 search_and_execute 背后的 code mode 模式的更多信息,请参阅 Code mode SDK 参考。

管理门户会话

连接到门户后,用户可以在不离开 MCP 客户端的情况下管理上游 MCP 服务器会话。门户使用 MCP elicitations ↗ 提供服务器选择页面,你可以在该页面启用或禁用服务器、注销单个服务器并重新认证。

返回到服务器选择页面

要在活动会话期间管理你的服务器连接,请要求你的 AI agent 带你回到服务器选择页面。例如,提示你的 agent:

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

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


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

在此页面中,你可以:

启用或禁用服务器 — 切换单个上游 MCP 服务器的开/关。禁用服务器会从活动会话中删除其工具,从而减少上下文窗口的使用。
注销并重新认证 — 注销服务器并重新登录,如果你需要更改服务器可访问的数据。例如,你可能需要使用不同的权限重新认证。

内联启用或禁用服务器

你也可以直接从 MCP 客户端启用或禁用特定服务器,而无需访问服务器选择页面。例如:

Enable the wiki server.

Disable my Jira server.

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

重新认证服务器

当上游 MCP 服务器 token 过期时,门户提示你从 MCP 客户端中重新认证。在浏览器中打开提供的 URL 并完成登录以恢复会话。

如果你的 MCP 客户端不显示重新认证提示,你可以手动清除缓存的凭据:

注意

此命令清除使用 mcp-remote@latest 的所有 MCP 服务器的凭据,而不仅仅是 MCP 门户。

终端窗口


rm -rf ~/.mcp-auth

清除凭据后,从 MCP 客户端重新连接到门户。

授权新服务器

当管理员向门户添加新的上游 MCP 服务器时,门户自动提示连接的用户授权新服务器。门户批量处理管理员更改,并将你重定向到授权流程一次,而不是为每个单独的服务器更新中断。

查看门户日志

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

在 Cloudflare One ↗ 中,转到 Access controls > AI controls。
找到要查看日志的门户或服务器,然后选择三个点 > Edit。
选择 Logs。

日志字段

字段	描述
Time	请求的日期和时间
Status	服务器是否成功返回响应
Server	处理请求的 MCP 服务器名称
Capability	用于处理请求的工具
Duration	请求的处理时间(毫秒)

使用 Logpush 导出日志

可用性

仅在 Enterprise 计划上可用。

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

要为 MCP 门户日志设置 Logpush 作业,请参阅 Logpush integration。有关可用日志字段的列表,请参阅 MCP portal logs。

故障排查

在认证到门户后,我的用户收到错误 `No allowed servers available, check your Zero Trust Policies`。

MCP 门户和服务器都必须有附加的 Access 策略。确保所有分配给门户的 MCP 服务器都有自己关联的策略。
服务器的管理员认证可能已过期。检查服务器的状态是 Ready。如果状态显示错误,请重新认证服务器。

当门户 URL 添加到 MCP 客户端时不提示认证。

验证门户已分配 Access 策略。
验证门户 URL 没有应用任何 Workers、Page Rules、custom hostname 定义,或任何其他可能干扰其连接到 MCP 客户端能力的配置。

Keyboard shortcuts

从零构建 Cloudflare Agent