Registrar servidores MCP como conectores de agente para o Microsoft 365

Os agentes no Microsoft 365 podem se conectar a sistemas externos por meio de conectores de agente declarados no manifesto do aplicativo. Este artigo mostra como registrar seu servidor MCP (protocolo de contexto de modelo) remoto no manifesto do aplicativo Microsoft 365, permitindo que os agentes do Microsoft 365 descubram, selecionem e invoquem com segurança as ferramentas MCP que seu servidor expõe.

Os agentes do Microsoft 365 usam conectores de agente para se comunicar com sistemas externos. Para servidores MCP, o conector fornece:

  • O ponto de extremidade de rede do servidor MCP
  • Configuração de autenticação e autorização
  • Definições da ferramenta
  • Metadados opcionais que ajudam os agentes a orquestrar a ferramenta certa durante as interações do usuário

Depois de registrado, seu servidor MCP fica disponível para qualquer agente do Microsoft 365 capaz de usar o MCP.

Pré-requisitos

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

  • Um locatário de teste para validar sua integração com o MCP
  • Um servidor MCP em funcionamento com um ponto de extremidade público seguro
  • Credenciais de autenticação (configuração OAuth ou chave de API)

Adicionar o conector do agente ao seu manifesto

Primeiro, declare seu servidor MCP na matriz agentConnectors no nível raiz do manifesto do aplicativo.

  1. Abra o arquivo de manifesto (manifest.json) do aplicativo Microsoft 365.

  2. Localize ou crie a matriz de nível agentConnectors raiz.

  3. Adicione um novo objeto conector com um , iddisplayName, e description:

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.27/MicrosoftTeams.schema.json",
  "manifestVersion": "1.27",
  ...
  "agentConnectors": [
    {
      "id": "my-mcp-server",
      "displayName": "My Automation Server",
      "description": "Provides workflow automation and task management tools.",
      "toolSource": {
        "remoteMcpServer": {
          "mcpServerUrl": "https://mcp.example.com"
        }
      }
    }
  ]
}

Cada conector deve ter um exclusivo id que o distingue de outros conectores em seu manifesto.

Configurar o ponto de extremidade do servidor MCP remoto

Defina como o Microsoft 365 se conecta ao seu servidor MCP usando o remoteMcpServer objeto.

  1. Na toolSource do conector, especifique o ponto de remoteMcpServer extremidade:

    "toolSource": {
  "remoteMcpServer": {
    "mcpServerUrl": "https://mcp.example.com"
  }
}

  2. Certifique-se de que seu ponto de extremidade use HTTPS (para conexões HTTP) ou WSS (para conexões WebSocket).

O ponto de extremidade deve ser acessível publicamente e responder às mensagens de handshake do protocolo MCP. Os agentes do Microsoft 365 estabelecem conexões duradouras com esse ponto de extremidade.

Configurar autenticação

Especifique como o Microsoft 365 recupera credenciais ao chamar seu servidor MCP. No momento, há suporte para os seguintes valores para a autenticação do servidor MCP:

  • Nenhum: nenhuma autenticação necessária
  • OAuthPluginVault: tokens OAuth 2.0 armazenados no cofre seguro da Microsoft
  • ApiKeyPluginVault: chave de API armazenada em um cofre e referenciada por ID
  • DynamicClientRegistration: registro de cliente OAuth dinâmico
  • AzureKeyVault: segredos armazenados em sua própria instância Azure Key Vault

Usar autenticação OAuth

Para tokens OAuth 2.0 armazenados no cofre seguro da Microsoft, especifique o tipo OAuthPluginVault de autorização em sua configuração:

"remoteMcpServer": {
  "mcpServerUrl": "https://mcp.example.com",
  "authorization": {
    "type": "OAuthPluginVault",
    "referenceId": "my-oauth-config"
  }
}

O referenceId aponta para uma configuração OAuth segura que você registra no Portal do Desenvolvedor. Para obter detalhes, consulte Configurar o OAuth no portal do desenvolvedor.

Ao configurar seu aplicativo OAuth com um provedor de autenticação de terceiros, certifique-se de adicionar https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect à lista de pontos de extremidade de redirecionamento permitidos.

