配置应用服务内置 MCP （预览版）

应用服务内置 MCP 将托管在 Azure 应用服务 上的现有 REST API 转换为 Model 上下文协议 （MCP） 服务器，而无需编写或部署任何 MCP 代码。 平台读取你提供的 OpenAPI 规范，并为每个操作生成 MCP 工具。 然后，它会在所选路径上通过 可流式传输的 HTTP 为 MCP 终结点提供服务。

何时使用内置 MCP

在以下情况下使用内置 MCP：

• 已在应用服务上运行 REST API，并且希望在不更改代码的情况下将其公开给 MCP 兼容的 AI 客户端（GitHub Copilot 对话助手、Cursor、风帆板、Claude Desktop）。
• 你有一个OpenAPI 3.0.x规范（JSON或YAML），描述了你想暴露的操作。
• 你希望平台负责处理 MCP 协议协商、工具发现、规范热重载和客户端取消。
• 你希望 App Service 身份验证对 MCP 请求强制要求身份验证，就像它对应用中的其他任何路由所做的那样。

在以下情况下，请改用自定义 MCP 服务器（使用 MCP SDK 构建，并作为你的应用代码部署）：

• 你需要无法直接映射到单个 REST 操作的 MCP 工具行为，例如多步工作流、内存聚合，或没有 HTTP 后端端点的工具。
• 除了工具之外，还需要公开 MCP 资源 或 提示 。
• 需要在单个应用上托管多个 MCP 服务器。

有关Azure上所有 MCP 托管选项的比较，请参阅 为 MCP 服务器指定Azure服务。

先决条件

• 专用定价层上的应用服务应用（基本或更高）。 免费、共享、消耗或弹性消耗计划不支持内置 MCP。
• 一个OpenAPI 3.0.x规范（JSON或YAML），描述你想作为MCP工具暴露的操作。 请参阅 步骤 1：为生成选项提供 OpenAPI 规范 。

步骤 1：提供 OpenAPI 规范

内置MCP需要OpenAPI 3.0.x文档（JSON或YAML）。 大多数 Web 框架都可以为你生成一个：

• ASP.NET Core最小 API - 使用内置 Microsoft.AspNetCore.OpenApi 包（默认为 .NET 9 及更高版本）。
• ASP.NET Core 控制器—使用 Swashbuckle。
• FastAPI - 自动生成于 /openapi.json.
• Express/NestJS - 使用 @nestjs/swagger 或 express-openapi。
• Spring Boot - 使用 springdoc-openapi。
• Java/Quarkus - 使用 SmallRye OpenAPI。

如果 API 已在运行并公开 OpenAPI 终结点，则无需添加新库-从该终结点下载规范（例如，使用 curl），并将其保存在本地，以便在启用内置 MCP 时上传它。

公开一个操作的最小规格如下所示：

{
  "openapi": "3.0.3",
  "info": { "title": "Zava Orders", "version": "1.0.0" },
  "paths": {
    "/orders/{id}": {
      "get": {
        "operationId": "get_order",
        "summary": "Get an order by ID",
        "parameters": [
          { "name": "id", "in": "path", "required": true,
            "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "OK" }
        }
      }
    }
  }
}

使用清晰、以行动为导向的operationId值（list_orders、create_order、cancel_order）。 在选择要调用的工具时，AI 客户端使用它们作为工具名称。 有关操作如何映射到 MCP 工具的详细信息，请参阅 内置 MCP 如何将 REST 操作映射到 MCP 工具？。

使规范可供平台使用

平台从应用文件系统中的某个文件读取规范。 默认路径为 /home/data/.ai/apispec.json，可通过 ApiSpecPath 进行配置。 获取文件的方式取决于 在步骤 2 中使用的配置路径：

• 门户 - 创建 MCP 服务器时上传 JSON 或 YAML 文件。 门户会替你将内容写入到 ApiSpecPath 中。
• Azure CLI—随应用一起部署该规范（例如，将其包含在部署工件中），或之后使用 az webapp deploy 或 az webapp ssh 上传它。
• Bicep—引用部署到应用中的路径。

步骤 2：启用内置 MCP

内置 MCP 是通过 aiIntegration 资源上的 Microsoft.Web/sites 属性配置的。 预览版附带 Portal、Azure CLI（使用 az rest） 和 Bicep 作为受支持的配置路径。

以下示例演示了在规范中公开每个操作的最小有效负载。若要筛选操作、配置没有应用服务身份验证的身份验证或更改规范所在的位置，请参阅 “自定义内置 MCP”。

RESOURCE_GROUP=<resource-group>
APP_NAME=<app-name>
SUBSCRIPTION=$(az account show --query id -o tsv)
API_VERSION=2025-05-01

az rest \
  --method PATCH \
  --uri "https://management.chinacloudapi.cn/subscriptions/$SUBSCRIPTION/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.Web/sites/$APP_NAME?api-version=$API_VERSION" \
  --body '{
    "properties": {
      "aiIntegration": {
        "Mcp": {
          "Servers": [
            { "Name": "orders", "Endpoint": "/mcp/orders" }
          ]
        }
      }
    }
  }'

