排查 智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶® 中的 MCP 应用问题

本指南提供有关在开发模型上下文协议 (MCP) 应用以与智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®中的声明性代理集成的常见问题的故障排除建议。

启用开发人员模式

启用开发人员模式 会在代理响应中显示日志和错误。 此信息对于调试至关重要。 若要启用开发人员模式，请在 Microsoft Copilot 中键入以下命令。

-developer on

代理可用的 MCP 工具显示在调试信息卡的“操作”部分中。 有关卡调试信息的详细信息，请参阅在 智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶® 中使用开发人员模式来测试和调试代理。

发现和输入问题

未列出任何工具

如果调试信息的“操作”部分卡未列出任何 MCP 工具，检查以下项。

  • 确认 MCP 服务器正在运行，并且你正在连接到插件清单中的正确 MCP 终结点。
  • 验证插件清单在 属性中包含 functions 预期的工具。
  • 验证在插件清单中的 属性中指定的 runtimes MCP 服务器运行时：
    • 通过以下任一方式引用 属性中的 mcp_tool_description 工具：
      • 引用包含属性或中file工具说明的 JSON 文件
      • 在 属性中列出内联 tools 工具说明
    • 在 属性中包含 run_for_functions 工具名称。
"runtimes": [
  {
    "type": "RemoteMCPServer",
    "spec": {
      "url": "https://api.contoso.com/mcp",
      "mcp_tool_description": "mcp-tools.json"
    },
    "run_for_functions": [
      "get_widget",
      "create_widget"
    ]
  }
]

未从 Copilot 聊天触发的工具

  • 重新访问工具和参数说明，确保它们提供足够的上下文。 请考虑使用“在以下情况下使用此函数/参数”重写它们：措辞。
  • 将说明保持在 1,024 个字符以内。 超过 1,024 个字符的文本将被忽略。
  • 确保正确设置工具可见性。
    • 对于 MCP 应用， _meta.ui.visibility 包括 model。
    • 对于 OpenAI SDK 应用， meta["openai/visibility"] 设置为 public。

选择了错误的工具

  • 避免使用名称相似或描述重叠的工具。
  • 在说明中添加明确的区别，说明何时应使用每个工具。

小组件问题

小组件不呈现

如果调用了正确的 MCP 工具，但 UI 小组件未在响应中呈现，则 MCP 服务器可能仅返回没有 UI 组件的结构化内容。 确保正确配置 UI 绑定。

  • 对于 MCP 应用，工具定义包括 _meta.ui.resourceUri 设置为 MIME 类型的 text/html;profile=mcp-app已注册 HTML 资源。
  • 对于 OpenAI SDK 应用，工具定义包括 _meta["openai/outputTemplate"] 设置为 MIME 类型的 text/html+skybridge已注册 HTML 资源。

小组件无法加载

  • 在控制台中打开针对内容安全策略 (CSP) 冲突的浏览器开发人员工具和检查。 确保允许列出来自小组件的主机 URL 的请求。 有关详细信息，请参阅 MCP 应用的 MCP 服务器要求。
  • 验证小组件是否将所有 HTML 和 JavaScript 依赖项编译为没有外部未解析资产的单个文件。

小组件加载时没有数据

  • 验证工具的响应结构。
    • content 应仅包含模型) (数据。
    • structuredContent 应同时包含数据和小组件。
    • _meta 应仅包含小组件。
  • 确保 structuredContent 或 _meta 包含所需的数据。

小组件具有双滚动条

Copilot 主机容器已具有最大高度的滚动。 通过在容器样式中设置 overflow: hidden 来禁用小组件内部滚动。

定位标记 <a> 不适用于 Copilot 中的外部链接。 请改用适当的平台 API。

  • 对于 MCP 应用，请使用 app.openLink。
  • 对于 OpenAI SDK 应用，请使用 window.openai.openExternal。

全屏在某些 Copilot 主机中不起作用

并非所有 Copilot 主机都支持全屏视图。 最佳做法是始终检查主机功能，并有条件地显示 UI 元素 (，例如全屏按钮) 。 有关详细信息，请参阅 验证 API 可用性。

响应问题

工具结果过期问题

确保通过 content 或 structuredContent 发送的工具响应不会过大。 如果小组件需要对模型没有用的丰富元数据（例如头像 URL 或特定于 UI 的详细信息），请在 中 _meta 包括完整数据，并在 中 content提供简洁的摘要。 此方法可确保模型保留关键信息，同时支持有效的多转体验。

小组件和文本摘要中的重复数据

使用以下选项之一解决此问题：

  • 优化数据分离： 用于 _meta 特定于小组件的数据和 content 模型可见摘要。
  • 引导格式设置： 使用声明性代理清单中的说明来指导如何构建和呈现响应。

身份验证问题

身份验证配置和插件之间的应用 ID 不匹配

如果在调试信息中看到错误卡类似于：

OAuth authentication failed: The App ID used in the request does not match the App ID in the authentication configuration. (HTTP 404)

转到 Teams 开发人员门户。 在客户端注册) 查找 OAuth 客户端或 SSO (单一登录，并验证插件中的应用 ID 是否与已注册的应用 ID 匹配。

身份验证配置中的基 URL 与插件不匹配

如果在调试信息中看到错误卡类似于：

OAuth authentication failed: The base URL in your authentication configuration does not match the server URL. (HTTP 401)

转到 Teams 开发人员门户。 找到 OAuth 客户端或 SSO 客户端注册，并验证插件中的 MCP 服务器 URL 是否与注册的基 URL 匹配。

插件清单中的引用 ID 不正确或缺失

如果在调试信息中看到错误卡类似于：

OAuth authentication failed: No matching configuration found for referenceID in 'runtime.auth' section of the action manifest

转到 Teams 开发人员门户。 找到 OAuth 客户端或 SSO 客户端注册，并验证 MCP 服务器运行时 auth.reference_id 中的 ID 是否与开发人员门户中的注册 ID 匹配。

组织策略限制访问

如果在调试信息中看到错误卡类似于：

OAuth authentication failed: Access is restricted by your organization's policy. (HTTP 404)

请与组织的管理员联系，查看并启用应用的访问权限。

登录按钮处于非活动状态或显示常规错误

如果登录按钮处于非活动状态或已禁用状态，或者选择它时出现一般“无法处理请求”错误，则此情况可能表示存在临时身份验证或会话问题。 重试查询。 如果问题仍然存在，请重新安装应用或联系组织的管理员。

登录弹出窗口无法打开

在浏览器设置中为站点启用弹出窗口，然后重试。

凭据错误

如果在登录弹出窗口或聊天响应中看到“凭据不正确”错误，请确保输入正确的凭据。 如果错误仍然存在，请确保用户具有所需的权限。

找不到登录 URL

卸载并重新安装应用，然后再次尝试登录。

身份验证期间的内部服务器错误

在身份验证弹出窗口中查看详细信息，并联系组织的管理员以了解权限问题。

如果出现请求权限或业务理由的同意对话框，请查看请求的权限，并在必要时提供业务理由。 如果不确定，或者同意对话框请求需要管理员同意的权限，请与组织的管理员联系。

相关内容

  • Last updated on