Traga seu próprio servidor MCP (BYO)

Ao usar o recurso de servidor MCP Bring Your Own (BYO), sua organização pode registrar seus próprios servidores remotos do Model Context Protocol (MCP) com o Microsoft Agent 365 para governança centralizada e observabilidade.

Importante

  • Este recurso está em versão preliminar.
  • As versões prévias do recurso não foram criadas para uso em ambientes de produção e podem ter funcionalidade restrita. Esses recursos estão sujeitos a termos de uso complementares e estão disponíveis antes do lançamento oficial, de maneira que os clientes possam obter acesso antecipado e fazer comentários.

As grandes empresas geralmente criam e operam servidores MCP internos para capacitar seus agentes em vários fluxos de trabalho de negócios. Esses servidores normalmente são executados fora de qualquer limite de governança organizacional, sem visibilidade do administrador sobre quais ferramentas são expostas, sem imposição de política sobre como elas são invocadas e sem telemetria de uso para equipes de segurança e conformidade. O servidor BYO MCP resolve esse problema roteando servidores registrados por meio do Gateway de Ferramentas do Agent 365, fornecendo aos administradores de TI controle por meio do Centro de administração do Microsoft 365 e às equipes de segurança os dados de observabilidade necessários.

Note

As superfícies de cliente com suporte durante a versão prévia são o Copilot Studio, o Visual Studio Code, o Claude Code e o CLI do GitHub Copilot. Não há suporte para o Fábrica de IA do Azure e os Agentes Declarativos do Microsoft 365.

Como funciona um servidor MCP BYO

Um servidor BYO MCP segue esse fluxo de desenvolvedor para administrador para que os servidores MCP remotos sejam revisados e governados antes que os agentes possam acessá-los:

O registro e a aprovação nesse fluxo se aplicam ao servidor MCP, não a um pacote completo de plugins. Eles não aprovam automaticamente agentes ou plugins que usam o servidor. Não presuma que esses controles se aplicam a todos os produtos ou componentes conectados.

  1. Um desenvolvedor registra o servidor por meio da CLI do Agent 365 e fornece a URL do servidor, o tipo de autenticação e as ferramentas para expor. Para obter mais informações, consulte Registrar um servidor MCP remoto.

  2. Um administrador de TI analisa o pedido no Centro de administração do Microsoft 365 e o aprova ou rejeita. Após a aprovação, o administrador concede as permissões necessárias do Microsoft Entra para o servidor. Para obter mais informações, consulte Examinar e aprovar solicitações de MCP.

  3. Clientes suportados utilizam o servidor aprovado, como Copilot Studio e Visual Studio Code, para construir e testar agentes com invocações reais de ferramentas. Para obter mais informações, consulte Usar um servidor MCP aprovado.

  4. A equipe de segurança monitora a atividade e as invocações de ferramentas por meio do Microsoft Defender Advanced Hunting para conformidade e detecção de anomalias. Para obter mais informações, consulte Monitorar e observar a atividade do servidor MCP.

Importante

Esse processo requer revisões de governança e conformidade antes que as integrações externas do MCP se tornem disponíveis para os usuários finais.

Note

Não é possível republicar novas versões do seu servidor MCP remoto durante a visualização.

Registrar um servidor MCP remoto

Dica

Os administradores podem usar essas etapas para entender o processo de registro ou fornecê-las a um desenvolvedor.

Você ou um desenvolvedor pode registrar um servidor MCP remoto com o Agent 365 usando a CLI. Após o registro, um administrador de TI pode revisar e aprovar o servidor para uso em superfícies de construção de agentes.

Conclua as tarefas a seguir:

Pré-requisitos do desenvolvedor

Antes de registrar um servidor MCP remoto, certifique-se de que:

  • Instalei a CLI do Agent 365 versão 1.1.165-preview ou posterior.

  • O service principal do Agent 365 é provisionado em seu tenant. Se você não encontrar a entidade de serviço associada à ID ea9ffc3e-8a23-4a7d-836d-234d7c7565c1do aplicativo, provisione-a usando os seguintes recursos:

  • Seu servidor MCP tem um endpoint acessível publicamente.

  • O servidor usa um dos seguintes tipos de autenticação com suporte:

    • NoAuth.
    • APIKey com um cabeçalho ou parâmetro de consulta.
    • ExternalOAuth.
    • EntraOAuth.

Instale a CLI do Agent 365

Para instalar a CLI do Agent 365, siga as instruções em Instalar a CLI do Agent 365.

Registre seu servidor MCP

