Configurar servidores MCP remotos para plug-ins do Microsoft 365 Copilot

Um plug-in do Microsoft 365 Copilot conecta experiências Microsoft compatíveis a ferramentas fornecidas por um servidor MCP (protocolo de contexto de modelo) remoto. O pacote de plug-ins contém a configuração de conexão e o servidor é executado separadamente.

Use o Work IQ Dev Tools (WIQD) para criar, validar e empacotar seu plug-in. Comece com Criar um plug-in com as Ferramentas de Desenvolvimento do Work IQ.

As seções a seguir explicam a configuração subjacente para desenvolvedores que precisam editar o manifesto manualmente. Registre o servidor MCP remoto do plug-in na matriz do manifesto agentConnectors do aplicativo Microsoft 365. Esse identificador de esquema permanece agentConnectors mesmo que o pacote instalável seja chamado de plug-in.

Importante

Essa configuração usa o manifesto do aplicativo Microsoft 365, não o manifesto do plug-in MCP usado para ações de agente declarativo. Ele também é separado da rota de registro da CLI do Agente 365. Para essas alternativas, consulte Criar ou reutilizar servidores MCP. O suporte para MCP por si só não estabelece suporte para esse modelo de registro.

Pré-requisitos

Antes de começar, verifique se você tem:

  • Um locatário de teste e uma experiência de destino da Microsoft que dá suporte a plug-ins configurados por meio do agentConnectors.
  • Um servidor MCP em funcionamento com um ponto de extremidade HTTPS acessível publicamente, TLS 1.2 ou posterior e um transporte suportado pela experiência de destino.
  • Um pacote do aplicativo Microsoft 365 com uma versão de manifesto compatível com a experiência de destino e o tipo de autorização escolhido.
  • Uma configuração de autorização registrada para seu servidor, como uma configuração OAuth ou configuração de chave de API, a menos que o servidor permita acesso anônimo.

Para requisitos de servidor WIQD e o requisito de descrição da ferramenta Copilot Cowork, consulte Ferramentas de desenvolvimento do Work IQ.

Adicionar o servidor MCP ao manifesto do aplicativo

Declare seu servidor MCP na matriz agentConnectors no nível raiz do manifesto do aplicativo.

  1. Abra o manifesto do aplicativo no pacote do aplicativo Microsoft 365.
  2. Localize ou crie a matriz de nível agentConnectors raiz.
  3. Adicione uma entrada com um , um displayName, um descriptione um exclusivo idtoolSource que identifique seu servidor MCP remoto.

O JSON a seguir é um fragmento a ser mesclado ao manifesto do aplicativo existente, não um manifesto completo do aplicativo:

{
  "$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"
          }
        }
      }
    }
  ]
}

Substitua o ponto de extremidade e a referência de autorização pelos valores do servidor. Cada entrada deve ser única dentro agentConnectorsde id . Mantenha as outras propriedades obrigatórias do manifesto do aplicativo no arquivo existente.

Configurar o ponto de extremidade do servidor

Defina toolSource.remoteMcpServer.mcpServerUrl para o ponto de extremidade HTTPS. Confirme se o servidor está acessível a partir da experiência de destino e responde à inicialização do MCP e às solicitações de protocolo subsequentes.

Configurar autenticação

Definido authorization dentro de agentConnectors[].toolSource.remoteMcpServer. A tabela a seguir lista os tipos de autorização e suas configurações. Para obter detalhes do esquema, consulte o esquema de autorização.

Tipo de autorização Configuração
None Nenhuma autenticação é necessária. Use somente quando o servidor permitir acesso anônimo.
OAuthPluginVault Configuração do OAuth armazenada no cofre da Microsoft e referenciada por ID.
ApiKeyPluginVault Configuração de chave de API armazenada em um cofre e referenciada por ID.
DynamicClientRegistration Configuração de registro do cliente OAuth dinâmico referenciada pela ID.
AzureKeyVault Configuração do Azure Key Vault referenciada por ID. Requer suporte ao host.
ConnectionVault (Versão Prévia do Desenvolvedor) Configuração de conexão referenciada por ID.

Um valor de esquema não garante suporte na experiência de destino. Verifique seus requisitos de autenticação antes de escolher um método.

O referenceId identifica uma configuração adquirida separadamente do manifesto. Não coloque chaves de API, tokens de acesso, segredos de cliente ou valores secretos neste campo ou em outro lugar no manifesto do aplicativo.

Usar autenticação OAuth

Para tokens OAuth 2.0 armazenados no cofre da Microsoft, use o seguinte authorization objeto:

{
  "type": "OAuthPluginVault",
  "referenceId": "my-oauth-config"
}

Registre a configuração do OAuth no Portal do Desenvolvedor e use a ID de configuração retornada como referenceId. Para obter detalhes, consulte Configurar o OAuth no portal do desenvolvedor.

Adicione a seguinte URL de retorno de chamada aos URIs de redirecionamento permitidos no registro do provedor OAuth:

https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect

Usar autenticação de chave de API

Para obter uma chave de API armazenada em um cofre, use o seguinte authorization objeto:

{
  "type": "ApiKeyPluginVault",
  "referenceId": "my-apikey"
}

Registre a chave no Portal do Desenvolvedor e substitua-a my-apikey pela ID de registro retornada. Para obter detalhes, consulte Autenticação de chave de API.

Usar o registro de cliente dinâmico

