Referência de comando da CLI develop-mcp do Agent 365

Gerenciar servidores MCP em ambientes do Dataverse. O develop-mcp comando oferece opções para publicar, despublicar, registrar e conceder permissões de agente para servidores MCP para uso em ambientes Dataverse.

Note

Os develop-mcp approvecomandos , develop-mcp block, e develop-mcp package-mcp-server são removidos da CLI do Agente 365. Administradores de tenant agora realizam aprovação e bloqueio de servidores no centro de administração Microsoft — solicitações pendentes são analisadas na página Solicitados Agentes. A CLI não produz mais pacotes de servidores MCP para envio ao Centro de Administração; Administradores a bordo e gerenciam os servidores diretamente no centro de administração.

Função mínima necessária: varia de acordo com o subcomando

Syntax

a365 develop-mcp [command] [options]

Opções

Option Description
-v, --verbose Habilitar o registro em log detalhado
-?, -h, --help Mostrar informações de ajuda e uso

develop-mcp evaluate

Avalie seu servidor MCP com base nas melhores práticas científicas para avaliar a prontidão para produção. Essa ferramenta produz um relatório de avaliação abrangente com pontuações, explicações e ações específicas. O comando descobre as ferramentas que um servidor MCP expõe, executa um conjunto de verificações semânticas determinísticas e pontuadas por IA em seus esquemas, e produz um relatório HTML que avalia a qualidade do esquema e lista as ações priorizadas para melhoria.

a365 develop-mcp evaluate --server-url <server-url> [--auth-token <auth-token>] [options]

evaluate opções

Option Description
-u, --server-url <server-url> Required. A URL do endpoint HTTP streamável do servidor MCP (normalmente termina em /mcp).
--auth-token <auth-token> Optional. Só é necessário quando o servidor MCP exige autenticação. Token de portador para o servidor. Prefira a A365_MCP_AUTH_TOKEN variável de ambiente; um token passado na linha de comando fica visível para listagens de processos e histórico de shell.
-o, --output-dir <output-dir> Diretório para a lista de verificação e arquivos de relatórios. O diretório atual é padrão (.).
--eval-engine <eval-engine> Qual agente local de codificação pontua as verificações semânticas: auto (padrão; tente GitHub Copilot, depois Claude Code), github-copilot, claude-code ou none (pule a pontuação da IA e espere uma checklist pré-pontuada).
-v, --verbose Permite o registro detalhado.
-?, -h, --help Mostrar informações de ajuda e uso.

evaluate Exemplos

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

Force um mecanismo de pontuação específico:

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

Aprenda a avaliar servidores MCP

evaluate variáveis de ambiente

Use as seguintes variáveis de ambiente para fornecer autenticação e, opcionalmente, controlar qual modelo cada motor de pontuação local utiliza.

Environment variable Purpose
A365_MCP_AUTH_TOKEN Token portador para o servidor MCP, usado quando --auth-token não é passado. Preferido em vez da flag porque mantém o token fora das listagens de processos e do histórico da shell.
A365_EVAL_COPILOT_MODEL Substitua o modelo GitHub Copilot. Requer um ID exato do modelo, por claude-haiku-4.5exemplo.
A365_EVAL_CLAUDE_MODEL Anule o modelo do Código Claude. Aceita um alias de modelo (por exemplo haiku) ou um ID completo do modelo.

develop-mcp grant-agents-access

Conceda permissão de um servidor MCP que traz seu próprio (BYO) para identificar agentes que não estejam com isso.

a365 develop-mcp grant-agents-access --mcp-server-name <NAME> --agent-blueprint-id <GUID> [options]

Permissões mínimas exigidas: Administrador Global (ou outra função com direitos para criar concessões de permissões OAuth2 para todo o inquilino)

Use esse comando para encontrar e corrigir identidades de agentes que não conseguem chamar um servidor MCP de bring your-own (BYO) porque estão sem Tools.ListInvoke.All permissão para isso. O comando lista as instâncias do agente do blueprint especificado que estão sem permissão, e depois permite que você escolha para quais conceder essa permissão.

O nome do servidor MCP resolve para um aplicativo Microsoft Entra, onde - BYO é anexado ao nome. Por exemplo, ext_Learn1 resolve em ext_Learn1 - BYO. A concessão em si é uma concessão de permissão OAuth2 delegada para todo o inquilino (AllPrincipals) sobre o principal de serviço dessa aplicação, então se aplica a todas as instâncias atuais e futuras do agente do blueprint, não apenas aquelas listadas em tempo de execução.

Geralmente, você não conhece o GUID do blueprint de antemão. Passar --agent-blueprint-id sem um valor, ou um inválido, imprime os nomes e IDs dos blueprints de primeira mão da Microsoft para que você possa encontrá-los. Passar --help imprime a mesma lista.

