針對 Microsoft 365 Copilot 外掛程式設定遠端 MCP 伺服器

Microsoft 365 Copilot 外掛程式可將支援的Microsoft體驗連線至遠端模型內容通訊協定 (MCP) 伺服器所提供的工具。 外掛程式套件包含連線配置,伺服器單獨執行。

使用 Work IQ 開發工具 (WIQD) 來建立、驗證及封裝您的外掛程式。 從 使用 Work IQ 開發工具建置外掛程式開始。

下列各節為需要手動編輯資訊清單的開發人員說明基礎設定。 在 Microsoft 365 應用程式資訊清單的陣列中 agentConnectors 註冊外掛程式的遠端 MCP 伺服器。 即使可安裝套件稱為外掛程式,此結構描述識別碼仍會保留 agentConnectors 。

重要

此設定使用 Microsoft 365 應用程式資訊清單,而不是用於宣告式代理程式動作的 MCP 外掛程式資訊清單。 它也與代理程式 365 CLI 註冊路由分開。 如需這些替代方案,請參閱 建置或重複使用 MCP 伺服器。 僅支援 MCP 並無法為此註冊模型建立支援。

先決條件

開始之前,請確定您已:

  • 支援透過設定 agentConnectors外掛程式的測試租用戶和目標 Microsoft 體驗。
  • 運作中的 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"
          }
        }
      }
    }
  ]
}

將端點和授權參照取代為您的伺服器值。 每個項目都idagentConnectors必須是唯一的。 將其他必要的應用程式資訊清單屬性保留在現有檔案中。

設定伺服器端點

將 toolSource.remoteMcpServer.mcpServerUrl 設定為 HTTPS 端點。 確認伺服器可從目標體驗連線,並回應 MCP 初始化和後續通訊協定要求。

設定驗證

設定在 之內agentConnectors[].toolSource.remoteMcpServer。authorization 下表列出授權類型及其設定。 如需結構描述詳細資訊,請參閱 授權結構描述。

授權類型 設定
None 不需驗證。 只有在伺服器允許匿名存取時才使用。
OAuthPluginVault OAuth 設定會儲存在 Microsoft 保存庫中,並由識別碼參考。
ApiKeyPluginVault 儲存在保存庫中並由識別碼參照的 API 金鑰設定。
DynamicClientRegistration 識別碼參考的動態 OAuth 用戶端註冊設定。
AzureKeyVault 識別碼參考的 Azure Key Vault 設定。 需要主機支援。
ConnectionVault (開發人員預覽) 識別碼參考的連線設定。

結構描述值無法保證目標體驗中的支援。 選擇方法之前,請先檢查其驗證需求。

識別 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 傳回的註冊識別碼取代。 如需詳細資料,請參閱 API 金鑰驗證。

使用動態用戶端註冊

動態用戶端登錄可讓主機使用 RFC 7591 向 MCP 伺服器註冊為 OAuth 用戶端。 兩者都必須支援註冊流程。 Microsoft Entra ID 不提供 RFC 7591 註冊端點;對受 Entra 保護的伺服器使用靜態 OAuth 註冊。

使用下列 authorization 物件:

{
  "type": "DynamicClientRegistration",
  "referenceId": "my-dcr-config"
}

在 開發人員入口網站 中登錄組態,並以其參考 ID 取代 my-dcr-config 。 組態提供主機在交涉用戶端認證時所使用的授權值。

您的伺服器必須:

  • 公開 RFC 7591 用戶端註冊端點。
  • 傳回主機的 OAuth 流程所需的用戶端註冊資訊。
  • 在需要長時間工作階段時支援權杖重新整理。

使用 Azure Key Vault 驗證

AzureKeyVault 包含在應用程式資訊清單結構描述 1.29 和 1.30 中。 只有在目標體驗記錄 Azure Key Vault 整合,以及取得設定參考的程序時才使用它。

使用下列 authorization 物件:

{
  "type": "AzureKeyVault",
  "referenceId": "my-keyvault-config"
}

遵循該整合的認證儲存和存取需求,並以 my-keyvault-config 傳回的參照取代。 僅憑資訊清單宣告不會授與對密碼的存取權。

使用連線保存庫驗證

注意

連線保存庫驗證在開發人員預覽中提供。 使用開發人員預覽應用程式資訊清單結構描述進行設定 ConnectionVault; 它不適用於一般可用的應用程式資訊清單結構描述。

如需支援的連線保存庫整合,請使用下列 authorization 物件:

{
  "type": "ConnectionVault",
  "referenceId": "shared_example"
}

shared_example取代為目標整合提供的連線參照。

不使用驗證

如果您的伺服器允許匿名存取,請在主機允許時設定authorization.typeNone或省略authorization。

針對生產和企業案例偏好已驗證的存取權,以及在支援的情況下優先使用 API 金鑰之上的 OAuth。

定義工具探索

當工具集已修正時使用封裝工具定義,或在應用程式資訊清單版本和目標主機都支援時使用動態探索。

使用靜態工具定義

在您的應用程式套件中包含工具描述檔案,並在 中引用它。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。 舊版需要此檔案。 即使已是 1.29 版或更新版本,Copilot Cowork 仍然需要工具描述檔案。 使用 WIQD,請透過 --tool-description; 請參閱 Work IQ 開發工具來提供。

對於支援動態探索的目標體驗,請省略 mcpToolDescription ,以便透過 擷取定義 tools/list。 傳回工具名稱、描述和輸入結構描述,並測試如何重新整理對工具集的變更。

驗證並測試您的外掛程式

在部署之前驗證套件,然後在目標體驗中進行測試:

  1. 根據其宣告的結構描述驗證完整的應用程式資訊清單,並在開發人員入口網站中使用 應用程式套件驗證 。
  2. 確認端點回應 MCP 初始化,以及封裝檔案或 tools/list 提供有效的工具定義。
  3. 透過目標體驗支援的程序,將套件部署到您的測試租用戶。 完成任何必要的管理員核准或存取設定。 部署不會取代使用者登入、同意或來源服務的權限。
  4. 測試伺服器公開作業的提示,例如「搜尋指派給我的未解決問題」,或對於具有寫入工具的伺服器,「更新票證號碼 123 的狀態」。
  5. 確認預期的工具可用、同意提示會在需要時出現,工具呼叫會傳回預期的結果。 如果適用,請測試 OAuth 權杖重新整理。
  6. 檢查無效輸入、無法使用服務、授權錯誤和逾時的失敗,包括重試行為。
  7. 如果您的案例需要多租用戶支援,請跨租用戶進行測試。

常見問題疑難排解

問題 支票
無法連線到伺服器 端點協助工具、HTTPS、傳輸支援、防火牆設定和 MCP 初始化。
工具未出現 封裝檔案路徑和有效定義,或支援具有 mcpToolDescription 省略和有效 tools/list.
驗證失敗 Registered referenceId、認證有效性、權限、同意和輸出授權標頭。
工具呼叫失敗或逾時 伺服器記錄、輸入驗證、MCP 回應格式、並行、逾時和重試。

後續步驟

整合準備就緒時, 請封裝您的外掛程式 ,並遵循支援的 發佈或共用方法。