Escolha um dos seguintes métodos para registrar seu servidor MCP no Agent 365:

  • Registro manual via CLI: execute o a365 develop-mcp register-external-mcp-server comando a partir da CLI e forneça manualmente os detalhes do servidor, o tipo de autenticação e as ferramentas que seu servidor MCP expõe.
  • Registro via arquivo JSON: Use a365 develop-mcp register-external-mcp-server -f <path-to-file.json> para registrar seu servidor MCP fornecendo um arquivo JSON que contenha todos os detalhes do servidor, tipo de autenticação e definições de ferramentas em um único arquivo, em vez de especificá-los individualmente na linha de comando.

Importante

Os exemplos a seguir usam zava.com como domínio fictício e nomes genéricos de servidores e ferramentas para ilustração. Substitua esses valores pela URL do servidor, nome e identificadores de ferramenta reais.

Os exemplos a seguir mostram como registrar um servidor MCP usando a CLI do Agent 365 com diferentes tipos de autenticação.

NoAuth

Para servidores MCP que não exigem autenticação:

a365 develop-mcp register-external-mcp-server \
--server-name "ZavaServer" \
--server-url "https://mcp.zava.com/mcp" \
--publisher "Contoso" \
--description "My external MCP server for document search" \
--auth-type "NoAuth" \
--tools "tool1,tool2"
{
  "serverName": "ext_DocsSearch",
  "serverUrl": "https://docs.contoso.com/api/mcp",
  "authType": "NoAuth",
  "description": "Documentation search MCP Server for Contoso developer docs.",
  "publisherName": "Contoso",
  "tools": [
    {
      "name": "search_docs",
      "description": "Search Contoso developer documentation and code samples."
    }
  ],
  "remoteScopes": null,
  "externalOAuth": null,
  "apiKey": null
}

APIKey (parâmetro de consulta)

Para servidores que passam a chave de API como um parâmetro de consulta:

a365 develop-mcp register-external-mcp-server \
--server-name "ZavaServer" \
--server-url "https://mcp.zava.com/mcp" \
--publisher "Contoso" \
--description "My external MCP server for document search" \
--auth-type APIKey \
--api-key-location Query \
--api-key-name apiKey \
--tools "tool1,tool2"
{
  "serverName": "ext_MarketData",
  "serverUrl": "https://api.contoso.com/market/mcp",
  "authType": "APIKey",
  "description": "Real-time stock market data and search from Contoso Market Services.",
  "publisherName": "Contoso",
  "tools": [
    {
      "name": "stock-market-data",
      "description": "Get real-time stock market data and financial information."
    },
    {
      "name": "real-time-search",
      "description": "Search the web for real-time information and news."
    }
  ],
  "remoteScopes": null,
  "externalOAuth": null,
  "apiKey": {
    "location": "Query",
    "name": "apiKey"
  }
}

APIKey (cabeçalho)

Para servidores que passam a chave de API em um cabeçalho de solicitação:

a365 develop-mcp register-external-mcp-server \
--server-name "ZavaServer" \
--server-url "https://mcp.zava.com/mcp" \
--publisher "Contoso" \
--description "My external MCP server for document search" \
--auth-type APIKey \
--api-key-location Header \
--api-key-name token \
--tools "tool1,tool2"
{
  "serverName": "ext_InternalTools",
  "serverUrl": "https://tools.contoso.com/mcp",
  "authType": "APIKey",
  "description": "Contoso internal tools MCP Server with API key authentication.",
  "publisherName": "Contoso",
  "tools": [
    {
      "name": "tool1",
      "description": "First tool exposed by the server."
    },
    {
      "name": "tool2",
      "description": "Second tool exposed by the server."
    }
  ],
  "remoteScopes": null,
  "externalOAuth": null,
  "apiKey": {
    "location": "Header",
    "name": "X-API-Key"
  }
}

ExternalOAuth

Para servidores que se autenticam por meio de um provedor OAuth externo:

a365 develop-mcp register-external-mcp-server \
--server-name "ZavaServer" \
--server-url "https://zava.com/mcp" \
--publisher "Contoso" \
--description "My external MCP server for document search" \
--auth-type ExternalOAuth \
--idp-authorization-url "https://idp.zava.com/o/oauth2/v2/auth" \
--idp-token-url "https://idp.zava.com/oauth2/token" \
--idp-scopes "https://api.zava.com/read" \
--idp-client-id "<your-client-id>" \
--idp-client-secret "<your-client-secret>" \
--remote-scopes "https://api.zava.com/read" \
--tools "tool1,tool2"

