Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Referência de comando CLI
Gerir servidores MCP em ambientes Dataverse. O develop-mcp comando oferece opções para publicar, despublicar, registar e conceder permissões de agente para servidores MCP para utilização 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. Os administradores de inquilinos agora realizam a aprovação e o bloqueio do servidor no centro de administração Microsoft — os pedidos pendentes são analisados na página Requested Agents. A CLI já não produz pacotes de servidores MCP para submissão ao Centro de Administração; Administradores integrados e gerem os servidores diretamente no centro de administração.
Papel mínimo exigido: Varia consoante o subcomando
Syntax
a365 develop-mcp [command] [options]
Opções
| Option | Description |
|---|---|
-v, --verbose |
Ativar registo detalhado |
-?, -h, --help |
Mostrar ajuda e informação de utilização |
develop-mcp evaluate
Avalie o seu servidor MCP com as melhores práticas científicas para avaliar a prontidão para produção. Esta 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 contra os seus esquemas, e produz um relatório HTML que avalia a qualidade do esquema e lista as ações prioritárias 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 streamable 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. Preferência a A365_MCP_AUTH_TOKEN variável de ambiente; um token passado na linha de comandos é 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 os ficheiros de relatório. Por defeito, o diretório atual (.). |
--eval-engine <eval-engine> |
Qual agente de codificação local pontua as verificações semânticas: auto (por defeito; experimenta GitHub Copilot, depois Claude Code), github-copilot, claude-code ou none (salta a pontuação da IA e espera uma lista de verificação pré-pontuada). |
-v, --verbose |
Ativar o registo de verboses. |
-?, -h, --help |
Mostrar informações de ajuda e utilização. |
evaluate exemplos
Avalie um servidor local com seleção automática do motor:
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, marque-a com o 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
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 é aprovado. Preferido em relação à flag porque mantém o token fora das listagens de processos e do histórico da shell. |
A365_EVAL_COPILOT_MODEL |
Anular o modelo GitHub Copilot. Requer um ID exato do modelo, por claude-haiku-4.5exemplo . |
A365_EVAL_CLAUDE_MODEL |
Anular o modelo Claude Code. Aceita um alias de modelo (por exemplo haiku) ou um ID de modelo completo. |
develop-mcp grant-agents-access
Conceda a permissão de um servidor MCP que traz o seu próprio (BYO) a identidades de agentes que não a tenham.
a365 develop-mcp grant-agents-access --mcp-server-name <NAME> --agent-blueprint-id <GUID> [options]
Permissões mínimas obrigatórias: Administrador Global (ou outro cargo com direitos para criar concessões de permissões OAuth2 para todo o inquilino)
Usa este comando para encontrar e corrigir identidades de agentes que não conseguem chamar um servidor MCP bring-your-own (BYO) porque lhes falta a Tools.ListInvoke.All permissão para isso. O comando lista as instâncias agentes do blueprint especificado que não têm a permissão, e depois permite-te escolher a quais conceder essa permissão.
O nome do servidor MCP resolve para uma aplicação Microsoft Entra, onde - BYO é acrescentado ao nome. Por exemplo, ext_Learn1 resolve em ext_Learn1 - BYO. A concessão em si é uma concessão de autorização OAuth2 delegada a nível de inquilino (AllPrincipals) sobre o principal de serviço dessa aplicação, pelo que se aplica a todas as instâncias atuais e futuras do agente do blueprint, não apenas às listadas em tempo de execução.
Geralmente, não conheces 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 possa encontrá-lo. Passar --help imprime a mesma lista.
Depois de o comando reportar que as instâncias do agente não têm a 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 pressionar Enter para evitar a concessão. Passe --yes para conceder a todas as instâncias listadas sem necessidade de solicitação, por exemplo num script.
Se mais do que uma aplicação Entra partilhar o mesmo <name> - BYO nome de visualizaçã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 omitir esta opção ou fornecer um valor inválido, o comando imprime os nomes e IDs dos blueprints de primeira mão. |
-s, --mcp-server-name <mcp-server-name> |
Required. Nome do servidor MCP. A aplicação Entra resolve-se como <name> - BYO. |
--tenant-id <tenant-id> |
ID do inquilino do Azure AD. Por defeito, o contexto atual da CLI do Azure. |
-y, --yes |
Conceda a permissão em falta a cada instância de agente listado 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 entrada, como um terminal embutido ou remoto. Abre-se https://microsoft.com/devicelogin no teu navegador. |
--dry-run |
Reporta quais as instâncias do agente que não têm a permissão sem a conceder. |
-v, --verbose |
Ativar registo detalhado |
-?, -h, --help |
Mostrar ajuda e informação de utilização |
develop-mcp list-environments
Liste todos os ambientes Dataverse disponíveis para gestão de servidores MCP.
a365 develop-mcp list-environments [options]
Este comando mostra todos os ambientes Dataverse onde pode gerir servidores MCP.
list-environments Opções
| Option | Description |
|---|---|
--dry-run |
Mostra o que seria feito sem executar |
-v, --verbose |
Ativar registo detalhado |
-?, -h, --help |
Mostrar ajuda e informação de utilização |
develop-mcp list-servers
Liste servidores MCP num ambiente Dataverse específico.
a365 develop-mcp list-servers [options]
Este comando lista todos os servidores MCP que estão atualmente implementados no ambiente Dataverse especificado.
list-servers Opções
| Option | Description |
|---|---|
-e, --environment-id <environment-id> |
ID do ambiente Dataverse |
--dry-run |
Mostra o que seria feito sem executar |
-v, --verbose |
Ativar registo detalhado |
-?, -h, --help |
Mostrar ajuda e informação de utilização |
develop-mcp publish
Publique um servidor MCP num ambiente Dataverse.
a365 develop-mcp publish [options]
Use este comando para publicar um servidor MCP no ambiente Dataverse especificado.
Important
Publicar um servidor MCP não o aprova. Publicar só submete o servidor ao seu inquilino e cria um pedido de aprovação pendente. Antes de qualquer agente poder 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 o pedido, o servidor permanece indisponível para os agentes. Quando o comando tem sucesso, a CLI imprime um lembrete para pedir ao administrador do inquilino que aprove o servidor.
Quando publicas, o CLI cria um registo <server-name>-PublicClients Microsoft Entra app no teu inquilino. Esta aplicação detém as permissões OAuth que os hosts clientes (como o Visual Studio Code e a CLI do Microsoft Copilot) usam para chamar o servidor MCP publicado. Como o comando cria um registo de app, a conta que executa a CLI deve ter a permissão Application.ReadWrite.All Microsoft Graph. Correr publish sem ela falha.
Note
Disponibilizar --publisher-name servidores MCP personalizados (criados pelos utilizadores). O valor é escrito nos metadados do desenvolvedor do pacote publicado e é obrigatório para estes servidores. É ignorado para servidores de primeira parte detidos por Microsoft (por exemplo, msdyn_DataverseMCPServer), que publicam sempre como "Microsoft". Quando o omites, o CLI apresenta prompts interativos; passe --yes para publicar sem prompts em contextos CI ou scriptados.
publish Opções
| Option | Description |
|---|---|
-e, --environment-id <environment-id> |
ID do ambiente Dataverse |
-s, --server-name <server-name> |
Nome do servidor MCP a publicar |
-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. Obrigatório para servidores MCP personalizados (criados pelo utilizador); ignorado por servidores próprios pertencentes à Microsoft. Incentivado interativamente quando omitido. |
-y, --yes |
Evite o interativo "Prosseguir com a publicação? (y/N)" confirmation. Uso em contextos de CI ou scriptados. |
--dry-run |
Mostra o que seria feito sem executar |
-v, --verbose |
Ativar registo detalhado |
-?, -h, --help |
Mostrar ajuda e informação de utilização |
develop-mcp unpublish
Despublicar um servidor MCP de um ambiente Dataverse.
a365 develop-mcp unpublish [options]
Use este comando para remover um servidor MCP do ambiente Dataverse especificado.
unpublish Opções
| Option | Description |
|---|---|
-e, --environment-id <environment-id> |
ID do ambiente Dataverse |
-s, --server-name <server-name> |
Nome do servidor MCP para despublicar |
--dry-run |
Mostra o que seria feito sem executar |
-?, -h, --help |
Mostrar ajuda e informação de utilização |
develop-mcp register-external-mcp-server
Registe 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 registar um servidor MCP alojado externamente (de terceiros) junto do seu inquilino. O comando cria os registos da aplicação Microsoft Entra de que a plataforma precisa, chama a plataforma Agent 365 para adicionar o servidor MCP e configura URIs de redirecionamento e permissões da API nos novos registos de aplicações.
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 falhem em tempo de execução.
Pode fornecer parâmetros de três formas:
- Passa-os como opções de linha de comandos.
- Forneça um ficheiro JSON com
--input-file. As opções da linha de comandos sobrepõem valores do ficheiro. Vejaregister-external-mcp-server-sample.jsonnos templates de CLI para a estrutura do ficheiro. - Omita qualquer valor necessário a ser solicitado de forma interativa.
Depois de o registo ser bem-sucedido, peça ao administrador do seu inquilino para aprovar o novo servidor MCP antes que os agentes possam usá-lo. Se se registou com ExternalOAuth, adicione também o URI de redirecionamento apresentado à sua aplicação externa IDP.
Important
Se o registo falhar após a criação dos registos da aplicação Microsoft Entra, as aplicações não são automaticamente revertidas. Apague-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 remoto do servidor MCP. Deve ser um URL HTTP ou HTTPS válido |
-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 ficheiro JSON com os parâmetros de registo |
--remote-scopes <remote-scopes> |
Escopos para o servidor MCP remoto, por api://{appId-guid}/{scopeName}exemplo. Utilizado com EntraOAuth |
-t, --tenant-id <tenant-id> |
Entra o ID do inquilino para o registo da aplicação. Passa por defeito ao inquilino atual az login |
--service-tree-id <service-tree-id> |
Identificador ServiceTree para o registo da aplicação Entra. Obrigatório nos tenants corporativos da Microsoft |
-l, --secret-lifetime-months <months> |
Vida útil em meses (1-24) para os segredos gerados pelos clientes nas aplicações Entra criadas. O prazo padrão é de 24 meses (2 anos). Defina um valor inferior ao appManagementPolicies limite no seu inquilino se a sua apólice de 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 externo do token OAuth. Necessário quando --auth-type é ExternalOAuth |
--idp-scopes <scopes> |
Oscilações OAuth externas. 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> |
Segredo externo do cliente 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 de chave API ou nome do cabeçalho, por exemplo X-API-Key ou token. Necessário quando --auth-type é APIKey |
--dry-run |
Mostra o que seria feito sem executar |
-v, --verbose |
Ativar registo detalhado |
-?, -h, --help |
Mostrar ajuda e informação de utilização |