智能 Microsoft 365 Copilot 副驾驶® 插件将受支持的Microsoft体验连接到 MCP) 服务器 (远程模型上下文协议提供的工具。 插件包包含连接配置,服务器单独运行。
使用 Work IQ Dev Tools (WIQD) 创建、验证和打包插件。 从 使用 Work IQ Dev Tools 构建插件开始。
以下部分介绍了需要手动编辑清单的开发人员的基础配置。 在 Microsoft 365 应用清单的数组中 agentConnectors 注册插件的远程 MCP 服务器。 即使可安装包称为插件,此架构标识符仍保留 agentConnectors 。
重要
此配置使用 Microsoft 365 应用清单,而不是用于声明性代理操作的 MCP 插件清单。 它还独立于智能体 365 CLI 注册路由。 有关这些替代方案,请参阅 构建或重用 MCP 服务器。 仅支持 MCP 并不能建立对此注册模型的支持。
先决条件
开始前,请确保你有:
- 测试租户和目标 Microsoft 体验,支持通过
agentConnectors配置的插件。 - 一个正在工作的 MCP 服务器,具有可公开访问的 HTTPS 终结点、TLS 1.2 或更高版本以及目标体验支持的传输。
- 一个 Microsoft 365 应用包,其清单版本受目标体验和所选授权类型支持。
- 为服务器注册的授权配置,例如 OAuth 配置 或 API 密钥配置,除非服务器允许匿名访问。
有关 WIQD 服务器要求和 Copilot Cowork 工具说明要求,请参阅 Work IQ 开发工具。
将 MCP 服务器添加到应用清单
在应用清单根级别的 agentConnectors 数组中声明 MCP 服务器。
- 在 Microsoft 365 应用包中打开应用清单。
- 找到或创建根级
agentConnectors数组。 - 添加一个带有唯一
id、 adisplayName、adescription和 atoolSource的条目,用于标识远程 MCP 服务器。
以下 JSON 是要合并到现有应用清单中的片段,而不是完整的应用清单:
{
"$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.30/MicrosoftTeams.schema.json",
"manifestVersion": "1.30",
"agentConnectors": [
{
"id": "my-mcp-server",
"displayName": "My Automation Server",
"description": "Provides workflow automation and task management tools.",
"toolSource": {
"remoteMcpServer": {
"mcpServerUrl": "https://mcp.example.com/mcp",
"authorization": {
"type": "OAuthPluginVault",
"referenceId": "my-oauth-config"
},
"mcpToolDescription": {
"file": "toolDescription.json"
}
}
}
}
]
}
将终结点和授权引用替换为服务器的值。 每个条目 id 在 agentConnectors中都必须是唯一的。 将其他必需的应用清单属性保留在现有文件中。
配置服务器终结点
将 toolSource.remoteMcpServer.mcpServerUrl 设置为 HTTPS 终结点。 确认服务器可从目标体验访问,并响应 MCP 初始化和后续协议请求。
配置身份验证
在 中设置authorization。agentConnectors[].toolSource.remoteMcpServer 下表列出了授权类型及其配置。 有关架构详细信息,请参阅 授权架构。
| 授权类型 | 配置 |
|---|---|
None |
无需身份验证。 仅当服务器允许匿名访问时使用。 |
OAuthPluginVault |
OAuth 配置存储在 Microsoft 保管库中并由 ID 引用。 |
ApiKeyPluginVault |
API 密钥配置存储在保管库中并由 ID 引用。 |
DynamicClientRegistration |
动态 OAuth 客户端注册配置,由 ID 引用。 |
AzureKeyVault |
ID 引用的 Azure 密钥保管库 配置。 需要主机支持。 |
ConnectionVault (开发者预览版) |
ID 引用的连接配置。 |
架构值不保证在目标体验中得到支持。 在选择方法之前,请检查其身份验证要求。
标识 referenceId 从清单中分开获取的配置。 请勿将 API 密钥、访问令牌、客户端密码或机密值放在应用清单的此字段或其他位置。
使用 OAuth 身份验证
对于存储在 Microsoft 保管库中的 OAuth 2.0 令牌,请使用以下 authorization 对象:
{
"type": "OAuthPluginVault",
"referenceId": "my-oauth-config"
}
在 开发人员门户 中注册 OAuth 配置,并将返回的配置 ID 用作 referenceId. 有关详细信息,请参阅 在开发人员门户中配置 OAuth。
将以下回调 URL 添加到 OAuth 提供程序注册中允许的重定向 URI:
https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect
使用 API 密钥身份验证
对于存储在保管库中的 API 密钥,请使用以下 authorization 对象:
{
"type": "ApiKeyPluginVault",
"referenceId": "my-apikey"
}
在 开发人员门户中注册密钥,然后替换 my-apikey 为返回的注册 ID。 有关详细信息,请参阅 API 密钥身份验证。
使用动态客户端注册
动态客户端注册使主机能够使用 RFC 7591 向 MCP 服务器注册为 OAuth 客户端。 两者都必须支持注册流程。 Microsoft Entra ID 不提供 RFC 7591 注册终结点;对受 Entra 保护的服务器使用静态 OAuth 注册。
使用以下 authorization 对象:
{
"type": "DynamicClientRegistration",
"referenceId": "my-dcr-config"
}
在 开发人员门户 中注册配置并替换 my-dcr-config 为其引用 ID。 该配置提供主机在协商客户端凭据时使用的授权值。
你的服务器必须:
- 公开 RFC 7591 客户端注册终结点。
- 返回主机的 OAuth 流所需的客户端注册信息。
- 在需要时支持长期会话的令牌刷新。
使用 Azure 密钥保管库 身份验证
AzureKeyVault 包含在应用清单架构 1.29 和 1.30 中。 仅当目标体验记录 Azure 密钥保管库 集成和获取配置引用的过程时,才使用此方法。
使用以下 authorization 对象:
{
"type": "AzureKeyVault",
"referenceId": "my-keyvault-config"
}
遵循该集成的凭据存储和访问要求,并替换 my-keyvault-config 为返回的引用。 清单声明本身不会授予对机密的访问权限。
使用连接保管库身份验证
注意
连接保管库身份验证在开发人员预览中可用。 使用开发人员预览版应用清单架构进行配置 ConnectionVault;它在公开发布的应用清单架构中不可用。
对于受支持的连接-保管库集成,请使用以下 authorization 对象:
{
"type": "ConnectionVault",
"referenceId": "shared_example"
}
替换 shared_example 为目标集成提供的连接引用。
不使用任何身份验证
如果您的服务器允许匿名访问,则在主机允许时设置为authorization.typeNone或省略authorization。
在生产和企业方案中首选经过身份验证的访问,在支持的情况下首选 OAuth 而不是 API 密钥。
定义工具发现
当工具集已修复时使用打包的工具定义,或者当应用清单版本和目标主机支持时使用动态发现。
使用静态工具定义
在应用包中包含工具说明文件,并在 中引用它 remoteMcpServer。 路径是相对于应用包的。 使用服务器 tools/list 结果中的工具定义,包括每个工具的名称、说明和输入架构。 例如,最小 toolDescription.json 文件可以包含:
{
"mcpToolDescription": {
"file": "toolDescription.json"
}
}
{
"tools": [
{
"name": "get_task",
"description": "Gets a task by its identifier.",
"inputSchema": {
"type": "object",
"properties": {
"taskId": {
"type": "string",
"description": "The identifier of the task."
}
},
"required": [
"taskId"
]
}
}
]
}
使打包的定义与服务器保持一致。
使用动态工具发现
动态发现允许主机在运行时 tools/list 提取工具列表,而不是依赖打包的定义。
应用清单版本 1.29 或更高版本允许你省略 mcpToolDescription。 早期版本需要该文件。
Copilot Cowork 仍需要工具说明文件,即使版本为 1.29 或更高版本也是如此。 使用 WIQD 时,通过 --tool-descriptionWIQD 提供;请参阅 Work IQ Dev Tools。
对于支持动态发现的目标体验,请省 mcpToolDescription 略,以便它可以通过 检索定义 tools/list。 返回工具名称、描述和输入架构,并测试如何刷新对工具集所做的更改。
验证并测试插件
在部署之前验证包,然后在目标体验中对其进行测试:
- 根据完整应用清单的声明架构进行验证,并在开发人员门户中使用 应用包验证 。
- 验证终结点是否响应 MCP 初始化,以及打包的文件或
tools/list是否提供了有效的工具定义。 - 通过目标体验支持的进程将包部署到测试租户。 完成任何必需的管理员批准或访问配置。 部署不会取代用户登录、同意或源服务的权限。
- 测试服务器公开的操作提示,例如“搜索分配给我的未解决问题”,或对于具有写入工具的服务器,“更新票证编号 123 的状态”。
- 验证预期工具是否可用,在需要时显示同意提示,以及工具调用返回预期结果。 测试 OAuth 令牌刷新(如果适用)。
- 检查无效输入、服务不可用、授权错误和超时(包括重试行为)的失败。
- 如果您的方案需要多租户支持,请跨租户进行测试。
常见问题疑难解答
| 症状 | 支票 |
|---|---|
| 无法连接到服务器 | 终结点辅助功能、HTTPS、传输支持、防火墙设置和 MCP 初始化。 |
| 工具不显示 | 打包的文件路径和有效定义,或支持通过省略和 mcpToolDescription 工作 tools/list. |
| 身份验证失败 | 注册 referenceId、凭据有效性、权限、同意和出站授权标头。 |
| 工具调用失败或超时 | 服务器日志、输入验证、MCP 响应格式、并发、超时和重试。 |