Após o comando reportar que as instâncias do agente estão sem permissão, Enter all para concedê-la a cada instância mostrada, uma lista separada por vírgulas dos números mostrados (por exemplo, 1,3) para conceder a instâncias específicas, ou pressione Enter para pular a concessão. Passe --yes para conceder a cada instância listada sem necessidade de solicitação, por exemplo, em um script.

Se mais de um aplicativo Entra compartilhar o mesmo <name> - BYO nome de exibição, o comando lista todas as correspondências e pergunta qual usar em vez de adivinhar.

grant-agents-access opções

Option Description
--agent-blueprint-id <agent-blueprint-id> ID do blueprint do agente (GUID) para as instâncias do agente verificarem. Se você omitir essa opção ou fornecer um valor inválido, o comando imprime os nomes dos blueprints e IDs de primeira parte.
-s, --mcp-server-name <mcp-server-name> Required. Nome do servidor MCP. A aplicação Entra resolve como <name> - BYO.
--tenant-id <tenant-id> ID do locatário do Azure AD. O padrão é o contexto atual da CLI do Azure.
-y, --yes Conceda a permissão faltante a cada instância de agente listada sem necessidade de solicitação.
--device-code Use autenticação por código de dispositivo em vez do fluxo interativo do navegador (o broker WAM no Windows). Use quando o WAM não pode mostrar um diálogo de login, como um terminal embarcado ou remoto. Abre https://microsoft.com/devicelogin no seu navegador.
--dry-run Informe quais instâncias de agentes estão sem permissão sem concedê-la.
-v, --verbose Habilitar o registro em log detalhado
-?, -h, --help Mostrar informações de ajuda e uso

develop-mcp list-environments

Listar todos os ambientes do Dataverse disponíveis para gerenciamento de servidor MCP.

a365 develop-mcp list-environments [options]

Esse comando exibe todos os ambientes do Dataverse em que você pode gerenciar servidores MCP.

list-environments opções

Option Description
--dry-run Mostrar o que seria feito sem executar
-v, --verbose Habilitar o registro em log detalhado
-?, -h, --help Mostrar informações de ajuda e uso

develop-mcp list-servers

Listar servidores MCP em um ambiente específico do Dataverse.

a365 develop-mcp list-servers [options]

Esse comando lista todos os servidores MCP que estão atualmente implantados no ambiente Dataverse especificado.

list-servers opções

Option Description
-e, --environment-id <environment-id> ID de ambiente do Dataverse
--dry-run Mostrar o que seria feito sem executar
-v, --verbose Habilitar o registro em log detalhado
-?, -h, --help Mostrar informações de ajuda e uso

develop-mcp publish

Publique um servidor MCP em um ambiente do Dataverse.

a365 develop-mcp publish [options]

Use este comando para publicar um servidor MCP no ambiente do Dataverse especificado.

Important

Publicar um servidor MCP não aprova isso. Publicar só envia o servidor para seu tenant e cria uma solicitação de aprovação pendente. Antes que qualquer agente possa usar o servidor, um administrador de tenant deve aprová-lo na página de Ferramentas Solicitadas no Centro de administração do Microsoft 365. Até que o administrador aprove a solicitação, o servidor permanece indisponível para os agentes. Quando o comando tem sucesso, a CLI imprime um lembrete para pedir ao administrador do tenant que aprove o servidor.

Quando você publica, a CLI cria um registro <server-name>-PublicClients Microsoft Entra app no seu locatário. Este aplicativo possui as permissões OAuth que os hosts clientes (como Visual Studio Code e o Microsoft Copilot CLI) usam para chamar o servidor MCP publicado. Como o comando cria um registro de app, a conta que executa a CLI deve ter a permissão Application.ReadWrite.All Microsoft Graph. Funcionar publish sem ela falha.

Note

Fornecer --publisher-name servidores MCP personalizados (criados pelos usuários). O valor é escrito nos metadados do desenvolvedor do pacote publicado e é exigido para esses servidores. É ignorado para servidores de primeira mão Microsoft (por exemplo, msdyn_DataverseMCPServer), que sempre publicam como "Microsoft". Quando você omite, o CLI solicita de forma interativa; passe --yes para publicar sem prompts em contextos CI ou scriptados.

publish opções

Option Description
-e, --environment-id <environment-id> ID de ambiente do Dataverse
-s, --server-name <server-name> Nome do servidor MCP a ser publicado
-a, --alias <alias> Alias para o servidor MCP
-d, --display-name <display-name> Nome de exibição para o servidor MCP
-p, --publisher-name <publisher-name> Nome do Publisher escrito nos metadados do pacote publicado. Exigido para servidores MCP personalizados (criados pelo usuário); ignorado por servidores de primeira mão da Microsoft. Incentivado de forma interativa quando omitido.
-y, --yes Pule o interativo "Prosseguir com a publicação? (y/N)" confirmation. Uso em contextos de CI ou scriptados.
--dry-run Mostrar o que seria feito sem executar
-v, --verbose Habilitar o registro em log detalhado
-?, -h, --help Mostrar informações de ajuda e uso