Usar autenticação de chave de API

Para chaves de API armazenadas em um cofre, configure o tipo de autorização como ApiKeyPluginVault:

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

Isso referenceId aponta para uma chave de API que você registra no Portal do desenvolvedor. 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 Microsoft 365 se registre como um cliente OAuth com seu servidor MCP em runtime usando o protocolo RFC 7591 . Essa abordagem é útil quando o servidor dá suporte a fluxos OAuth dinâmicos e você não deseja registrar previamente as credenciais do cliente.

Configure o tipo de autorização como DynamicClientRegistration com:referenceId

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

O referenceId aponta para uma configuração de registro de cliente dinâmico que você registra no Portal do Desenvolvedor. Essa configuração fornece os valores de autorização necessários que o Microsoft 365 usa ao negociar credenciais de cliente com o ponto de extremidade de registro OAuth do servidor MCP.

O servidor deve:

  • Expor um ponto de extremidade de registro de cliente compatível com RFC 7591 .
  • Retorne um client_id e client_secret que o Microsoft 365 pode usar para obter tokens de acesso.
  • Atualização de token de suporte para sessões de longa duração.

Usar autenticação Azure Key Vault

Azure Key Vault autenticação permite que você armazene e gerencie suas credenciais de servidor MCP em sua própria instância Azure Key Vault. Isso lhe dá controle total sobre o gerenciamento do ciclo de vida secreto, incluindo rotação, políticas de acesso e log de auditoria.

Configure o tipo de autorização como AzureKeyVault:

"authorization": {
  "type": "AzureKeyVault",
  "referenceId": "my-keyvault-secret"
}

O referenceId aponta para um identificador secreto registrado no Portal do Desenvolvedor que mapeia para seu Azure Key Vault segredo.

Para configurar Azure Key Vault autenticação:

  1. Armazene suas credenciais do servidor MCP (chave de API ou segredo do cliente) como um segredo em seu Azure Key Vault.
  2. Conceda à entidade de serviço do Microsoft 365 acesso para ler o segredo configurando uma política de acesso ou uma função RBAC do Azure em seu cofre.
  3. Registre a referência secreta no Portal do Desenvolvedor e anote a ID de registro.
  4. Use a ID de registro como o em seu manifesto referenceId .

Não usar autenticação

Se o servidor não exigir autenticação (não recomendado para produção), defina o tipo None de autorização como ou omita o authorization objeto inteiramente.

Para cenários corporativos, prefira OAuth em vez de chaves de API para se alinhar às práticas recomendadas de segurança e às expectativas do administrador.

Definir descoberta de ferramenta

Configure como os agentes do Microsoft 365 descobrem as ferramentas que seu servidor MCP fornece. Use definições estáticas de ferramentas embutidas quando seu conjunto de ferramentas estiver estável ou habilite a descoberta dinâmica de ferramentas quando seu conjunto de ferramentas mudar com frequência.

Use definições de ferramentas estáticas

Para conjuntos de ferramentas estáticos que não mudam com frequência, adicione um mcpToolDescription objeto com suas definições de ferramenta:

"remoteMcpServer": {
  "mcpServerUrl": "https://mcp.example.com",
  "authorization": {
    "type": "ApiKeyPluginVault",
    "referenceId": "my-apikey"
  },
  "mcpToolDescription": {
    "description": {
      "file": "toolDescription.json"
    }
  }
}

O description objeto deve corresponder ao esquema retornado pela resposta do tools/list servidor MCP.

Usar a descoberta dinâmica de ferramentas

A descoberta dinâmica de ferramentas permite que os agentes do Microsoft 365 busquem sua lista de ferramentas em tempo de execução chamando o tools/list método do servidor. Essa abordagem é recomendada quando seu conjunto de ferramentas muda com frequência, pois elimina a necessidade de republicar seu aplicativo sempre que as ferramentas são adicionadas, atualizadas ou removidas.

Para habilitar a descoberta dinâmica de ferramentas, omita o mcpToolDescription da configuração do remoteMcpServer :