{
  "serverName": "ext_Analytics",
  "serverUrl": "https://analytics.contoso.com/mcp",
  "authType": "ExternalOAuth",
  "description": "Contoso Analytics MCP Server for dataset and query operations.",
  "publisherName": "Contoso",
  "tools": [
    {
      "name": "list_datasets",
      "description": "List all available analytics datasets."
    }
  ],
  "remoteScopes": "https://analytics.contoso.com/.default",
  "externalOAuth": {
    "authorizationUrl": "https://auth.contoso.com/oauth2/authorize",
    "tokenUrl": "https://auth.contoso.com/oauth2/token",
    "scopes": "https://analytics.contoso.com/.default",
    "clientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "clientSecret": "<your-client-secret>"
  },
  "apiKey": null
}

EntraOAuth

Para servidores que se autenticam por meio do Microsoft Entra ID:

a365 develop-mcp register-external-mcp-server \
--server-name "ZavaServer" \
--server-url "https://mcp.zava.com/mcp" \
--publisher "Contoso" \
--description "My external MCP server for document search" \
--auth-type EntraOAuth \
--remote-scopes "https://api.zava.com/.default" \
--tools "tool1,tool2"
{
  "serverName": "ext_OrgDirectory",
  "serverUrl": "https://directory.contoso.com/mcp",
  "authType": "EntraOAuth",
  "description": "Contoso organization directory MCP Server secured with Entra OAuth.",
  "publisherName": "Contoso",
  "tools": [
    {
      "name": "list_users",
      "description": "List users in the organization directory."
    },
    {
      "name": "get_user_profile",
      "description": "Get the profile of a specific user by ID or UPN."
    }
  ],
  "remoteScopes": "api://contoso-directory/.default",
  "externalOAuth": null,
  "apiKey": null
}

Após o registro bem-sucedido, envie o servidor MCP para revisão pelo administrador no Centro de administração do Microsoft 365.

Avaliar servidores MCP

Você pode avaliar a qualidade das definições das suas ferramentas MCP usando o a365 develop-mcp evaluate comando. Esse comando inspeciona os esquemas de ferramentas do servidor e gera um relatório com orientações acionáveis para melhorar os nomes de ferramentas, descrições e esquemas de parâmetros.

A CLI do agente de codificação (GitHub Copilot CLI ou Claude Code) que roda localmente na sua máquina, sob sua própria conta e assinatura de IA, faz as verificações semânticas. Esse comando não envia dados de esquema de ferramenta para a Microsoft.

Importante

Execute evaluate apenas contra servidores MCP nos quais você confia. Os nomes de ferramentas, descrições e esquemas de parâmetros do servidor são lidos por meio de uma chamada MCP tools/list padrão e entregues a um agente de codificação em execução em seu computador para pontuação. Esse aviso de confiança é impresso uma vez no início de cada execução que usa um agente. Não se aplica a --eval-engine none, que mantém tudo local.

Você não precisa de uma função de administrador para executar a avaliação. Ele é executado localmente na URL do servidor MCP que você fornece e não chama o Azure ou o Microsoft Graph.

Prerequisites

  • Instale o Agent 365 CLI.
  • Para pontuação semântica (IA), instale um CLI de agente de codificação localmente:
    • GitHub Copilot CLI: Instale com npm install -g @github/copilot (Node.js 18 ou posterior). Essa CLI é o binário independentecopilot, não a gh copilot extensão da CLI do GitHub.
    • Claude Code: Instale com npm install -g @anthropic-ai/claude-code, ou siga instalação do Claude Code.
  • Se você não instalar nenhum dos agentes, o comando ainda executa as verificações determinísticas e escreve a lista de verificação, depois para para que você possa pontuar as verificações semânticas com seu próprio LLM (trazer seu próprio LLM). Informe --eval-engine none para ignorar totalmente a sondagem do agente.

Como funciona a avaliação

O comando executa um pipeline de cinco etapas e registra o progresso, conforme mostrado na tabela a seguir:

Step O que faz
1. Descubra ferramentas Conecta-se ao servidor MCP, chama tools/liste captura o esquema de cada ferramenta.
2. Gerar lista de verificação Grava <server-name>_checklist.json no diretório de saída.
3. Executar a avaliação semântica Entregue a lista de verificação ao agente de codificação selecionado para pontuação. Pula quando você especifica --eval-engine none ou não há agente disponível.
4. Analise Agrega pontuações gerais e por ferramenta e determina o nível de maturidade.
5. Escreva relatórios Produz <server-name>_eval_report.html e <server-name>_eval_report.json.

