为 智能 Microsoft 365 Copilot 副驾驶® 插件配置远程 MCP 服务器

智能 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 服务器。

  1. 在 Microsoft 365 应用包中打开应用清单。
  2. 找到或创建根级 agentConnectors 数组。
  3. 添加一个带有唯一 id、 a displayName、a description和 a toolSource 的条目,用于标识远程 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。 返回工具名称、描述和输入架构,并测试如何刷新对工具集所做的更改。

验证并测试插件

在部署之前验证包,然后在目标体验中对其进行测试:

  1. 根据完整应用清单的声明架构进行验证,并在开发人员门户中使用 应用包验证 。
  2. 验证终结点是否响应 MCP 初始化,以及打包的文件或 tools/list 是否提供了有效的工具定义。
  3. 通过目标体验支持的进程将包部署到测试租户。 完成任何必需的管理员批准或访问配置。 部署不会取代用户登录、同意或源服务的权限。
  4. 测试服务器公开的操作提示,例如“搜索分配给我的未解决问题”,或对于具有写入工具的服务器,“更新票证编号 123 的状态”。
  5. 验证预期工具是否可用,在需要时显示同意提示,以及工具调用返回预期结果。 测试 OAuth 令牌刷新(如果适用)。
  6. 检查无效输入、服务不可用、授权错误和超时(包括重试行为)的失败。
  7. 如果您的方案需要多租户支持,请跨租户进行测试。

常见问题疑难解答

症状 支票
无法连接到服务器 终结点辅助功能、HTTPS、传输支持、防火墙设置和 MCP 初始化。
工具不显示 打包的文件路径和有效定义,或支持通过省略和 mcpToolDescription 工作 tools/list.
身份验证失败 注册 referenceId、凭据有效性、权限、同意和出站授权标头。
工具调用失败或超时 服务器日志、输入验证、MCP 响应格式、并发、超时和重试。

后续步骤

集成准备就绪后, 打包插件 并遵循支持 的发布或共享方法。