排查 Apigee 中的 MCP 部署问题

本页面适用于 Apigee，但不适用于 Apigee Hybrid。

查看 Apigee Edge 文档。

本页介绍了如何排查和解决 MCP 发现代理的部署问题。您可以通过本页了解 MCP 部署的异步配置生命周期、解决错误代码并验证运行时连接。

了解 MCP 部署

MCP Discovery 代理的部署是一个异步的多步流程，可确保在代理部署完成之前，配置已完全传播到 Apigee 和 Google Cloud 基础架构。

在执行这些下游配置步骤期间，界面会将代理显示为“正在配置”状态。 流程完成后，状态会更改为已部署。此状态确认所有下游组件都已完全预配，并且代理已准备好处理流量。

问题排查

以下各部分介绍了在 Apigee 中使用 MCP 时可能会遇到的错误和已知问题。

工具调用和元数据的错误响应状态代码

Apigee MCP 端点会返回遵循 Model Context Protocol (MCP) 规范和相关 OAuth 标准的 HTTP 状态代码。了解此行为有助于您正确处理 MCP 客户端或 AI 智能体中的错误。

下表总结了 Apigee MCP 端点返回的状态代码：

场景 HTTP 状态代码 响应正文
工具执行在 tools/call 上失败（例如，后端 API 返回 4xx 或 5xx 错误，例如验证错误或缺少必需字段）。 200 OK CallToolResult，其中 result.isError 设置为 true，错误详情位于 content 中。这样一来，MCP 客户端和 LLM 代理就可以读取错误并恢复（例如，通过重新提示缺失的输入并重试），而不是终止会话。
OAuth 受保护的资源元数据 (PRM) 未配置或无法在 /.well-known/oauth-protected-resource/mcp 找到。 404 Not Found 表示所请求的位置没有受保护的资源元数据。
访问令牌缺失、无效或已过期。 401 Unauthorized 包含一个 WWW-Authenticate 挑战，用于驱动 OAuth 发现流程。
访问令牌的范围不足。 403 Forbidden 包含一个 WWW-Authenticate 挑战，用于驱动逐步授权流程。

示例：工具执行错误响应正文

当工具调用失败时，Apigee MCP 会返回 HTTP 200 OK，并在 JSON-RPC result 对象中报告失败情况，并将 isError 设置为 true。后端返回的原始错误会保留：后端响应正文会逐字逐句地放置在 result.content[].text 中（以字符串形式）。例如，如果后端返回正文为 {"error":"User 42 not found"} 的 HTTP 404，则 MCP 响应为：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"error\":\"User 42 not found\"}"
      }
    ],
    "isError": true
  }
}

id 与 tools/call 请求的 id 相匹配。 如果后端未返回任何响应正文，则 text 会包含生成的摘要，例如 Operation failed (HTTP 500).

您的 MCP 客户端应检查 result.isError（而非 HTTP 状态代码）来检测工具调用是否失败。如果您的客户端代码专门期望使用 4xx 或 5xx HTTP 状态来表示工具执行错误，那么在此更改后，它将不再检测到该错误，因为响应现在是 HTTP 200 OK。更新此类客户端以读取 result.isError 和 content 数组。

协议级错误（例如，格式错误的 JSON-RPC 请求）与工具执行错误不同：它们会继续在 JSON-RPC error 对象（例如，{"jsonrpc": "2.0", "error": {"code": -32700, ...}}）中返回，而不是在 result.isError 中返回。

建议：符合标准的 MCP 客户端通过其默认逻辑处理这些状态代码，因此无需进行任何更改。如果您之前添加了客户端解决方法来处理非标准状态代码（例如，解析非 2xx 响应正文以处理 tools/call 错误，或将来自 PRM 端点的 500 响应视为“未配置元数据”），建议您移除该解决方法。否则，您的客户端可能会继续使用过时的处理逻辑，而不是正常处理更正后的状态代码。

基于浏览器的 MCP 调用的 CORS 政策

当直接从浏览器发出 Apigee MCP 调用时（例如，当 MCP 检查器使用“直接”设置而不是“通过代理”时），需要使用跨源资源共享 (CORS) 政策。MCP Discovery Proxy 模板默认在代理软件包的代理端点 Request PreFlow 中包含 Apigee CORS 政策，以启用基于浏览器的调用。

如果您在直接从浏览器进行调用时遇到与 CORS 相关的问题，可能需要在 MCP 发现代理软件包的代理端点 Request PreFlow 中调整 CORS 政策设置。

向 MCP 端点发送请求时出现 JSON 解析错误

向 MCP 端点发送请求时，您可能会收到类似于以下内容的错误消息（或包含其他错误代码和消息）： 

{
  "error": {
    "code": -32700,
    "message": "JSON parse error"
  },
  "id": null,
  "jsonrpc": "2.0"
}

在这种情况下，我们建议您确认以下信息：

  • 您输入的 MCP 端点网址是否正确无误。
  • 您的请求格式正确。
  • 您正在访问受支持的方法。
  • 您已在 受支持的区域中启用并配置 MCP 发现代理。如需查看可能存在容量限制的区域列表，请参阅部署失败。

部署失败

如果 MCP 发现代理的部署在界面中失败并显示 Failed 状态，请查看错误消息了解详情。常见失败情况包括：

  • 网络配置失败或 OAS 中存在不受支持的架构：这些错误通常表示您的 OpenAPI 规范存在问题。确保您的规范有效且使用的是受支持的版本。
  • 区域容量限制：如果您看到与负载均衡器配置失败相关的错误，或者配置状态始终未更改为 Deployed，则可能是由于以下某个区域的临时基础架构容量限制所致：
    • asia-east2
    • asia-northeast3
    • asia-southeast2
    • australia-southeast1
    • europe-central2
    • europe-west12
    • europe-west9
    • me-central2
    • us-central2

    如需解决此错误，请尝试将代理部署到其他区域的环境中。

无法在 API Hub 中将 API 样式更改为 MCP

如果 Apigee API Hub 中已存在具有现有 API 操作的 API 资源，您无法将该资源的 API 样式属性更改为 MCP。如需将 API 注册到 Apigee API Hub 中作为 MCP API，您必须在首次注册 API 时选择 MCP 样式，或者在将样式更改为 MCP 之前确保 API 资源中没有任何操作。

如果您遇到任何其他问题，请参阅使用调试，详细了解如何在 Google Cloud 控制台中使用调试工具来分析与 MCP 发现代理之间的请求和响应。