Cada verificação é de um dos dois tipos:

  • Determinístico: Lógica baseada em regras na CLI; aprovar ou reprovar é exato e não precisa de IA (por exemplo, "nome da ferramenta não está vazio").
  • Semântica: Pontuada pelo agente de codificação, com uma reason string explicando o julgamento.

A execução é idempotente. Reexecutar o mesmo comando reutiliza um comando existente <server-name>_checklist.json e pula a descoberta do servidor. Esse processo apoia a viagem de ida e volta de trazer seu próprio LLM: pontuar a lista de verificação você mesmo e depois reiniciar para retomar. Exclua o arquivo de lista de verificação para forçar uma nova descoberta depois de alterar os esquemas de ferramentas.

Examples

Avalie um servidor local com a seleção automática de mecanismo:

a365 develop-mcp evaluate --server-url "http://localhost:5000/mcp"

Avalie um servidor autenticado, com o token fornecido por meio de uma variável de ambiente e artefatos gravados em uma subpasta:

$env:A365_MCP_AUTH_TOKEN = "<bearer-token>"
a365 develop-mcp evaluate --server-url "https://my-mcp-server.contoso.com/mcp" --output-dir "./eval"

Gere apenas a lista de verificação e, em seguida, pontue-a com seu próprio LLM:

a365 develop-mcp evaluate --server-url "https://my-mcp-server.contoso.com/mcp" --eval-engine none

Forçar um mecanismo de pontuação específico:

a365 develop-mcp evaluate --server-url "http://localhost:5000/mcp" --eval-engine claude-code

Leia o relatório

Abra <server-name>_eval_report.html a partir do diretório de saída em um navegador. O relatório mostra:

  • A pontuação geral (0-100; quanto maior, melhor).
  • Pontuações por ferramenta com detalhamentos de categoria: nome da ferramenta, descrição da ferramenta, nome do parâmetro, descrição do parâmetro e estrutura de esquema.
  • Uma lista de itens de ação priorizada, ordenada por impacto, incluindo os requisitos concretos para atingir o próximo nível de maturidade.

Captura de tela do relatório HTML develop-mcp Evaluate mostrando a pontuação geral de qualidade, nível de maturidade, contagem de chaves e pontuações por categoria por dimensão.

Tratamento de dados e transparência da IA

  • O comando processa apenas os esquemas de ferramentas estáticas do seu servidor MCP (nomes, descrições e esquemas de parâmetros) de tools/list. Ele não processa payloads de execução, dados do usuário final ou dados pessoais.
  • A CLI do agente de codificação é executada em seu computador com sua própria assinatura de IA. A chamada à API modelo é feita diretamente por essa CLI ao provedor de IA de acordo com seus termos de serviço e cobrança. A a365 CLI especifica o modelo, mas não medeia a chamada.
  • O --auth-token valor é mantido na memória, enviado somente como o cabeçalho HTTP Authorization para o servidor e nunca gravado em disco ou passado para o agente de codificação.
  • Os arquivos de saída (_checklist.json, _eval_report.html, _eval_report.json) são gravados apenas em seu --output-dir e permanecem em seu computador.

Troubleshooting

Use o guia de solução de problemas a seguir para diagnosticar erros comuns e aplicar a correção recomendada.

Sintoma Causa provável Corrigir
Unauthorized direto de tools/list Bearer token incorreto ou expirado Adquira novamente o token e passe-o por A365_MCP_AUTH_TOKEN.
Unknown eval engine Valor --eval-engine inválido Use um de auto, github-copilot, claude-code ou none.
O pipeline para após [2/5] Nenhum agente de codificação ativado PATH Instale a CLI do GitHub Copilot ou o Claude Code ou pontue a lista de verificação por conta própria e execute novamente.
--output-dir cannot be empty or whitespace Um valor vazio foi passado para --output-dir Passe um caminho de diretório válido ou omita a opção de usar o diretório atual.
Failed to read existing checklist O arquivo de lista de verificação está bloqueado ou malformado Exclua o arquivo de checklist para forçar uma nova descoberta na próxima execução.

Examinar e aprovar solicitações do servidor BYO MCP

Depois que um desenvolvedor registra um servidor BYO MCP, um administrador o revisa e aprova da mesma forma que qualquer outra solicitação de ferramenta. Para obter as etapas completas de revisão e aprovação, consulte Revisar e aprovar solicitações de MCP.

Principais controles de governança

A tabela a seguir resume os principais controles de governança:

Controle Description
Aprovação ou rejeição Um administrador aprova ou rejeita cada servidor BYO MCP antes que ele possa ser usado.
Bloqueio no nível do servidor Um administrador pode bloquear um servidor aprovado. O Gateway de Ferramentas Agent 365 impede que clientes suportados invoquem o servidor bloqueado através do gateway.
Bloco no nível da ferramenta O bloqueio individual de ferramentas para servidores MCP BYO está planejado para um lançamento futuro. Controles em nível de ferramenta estão sendo implementados para outros tipos de servidores MCP suportados registrados no Agente 365. Para obter mais informações, consulte Gerenciar ferramentas individuais em um servidor MCP.
Instantâneo das ferramentas Um administrador pode exibir as ferramentas declaradas por cada servidor MCP.
Aplicação de tempo de execução O Gateway de Ferramentas Agent 365 impõe bloqueio de servidor para invocações roteadas pelo gateway a partir de clientes suportados. Não presuma que o bloqueio impeça o acesso direto ao endpoint do servidor subjacente.
Delete Um administrador pode excluir um servidor MCP BYO registrado que não é mais necessário. Para obter mais informações, consulte Excluir um servidor MCP BYO.

Usar um servidor MCP aprovado

Depois que um servidor MCP for aprovado e o Microsoft Entra conceder consentimento, você poderá usá-lo em superfícies de construção de agente compatíveis. As seguintes superfícies cliente dão suporte a servidores MCP BYO aprovados durante a visualização:

Client Status
Copilot Studio Supported
Visual Studio Code Supported
Código Claude Supported
CLI do GitHub Copilot Supported

No Copilot Studio, siga estas etapas para invocar o servidor MCP BYO aprovado:

  1. Acesse o Copilot Studio em seu ambiente.

  2. Crie um novo agente personalizado (ou abra um existente).

  3. Vá para a seção Ferramentas e selecione Servidor MCP.

  4. Selecione o servidor MCP no registro.

  5. Teste o agente inserindo um prompt que invoca o servidor MCP.

Note

Na primeira vez que você invocar o servidor, talvez seja solicitado que você conclua uma configuração de conexão feita uma única vez. Siga a URL fornecida para criar a conexão necessária, como inserir sua chave de API para um servidor baseado em APIKey. Quando terminar, retorne ao seu agente e repita o prompt. Após uma invocação bem-sucedida, o servidor MCP retorna a saída da ferramenta.

Saiba como invocar servidores BYO MCP aprovados do Claude Code, do VS Code e da CLI do GitHub Copilot na seção Configurar servidores MCP do Work IQ para agentes de codificação da visão geral do MCP do Work IQ.

Note

O Work IQ MCP fornece controles de política no nível do locatário que ajudam os administradores a gerenciar como os agentes acessam e interagem com os recursos do Microsoft 365. Para aprender a configurar esses controles, veja Governança de Políticas para o Work IQ MCP.

Monitorar e observar a atividade do servidor MCP

Use o Microsoft Defender advanced hunting para rastrear e analisar invocações de servidores MCP roteadas pelo Gateway de Ferramentas do Agente 365. Esse processo mostra quais agentes invocam quais servidores MCP, quando as invocações ocorrem e outros metadados que podem ajudá-lo a detectar o uso incomum ou não autorizado. Essa telemetria não oferece cobertura completa de monitoramento para cada plugin ou componente em um pacote de plugins.

A consulta KQL a seguir fornece um exemplo para a busca avançada do Defender:

CloudAppEvents
| where ActionType in ( "ExecuteToolByGateway")
| where RawEventData contains "tool name"

Essa consulta retorna detalhes, incluindo nome do agente, nome do servidor MCP e metadados de invocação.

Excluir um servidor BYO MCP

Você pode excluir um servidor MCP BYO registrado do Centro de administração do Microsoft 365 quando ele não for mais necessário. Ao excluir o registro, o servidor é removido do registro, e os agentes não podem mais invocá-lo por meio do Gateway de Ferramentas do Agent 365. Não trate a exclusão do registro como desligar o serviço remoto, revogar suas credenciais ou impedir o acesso direto ao seu endpoint.

Para excluir um servidor MCP BYO, siga estas etapas:

  1. Entre no centro de administração do Microsoft 365.
  2. Selecione Agentes>Ferramentas e, em seguida, selecione a guia Registro.
  3. Selecione o servidor BYO MCP que você deseja excluir para abrir seu painel de visão geral.
  4. Selecione Excluir.
  5. Confirme a exclusão selecionando Excluir.