Saiba como administradores de inquilinos aprovam servidores MCP

develop-mcp unpublish

Cancele a publicação de um servidor MCP de um ambiente do Dataverse.

a365 develop-mcp unpublish [options]

Use este comando para remover um servidor MCP do ambiente do Dataverse especificado.

unpublish opções

Option Description
-e, --environment-id <environment-id> ID de ambiente do Dataverse
-s, --server-name <server-name> Nome do servidor MCP para cancelar a publicação
--dry-run Mostrar o que seria feito sem executar
-?, -h, --help Mostrar informações de ajuda e uso

develop-mcp register-external-mcp-server

Registre um servidor MCP externo com Entra, OAuth externo, chave API ou sem autenticação.

a365 develop-mcp register-external-mcp-server [options]

Use este comando para registrar um servidor MCP hospedado externamente (de terceiros) junto ao seu locatário. O comando cria os registros do app Microsoft Entra que a plataforma precisa, chama a plataforma Agent 365 para adicionar o servidor MCP e configura URIs de redirecionamento e permissões de API nos novos registros de aplicativos.

O nome do servidor deve começar com o ext_ prefixo e ter no máximo 20 caracteres, por ext_MyServerexemplo. Os nomes das ferramentas devem corresponder exatamente aos nomes expostos pelo servidor MCP remoto. Nomes incompatíveis fazem com que as invocações de ferramentas falham em tempo de execução.

Você pode fornecer parâmetros de três maneiras:

  • Passe como opções de linha de comando.
  • Forneça um arquivo JSON com --input-file. Opções de linha de comando sobrescrevem valores do arquivo. Veja register-external-mcp-server-sample.json nos templates de CLI a estrutura do arquivo.
  • Omita qualquer valor necessário para ser solicitado interativamente.

Depois que o registro for bem-sucedido, peça ao administrador do inquilino para aprovar o novo servidor MCP antes que os agentes possam usá-lo. Se você se registrou com ExternalOAuth, também adicione o URI de redirecionamento exibido ao seu aplicativo IDP externo.

Important

Se o registro falhar após a criação dos registros do app Microsoft Entra, os aplicativos não são automaticamente revertidos. Delete-os manualmente no portal do Azure antes de tentar novamente.

register-external-mcp-server opções

Algumas opções são necessárias apenas para tipos específicos de autenticação, conforme descrito na coluna de descrição.

Option Description
-s, --server-name <server-name> Nome do servidor MCP. Deve começar com ext_ e ter no máximo 20 caracteres, por exemplo ext_MyServer
-u, --server-url <server-url> URL remota do servidor MCP. Deve ser uma URL HTTP ou HTTPS válida
-a, --auth-type <auth-type> Tipo de autenticação: EntraOAuth, ExternalOAuth, APIKey, ou NoAuth
--publisher <publisher> Nome do Publisher (usado nos metadados do pacote)
--description <description> Descrição do servidor (usada nos metadados dos pacotes)
--tools <tools> Lista separada por vírgulas de nomes de ferramentas exposta por este servidor, por exemplo tool1,tool2,tool3
-f, --input-file <input-file> Caminho para um arquivo JSON com os parâmetros de registro
--remote-scopes <remote-scopes> Escopos para o servidor MCP remoto, por api://{appId-guid}/{scopeName}exemplo. Usada com EntraOAuth
-t, --tenant-id <tenant-id> Entra o ID do inquilino para o registro do aplicativo. Default para o inquilino atual az login
--service-tree-id <service-tree-id> ID ServiceTree para o registro do aplicativo Entra. Exigido em tenants corporativos da Microsoft
-l, --secret-lifetime-months <months> Vida útil em meses (1-24) para os segredos gerados pelos clientes nos aplicativos Entra criados. O prazo padrão é de 24 meses (2 anos). Defina um valor menor que o appManagementPolicies limite do seu inquilino se a política do inquilino impor um máximo mais curto
--idp-authorization-url <url> URL de autorização OAuth externa. Necessário quando --auth-type é ExternalOAuth
--idp-token-url <url> URL externa do token OAuth. Necessário quando --auth-type é ExternalOAuth
--idp-scopes <scopes> Escopos externos OAuth. Necessário quando --auth-type é ExternalOAuth
--idp-client-id <client-id> ID de cliente OAuth externo. Necessário quando --auth-type é ExternalOAuth
--idp-client-secret <client-secret> Cliente secreto externo OAuth. Necessário quando --auth-type é ExternalOAuth
--api-key-location <location> Localização da chave API: Header ou Query. Necessário quando --auth-type é APIKey
--api-key-name <name> Parâmetro ou nome do cabeçalho da chave API, por exemplo X-API-Key ou token. Necessário quando --auth-type é APIKey
--dry-run Mostrar o que seria feito sem executar
-v, --verbose Habilitar o registro em log detalhado
-?, -h, --help Mostrar informações de ajuda e uso
  • Última atualização em