az rest \
  --method PATCH \
  --uri "https://management.chinacloudapi.cn/subscriptions/$SUBSCRIPTION/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.Web/sites/$APP_NAME?api-version=$API_VERSION" \
  --body '{ "properties": { "aiIntegration": null } }'

resource site 'Microsoft.Web/sites@2025-05-01' = {
  name: appName
  location: location
  properties: {
    serverFarmId: appServicePlanId
    aiIntegration: {
      Mcp: {
        Servers: [
          {
            Name: 'orders'
            Endpoint: '/mcp/orders'
          }
        ]
      }
    }
  }
}

步骤 3：连接 MCP 客户端

保存配置后，MCP 终结点可在以下位置获取：

https://<app-name>.chinacloudsites.cn/<endpoint path you provided>

当客户端连接时，它会先调用 initialize，然后调用 tools/list 以发现您的 OpenAPI 规范公开的操作，接着在每次调用时调用 tools/call。

Authentication

内置 MCP 不会颁发令牌或实现授权服务器。 应用服务身份验证对同一应用强制实施身份验证，并可与应用服务身份验证支持的任何身份提供程序配合使用（Microsoft Entra 以及任何其他已配置的 OpenID Connect (OIDC) 提供程序）。 支持两种配置：

• 应用服务身份验证已启用（建议）。 MCP 请求通过与任何其他路由相同的标识检查，并且平台会发布受保护的资源元数据/.well-known/oauth-protected-resource，以便 MCP 客户端可以自动完成 OAuth。 必须执行的后续操作：完成 配置内置 MCP 服务器授权 中的步骤，以在身份提供商中注册 MCP 受众和作用域。
• 未启用应用服务身份验证。 在 SiteAuth 的 aiIntegration 块中提供身份提供商元数据。 此选项适用于已在应用程序代码中验证令牌的情况，并且不希望应用服务身份验证代表应用处理 OAuth 流。 请参阅 配置身份验证而不使用应用服务身份验证。

在这两种情况下，应用程序代码仍负责验证每个请求的持有者令牌。 内置 MCP 不会对基础 HTTP 路由强制实施授权。

自定义内置 MCP

步骤 2 中的最小有效负载接受每个默认值。 仅添加实际需要的字段。 每个代码片段都显示了在最小有效负载基础上添加的字段。

更改规范所在的位置

默认情况下，平台从 /home/data/.ai/apispec.json中读取规范。 将 ApiSpecPath 设置为从其他位置读取它：

"aiIntegration": {
  "ApiSpecPath": "/home/site/wwwroot/openapi/orders.yaml",
  "Mcp": { "Servers": [ { "Name": "orders", "Endpoint": "/mcp/orders" } ] }
}

筛选公开的操作

ToolList 控制每台服务器上的 MCP 服务器公开哪些 OpenAPI 操作。 默认值为 ["*"] （规范中的每个操作）。

• ["*"]— 公开规范中的每个操作。
• []— 不公开任何操作。 可用于在不移除服务器的情况下暂时禁用工具发现功能。
• ["get_order", "list_orders"]——仅暴露列出的 operationId 值。

"Mcp": {
  "Servers": [
    {
      "Name": "orders",
      "Endpoint": "/mcp/orders",
      "ToolList": ["get_order", "list_orders"]
    }
  ]
}

使用此筛选器可将破坏性或仅限管理员的操作保留在 MCP 图面上，同时仍将其服务给现有的 HTTP 客户端。

ToolList 与规范更新的交互方式如下：

• ToolList = ["*"]- 更新规范后，会自动公开新操作。
• ToolList = ["op1", "op2"]—当规范更新时，仅暴露 op1 和 op2。 规范中的新操作将在您将其添加到 ToolList 之前被忽略。
• ToolList 中在规范里不存在的操作 ID 会被静默丢弃。

如果只想进行规范驱动的筛选（没有 ARM 端允许列表），请保留 ToolList = ["*"] 和删除规范本身的操作。

禁用服务器而不将其删除

