如何在 API 管理中安全地推出新的 MCP 服务器版本

更新 MCP 服务器时，在将所有使用方切换到新版本之前，需要确保该版本运行良好，并且不会引入破坏性变更。 API 管理支持并行运行多个版本的 API，因此可以将部分流量路由到新版本，同时保留旧版本作为回退。

API 管理还支持 API 修订，这些修订非常适合非中断性变更。通过修订，您可以在不影响使用方的情况下迭代更新某个 API 版本，直到准备好将新修订版本提升为正式版本。

确定您的更改是破坏性变更还是非破坏性变更，以选择正确的版本管理策略：

策略	何时使用	使用者的结果
API 版本（路径、标头或查询）	重大更改，例如重命名工具、更改所需参数或删除工具。	v1 和 v2 在不同的终结点上可访问。消费者明确针对其中一个。
API 修订	非中断性迭代，例如展开工具说明、添加可选参数或修复后端 bug。	所有客户端都会继续访问当前版本；你可以以原子方式将新版本提升为现行版本。

本文重点介绍需要进行需要新 API 版本的重大更改的方案。

先决条件

API 管理实例。若要创建一个实例，请参阅“创建Azure API 管理实例”。
已添加到 API 管理中的现有 MCP 服务器（在本文中称为 v1），并且已有活跃使用者。请参阅将 REST API 公开为 MCP 服务器或公开现有 MCP 服务器。
可供部署的新版 MCP 服务器（v2）已准备就绪，其工具集与 v1 不同，或包含破坏性变更。
已实施监控，用于比较 v1 和 v2 的性能与可靠性（例如，使用包含 API 版本和工具名称等自定义维度的 Application Insights）。有关详细信息，请参阅监视 MCP 服务器流量。

搭建 v2，与 v1 并行运行

在 Azure 门户中，转到 API 管理实例。
选择 API>MCP 服务器，并找到要版本的 MCP 服务器。
在 MCP 服务器的上下文菜单中，选择“ + 添加版本”。选择版本控制方案：路径（/mymcp/v2/...）、标头（Api-Version: v2）或 查询字符串 （?api-version=v2）。有关配置详细信息，请参阅创建新的 API 版本。
配置 v2 的工具集。工具定义可以从 v1 中分离。
接下来，将 v2 发布到与 v1 相同的产品中，这样现有订阅在迁移期间即可同时涵盖这两个端点。

将一部分使用者路由到 v2

在两个版本同时运行的情况下，你可以将一定比例的流量路由到 v2，其余流量则继续路由到 v1。通过此方法，可以在实际使用者负载下验证 v2 的性能和可靠性，然后再将其提升给所有人。在 API 的策略定义中配置路由。下面是一些常见策略：

粘性百分比发布

在此策略中，同一订阅始终会分配到同一版本：

<choose> 
  <when condition="@(System.Math.Abs(context.Subscription.Id.GetHashCode()) % 100 < 20)"> 
    <set-backend-service backend-id="mcp-v2" /> 
  </when> 
  <otherwise> 
    <set-backend-service backend-id="mcp-v1" /> 
  </otherwise> 
</choose>

基于标头的选择加入

在此策略中，使用者将添加 x-mcp-channel: preview 以选择 v2：

<choose> 
  <when condition="@(context.Request.Headers.GetValueOrDefault(\"x-mcp-channel\",,\"\") == \"preview\")"> 
    <set-backend-service backend-id="mcp-v2" /> 
  </when> 
  <otherwise> 
    <set-backend-service backend-id="mcp-v1" /> 
  </otherwise> 
</choose>

按订阅 ID 划分的允许列表

在此策略中，将特定的试点客户固定到 v2：

<set-variable name="preview-subs" value="sub-abc,sub-def" /> 
<choose> 
  <when condition="@(((string)context.Variables[\"preview-subs\"]).Split(',') 
                      .Contains(context.Subscription.Id))"> 
    <set-backend-service backend-id="mcp-v2" /> 
  </when> 
</choose>

监控发布过程

当 v1 和 v2 同时运行时，请按 service.version 筛选以进行比较：

requests 
| where customDimensions["api.type"] == "Mcp" 
  and customDimensions["service.name"] == "sales-mcp" 
  and customDimensions["gen_ai.operation.name"] == "tools/call" 
  and timestamp > ago(24h) 
| summarize p95       = percentile(duration, 95), 
            errorRate = todouble(countif(success == false)) / count(), 
            calls     = count() 
    by version = tostring(customDimensions["service.version"]), 
       tool    = tostring(customDimensions["gen_ai.tool.name"]) 
| order by version, p95 desc

提前定义成功条件。例如，“v2 p95 延迟在 v1 的 10% 内，错误率小于或等于 v1 错误速率 24 小时。

升级 v2 并停用 v1

当 v2 满足成功条件时，请将 v2 标记为默认版本。未指定版本的新客户端会自动采用该版本。

向使用方公布 v1 的弃用期（订阅所有者可在开发人员门户中查看）。

窗口后，删除 v1。

如果出现问题，回滚

如果您发现 v2 有问题，请使用以下策略进行回退：

在同一版本内：还原到上一修订版本。修订版本可原子化回退，且无需使用方做任何改动。
跨版本：将默认版本更改回 v1，或更改路由策略以将所有流量发送到 v1。由于 v1 和 v2 共享相同的产品和订阅，因此使用者无需更改其密钥。

什么是 API 管理中的 MCP 服务器？

Last updated on 2026-07-09