本指南针对开发模型上下文协议 (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 应用,
选择了错误的工具
- 避免使用名称相似或描述重叠的工具。
- 在描述中添加明确的区别,解释何时应使用每个工具。
小组件问题
小组件无法呈现
如果调用了正确的 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 插件身份验证疑难解答。