将 Enabled 设置为 false，可在不删除配置的情况下使 MCP 端点离线：

"Mcp": {
  "Servers": [
    { "Name": "orders", "Endpoint": "/mcp/orders", "Enabled": false }
  ]
}

在没有应用服务身份验证的情况下配置身份验证

如果未在应用上启用应用服务身份验证，请添加一个SiteAuth块，以便平台可以在该处发布/.well-known/oauth-protected-resource。 MCP 客户端（如 VS Code）会遵循首次调用返回的 WWW-Authenticate 标头，以发现授权服务器并完成 OAuth 流程。

"aiIntegration": {
  "Mcp": { "Servers": [ { "Name": "orders", "Endpoint": "/mcp/orders" } ] },
  "SiteAuth": {
    "Scopes": ["api://my-app/user_impersonation"],
    "WellKnownOpenIdConfiguration": "https://login.partner.microsoftonline.cn/{tenant}/v2.0/.well-known/openid-configuration",
    "Audience": "api://my-app-client-id"
  }
}

必填字段：Scopes，以及 WellKnownOpenIdConfiguration 或 Issuer 中的一个。 JwksUri 并且 Audience 是可选的。 有关完整字段列表，请参阅 参考：aiIntegration 架构定义。

应用程序代码仍负责验证每个请求的持有者令牌。

故障排除

MCP 客户端在配置的终结点获取 404。

• 确认 Endpoint 值以 / 开头，并且不会与应用中现有的路由冲突。
• 确认服务器的 Enabled 字段为 true.

MCP 客户端连接但 tools/list 返回空数组。

• 确认已配置规范：要么通过门户上传，要么可在 ApiSpecPath 中设置的路径下获取。
• 确认 ToolList 未设置为 []。
• 用 OpenAPI 3.0.x 的线条验证规范——缺少必填字段（如响应模式）的操作会被跳过。

MCP 客户端收到带有 WWW-Authenticate 质询的 401 响应。

• 启用应用服务身份验证且客户端没有有效令牌时，会出现此错误。 该质询将客户端引导至受保护资源元数据端点，而该端点又会将客户端引导至你的身份提供方。 请参阅 配置内置的 MCP 服务器授权。

MCP 客户端在调用工具时返回 403，但 tools/list 却成功了。

• OAuth 令牌对 MCP 发现有效，但不具备您的应用程序访问底层 HTTP 路由所需的作用域或角色。 检查 CallToolResult 中显示的上游 HTTP 状态。

常见问题解答

内置 MCP 如何将 REST 操作映射到 MCP 工具？

每个 OpenAPI 操作都成为一个 MCP 工具：

• 工具名称—源自该操作的operationId。 如果operationId缺少，平台会回退到{method}_{path}（例如）。 get__orders__id_ 使用面向操作 operationId 的显式值为 AI 客户端提供更清晰的工具名称。

• 工具说明——先显示操作的summary，如果缺少description，则显示summary。

• 工具注释 - 内置 MCP 将 HTTP 方法映射到 MCP 工具注释：

  HTTP 方法	readOnlyHint	idempotentHint	destructiveHint
  GET、HEAD	true	true	false
  PUT、PATCH	false	true	false
  DELETE	false	true	true
  POST	false	false	false

平台如何处理规范更新？

当 ApiSpecPath 处的规范发生变化时（无论是因您重新部署了文件，还是通过门户上传了新版本），平台将：

1. 检测到更改。
2. 重新分析规范并重新计算工具列表。
3. 对新工具列表（SHA-256）进行哈希处理，并将其与以前的哈希进行比较。
4. 如果哈希已更改，请向每个连接的 MCP 客户端发送一个 notifications/tools/list_changed 事件。

无需重启应用或更新 aiIntegration 配置，即可使规范变更生效。 有关 ToolList 如何与规范更新交互，请参阅筛选要公开的操作。

平台在 /.well-known/oauth-protected-resource 提供什么服务？

平台发布 受保护的资源元数据（PRM）， 以便 MCP 客户端可以发现获取访问令牌的位置。 内容来自：

• 应用服务身份验证，在应用上启用时。 平台发布配置的标识提供者的元数据。
• 未启用应用服务身份验证时，SiteAuth 上的 aiIntegration 块。 请参阅 配置身份验证而不使用应用服务身份验证。

如果两者都未配置，平台将不会公开该端点，客户端也不会被要求进行 OAuth 身份验证。

有哪些限制？

参考：aiIntegration 架构

后续步骤

• 配置内置的 MCP 服务器授权
• 为 MCP 服务器设置Azure服务