智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶® 中的 MCP 应用疑难解答

本指南针对开发模型上下文协议 (MCP) 应用以与 智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶® 中的声明式代理集成时可能遇到的常见问题提供疑难解答建议。

启用开发人员模式

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

-developer on

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

发现和条目问题

未列出任何工具

如果调试信息卡的操作部分未列出任何 MCP 工具,请检查以下项:

  • 确认 MCP 服务器正在运行,并且连接到插件清单中的正确 MCP 终结点。
  • 确认身份验证成功。 许多 MCP 服务器在用户登录前不会返回任何工具,因此失败或跳过登录可能会导致工具列表为空。

动态工具发现

如果代理 (默认) 使用 动态工具发现 ,则会在运行时从服务器解析这些工具。 检查:

  • RemoteMCPServer运行时设置为 run_for_functions ,["*"]并且顶级functions数组为空。
  • 服务器的方法 tools/list 返回工具。 可以使用 MCP 检查器等工具检查响应。
  • 运行时验证不会保留新发现或修改的工具。 检查调试信息中是否存在验证错误。
"runtimes": [
  {
    "type": "RemoteMCPServer",
    "spec": {
      "url": "https://api.contoso.com/mcp"
    },
    "run_for_functions": [
      "*"
    ]
  }
]

已固定工具

如果固定了一组固定的工具,请验证插件清单中属性 runtimes 中指定的 MCP 服务器运行时:

  • 在顶级 functions 属性中包括所需的工具。
  • 通过以下任一方法引用属性中的 mcp_tool_description 工具:
    • 引用属性中file包含工具说明的 JSON 文件或
    • 在属性中 tools 内联列出工具说明
  • 在属性中 run_for_functions 包括工具名称。
"runtimes": [
  {
    "type": "RemoteMCPServer",
    "spec": {
      "url": "https://api.contoso.com/mcp",
      "mcp_tool_description": {
        "file": "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 可用性。

响应问题

工具结果过期问题

确保工具响应通过contentstructuredContent或不过大。 如果小组件需要对模型无用的丰富元数据(例如虚拟形象 URL 或特定于 UI 的详细信息),请在 中 _meta 包含完整数据,并在 中提供简洁摘要 content。 这种方法可确保模型保留关键信息,同时支持有效的多轮身体验。

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

使用下列选项之一解决此问题:

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

身份验证问题

有关身份验证问题(例如登录失败、令牌错误、同意提示和身份验证配置不匹配)请参阅 MCP 和 API 插件身份验证疑难解答。