O registro de cliente dinâmico permite que o host se registre como um cliente OAuth com seu servidor MCP usando o RFC 7591. Ambos devem dar suporte ao fluxo de registro. O Microsoft Entra ID não fornece um ponto de extremidade de registro RFC 7591; usar o registro OAuth estático para um servidor protegido por Entra.

Use o seguinte authorization objeto:

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

Registre a configuração no portal do desenvolvedor e substitua my-dcr-config por sua ID de referência. A configuração fornece os valores de autorização que o host usa ao negociar credenciais de cliente.

O servidor deve:

  • Exponha um ponto de extremidade de registro do cliente RFC 7591.
  • Retorne as informações de registro do cliente necessárias para o fluxo OAuth do host.
  • Suporte a atualização de token quando necessário para sessões de longa duração.

Usar a autenticação do Azure Key Vault

AzureKeyVault está incluído nos esquemas de manifesto de aplicativo 1.29 e 1.30. Use-o somente quando a experiência de destino documentar uma integração do Azure Key Vault e um processo para adquirir a referência de configuração.

Use o seguinte authorization objeto:

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

Siga os requisitos de armazenamento e acesso de credenciais dessa integração e substitua my-keyvault-config pela referência retornada. A declaração de manifesto por si só não concede acesso aos segredos.

Usar a autenticação do Cofre de Conexão

Observação

A autenticação do Cofre de Conexão está disponível no developer preview. Use o esquema de manifesto do aplicativo de visualização do desenvolvedor para configurar ConnectionVault; ele não está disponível em esquemas de manifesto de aplicativo geralmente disponíveis.

Para uma integração de cofre de conexão com suporte, use o seguinte authorization objeto:

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

Substitua shared_example pela referência de conexão fornecida pela integração de destino.

Não usar autenticação

Se o servidor permitir acesso anônimo, defina authorization.type como None ou omita authorization quando o host permitir.

Prefira acesso autenticado para cenários de produção e corporativos e OAuth em vez de chaves de API, quando há suporte.

Definir descoberta de ferramenta

Use definições de ferramentas empacotadas quando o conjunto de ferramentas for fixo ou descoberta dinâmica quando a versão do manifesto do aplicativo e o host de destino derem suporte a ela.

Use definições de ferramentas estáticas

Inclua um arquivo de descrição da ferramenta no pacote do aplicativo e faça referência a ele no remoteMcpServer. O caminho é relativo ao pacote do aplicativo. Use as definições de ferramenta do resultado do tools/list servidor, incluindo o nome, a descrição e o esquema de entrada de cada ferramenta. Por exemplo, um arquivo mínimo toolDescription.json pode conter:

{
  "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"
        ]
      }
    }
  ]
}

Mantenha as definições empacotadas consistentes com o servidor.

Usar a descoberta dinâmica de ferramentas

A descoberta dinâmica permite que um host busque a lista de ferramentas em tempo tools/list de execução, em vez de depender de definições empacotadas.

A versão 1.29 ou posterior do manifesto do aplicativo permite que você omita mcpToolDescription. Versões anteriores exigem o arquivo. O Copilot Cowork ainda requer um ficheiro de descrição da ferramenta, mesmo com a versão 1.29 ou posterior. Com o WIQD, forneça-o através de --tool-description; veja Work IQ Dev Tools.

Para uma experiência de destino que ofereça suporte à descoberta dinâmica, omita mcpToolDescription para que possa recuperar definições por meio do tools/list. Retornar nomes de ferramentas, descrições e esquemas de entrada e testar como as alterações no conjunto de ferramentas são atualizadas.

Valide e teste o seu plugin

Valide o pacote antes da implantação e teste-o na experiência de destino:

  1. Valide o manifesto completo do aplicativo em relação ao esquema declarado e use a validação do pacote do aplicativo no Portal do Desenvolvedor.
  2. Verifique se o ponto de extremidade responde à inicialização MCP e se o arquivo empacotado ou tools/list fornece definições de ferramenta válidas.
  3. Implante o pacote em seu locatário de teste por meio do processo com suporte da experiência de destino. Conclua qualquer configuração de acesso ou aprovação de administrador necessária. A implementação não substitui o início de sessão do utilizador, o consentimento ou as permissões do serviço de origem.
  4. Prompts de teste para as operações expostas pelo servidor, como "Procurar problemas em aberto atribuídos a mim" ou, para um servidor com ferramentas de gravação, "Atualizar o status do tíquete número 123".
  5. Verifique se as ferramentas pretendidas estão disponíveis, que são apresentados pedidos de consentimento quando necessário e que as chamadas efetuadas devolvem os resultados esperados. Teste a atualização do token OAuth quando aplicável.
  6. Verifique se há entradas inválidas, serviços indisponíveis, erros de autorização e tempos limite, incluindo comportamento de repetição.
  7. Teste entre inquilinos se o seu cenário exigir suporte multi-inquilino.

Resolver problemas comuns

Sintoma Verificação
Não é possível ligar ao servidor Acessibilidade de ponto final, HTTPS, suporte de transporte, configurações de firewall e inicialização MCP.
As ferramentas não são apresentadas Caminho do arquivo compactado e definições válidas, ou suporte para descoberta dinâmica com mcpToolDescription omitido e um .tools/list
Falha na autenticação Registado referenceId, validade de credencial, permissões, consentimento e cabeçalhos de autorização de saída.
As chamadas da ferramenta falham ou excedem o tempo limite Logs do servidor, validação de entrada, formato de resposta MCP, simultaneidade, tempos limite e tentativas.

Próximas etapas

Quando a integração estiver pronta, empacote seu plug-in e siga um método de publicação ou compartilhamento suportado.