"remoteMcpServer": {
  "mcpServerUrl": "https://mcp.example.com",
  "authorization": {
    "type": "OAuthPluginVault",
    "referenceId": "my-oauth-config"
  }
}

Quando mcpToolDescription é omitido, os agentes do Microsoft 365:

  • Conecte-se ao ponto de extremidade do servidor MCP.
  • Chame o tools/list método para recuperar as ferramentas disponíveis em runtime.
  • Atualize a lista de ferramentas disponíveis sem exigir uma republicação de manifesto.

O servidor MCP deve retornar uma resposta válida tools/list que inclua o nome, a descrição e o esquema de entrada de cada ferramenta.

Validar sua configuração

Antes de implantar seu agente ou aplicativo, verifique se o manifesto e o servidor MCP estão configurados corretamente.

  1. Use a ferramenta de validação de pacote do aplicativo Microsoft 365 no Portal do desenvolvedor para marcar se há erros no manifesto.

  2. Verifique se o servidor MCP responde corretamente às mensagens de handshake testando a conexão manualmente.

  3. Confirme se o tools/list ponto de extremidade retorna definições de ferramenta compatíveis com esquema:

    • Cada ferramenta tem um nome e uma descrição exclusivos
    • Os esquemas de entrada são válidos Esquema JSON
    • Os parâmetros obrigatórios e opcionais são claramente definidos

  4. Teste sua configuração de autorização:

    • Verificar os referenceId pontos para um segredo válido
    • Confirmar se os tokens ou chaves foram recuperados corretamente
    • Testar atualização do token se estiver usando OAuth

  5. Verifique se o ponto de extremidade é compatível com TLS 1.2 ou superior.

  6. Verifique as mensagens de erro e repita a semântica para chamadas de ferramenta com falha.

Teste com agentes do Microsoft 365

Valide sua integração testando com agentes reais do Microsoft 365.

  1. Implante seu agente ou aplicativo em um ambiente de teste.

  2. Abra um agente do Microsoft 365 que dê suporte a MCP.

  3. Teste os comandos de linguagem natural que devem acionar suas ferramentas:

    • "Criar uma tarefa no meu sistema de gerenciamento de projetos"
    • "Atualizar o status do tíquete número 123"
    • "Pesquisar problemas abertos atribuídos a mim"

  4. Verifique se:

    • As ferramentas aparecem nas ações disponíveis do agente
    • Os avisos de consentimento do usuário são exibidos quando necessário
    • As chamadas de ferramenta são executadas com êxito
    • As respostas são processadas corretamente
    • As condições de erro são tratadas normalmente

  5. Teste em vários locatários se o cenário exigir suporte a vários locatários.

Solução de problemas comuns

Se o servidor MCP não estiver funcionando conforme o esperado, Marque estes problemas comuns:

O agente não pode se conectar a seu servidor

  • Verifique se o ponto de extremidade está acessível publicamente
  • Confirme se o ponto de extremidade usa HTTPS ou WSS
  • Verificar configurações de segurança de rede e firewall
  • Certifique-se de que seu servidor responda às mensagens de handshake MCP

As ferramentas não aparecem nos agentes

  • Verificar tools/list retorna definições de ferramenta válidas
  • Verifique se as descrições das ferramentas estão claras e completas
  • Para definições estáticas, valide o esquema JSON das definições de ferramenta embutida
  • Para descoberta dinâmica, confirmar mcpToolDescription é omitido e seu servidor responde corretamente em tempo de tools/list execução

Falhas de autenticação

  • Verifique se as correspondências com a referenceId configuração do segredo armazenado
  • Teste se os tokens OAuth são válidos e não expiraram
  • Confirmar se as chaves de API têm as permissões necessárias
  • Verificar o formato do cabeçalho de autorização em solicitações de saída

As chamadas de ferramenta falham ou atingem o tempo limite

  • Examine os logs do servidor para encontrar erros
  • Verifique se a validação do parâmetro de entrada está funcionando corretamente
  • Verifique se as respostas seguem o formato do protocolo MCP
  • Verifique se o servidor lida com solicitações simultâneas

Próximas etapas

Quando estiver pronto, envie seu aplicativo para certificação e publicação de parceiros.

  • Last updated on