Solucionar problemas do servidor MCP do Azure DevOps remoto

Serviços do Azure DevOps

Este artigo ajuda você a diagnosticar e resolver problemas comuns com o servidor MCP remoto do Azure DevOps. Para problemas de servidor MCP local, consulte o guia de solução de problemas do SERVIDOR MCP local.

Falhas na conexão

Servidor não encontrado ou erros de URL

Sintoma: Seu assistente de IA não pode se conectar ao servidor MCP remoto ou você vê erros relacionados à URL.

Resolução:

1. Verifique o formato de URL do servidor em seu mcp.json:

   {
     "servers": {
       "ado-remote-mcp": {
         "url": "https://mcp.dev.azure.com/{organization}",
         "type": "http"
       }
     }
   }
   

2. Confirme o seguinte:

   • Use https://mcp.dev.azure.com/{organization} – substitua {organization} pelo nome real da organização.
   • Use apenas o nome da organização (por exemplo, contoso), não a URL de Azure DevOps completa.
   • O type deve ser "http", não "stdio".

3. Se você omitir o nome da organização da URL (https://mcp.dev.azure.com/), deverá fornecer o nome da organização como contexto em cada chamada de ferramenta.

Blocos de rede ou firewall

Sintoma: A conexão atinge o tempo limite ou é recusada, mas a URL está correta.

Resolução:

• Verifique se a rede permite o tráfego HTTPS de saída para mcp.dev.azure.com.
• Se você estiver atrás de um proxy corporativo ou firewall, verifique se mcp.dev.azure.com não está bloqueado. Entre em contato com seu administrador de rede para adicionar este ponto de extremidade à lista de permissões.
• As configurações de VPN podem interferir na conectividade. Tente se conectar sem VPN para isolar o problema.

Visualizar disponibilidade

Sintoma: Você recebe um erro indicando que o serviço não está disponível.

Resolução:

O servidor MCP remoto está em versão prévia pública e está sendo implantado gradualmente. Se você não conseguir se conectar:

• Verifique se sua organização está conectada a Microsoft Entra ID.
• Volte mais tarde, pois a prévia continua a ser expandida.
• Confirme com o administrador da organização que nenhuma política bloqueia recursos de visualização.

Erros de autenticação

O servidor MCP remoto usa Microsoft Entra ID (OAuth) para autenticação. Não há suporte para PATs (tokens de acesso pessoal) para o servidor remoto.

A tela de login falha ou não aparece

Sintoma: O prompt de entrada do OAuth não aparece ou a autenticação falha antes que você possa entrar.

Resolução:

1. Verifique se sua conta está conectada ao Microsoft Entra ID. O servidor MCP remoto requer uma identidade com suporte Microsoft Entra.
2. Verifique se o seu navegador pode ser aberto para o fluxo do OAuth. Se você usar o VS Code em um ambiente remoto ou sem cabeça, o redirecionamento do OAuth poderá não funcionar corretamente.
3. Limpar credenciais armazenadas em cache:
   • No VS Code, abra a Paleta de Comandos (Ctrl+Shift+P) e execute Contas: Sair. Em seguida, tente a conexão novamente.
   • Se o problema persistir, recarregue a janela do VS Code (Desenvolvedor: Recarregar Janela).

Falha de autorização após o login

Sintoma: Você entra com êxito, mas recebe um erro de autorização ao tentar acessar sua organização ou projeto.

Resolução:

• Confirme se você tem o nível access correto na organização Azure DevOps.
• Verifique se você é membro do projeto que está tentando acessar.
• Verifique se suas permissões de Azure DevOps incluem acesso aos recursos que você está consultando (por exemplo, itens de trabalho, repositórios ou pipelines).

Políticas de acesso condicional bloqueiam o acesso

Symptom: uma política de Acesso condicional do Microsoft Entra bloqueia sua entrada.

Resolução:

As políticas de Acesso Condicional se aplicam ao servidor MCP remoto da mesma forma que se aplicam a Azure DevOps. Se o locatário impor políticas como restrições baseadas em local ou dispositivo:

• Verifique se você está fazendo login a partir de um dispositivo e de um local de rede em conformidade.
• Se o locatário usar políticas de Acesso Condicional baseadas em localização, o administrador do Microsoft Entra ID poderá precisar adicionar os endereços IP dos servidores MCP remotos à lista de permissões: 20.125.155.22 e 40.74.28.81.
• Contate o administrador do Microsoft Entra ID para obter requisitos de política específicos.

O acesso de convidado (B2B) falha

Symptom: Um usuário convidado no locatário Microsoft Entra não pode acessar o SERVIDOR MCP remoto.

Resolução:

Para que o acesso de convidado funcione, o usuário deve ser:

1. Adicionado como um usuário convidado ao locatário do Microsoft Entra.
2. Adicionado à organização Azure DevOps com as permissões apropriadas.
3. Acesso concedido aos projetos e recursos específicos de que precisam.
4. Usando a URL específica da organização (https://mcp.dev.azure.com/{organization}). Os usuários convidados não podem usar a URL raiz (https://mcp.dev.azure.com/) – eles devem incluir o nome da organização na URL.

Se alguma dessas etapas estiver ausente, o acesso falhará. Trate esse problema da mesma forma que um problema de acesso de convidado Azure DevOps padrão.

Códigos de erro AADSTS

Sintoma: Você vê um código de erro começando com AADSTS (por exemplo, AADSTS50076, ). AADSTS700016

Resolução:

AADSTS são erros de autenticação do Microsoft Entra ID, não problemas específicos do MCP. Os códigos comuns incluem:

Para obter uma lista completa de códigos de erro, consulte Microsoft Entra códigos de erro de autenticação e autorização.

Problemas de configuração do servidor

Configuração incorreta mcp.json

Sintoma: O servidor MCP remoto se conecta, mas as ferramentas não são carregadas ou você obtém um comportamento inesperado.

Resolução:

Verifique se você mcp.json usa o formato correto para o servidor remoto:

• O servidor remoto usa "type": "http" e "url".
• O servidor local usa "type": "stdio", "command"e "args".

Não misture formatos de configuração locais e remotos. Não execute os dois servidores ao mesmo tempo — escolha um:

• Servidor remoto — Use com o Visual Studio Code e o Visual Studio. Nenhuma instalação local é necessária.
• Local server — Use para clientes não Microsoft (Claude Desktop, Claude Code, Cursor, Codex) que não dão suporte à autenticação Microsoft Entra.

Conjunto de ferramentas ou filtragem de ferramentas não funciona

Sintoma: Você configura X-MCP-Toolsets ou X-MCP-Tools cabeçalhos, mas a lista de ferramentas não corresponde às expectativas.

Resolução:

• Não combine os cabeçalhos X-MCP-Toolsets e X-MCP-Tools — eles são mutuamente exclusivos.
• Verifique se os nomes do conjunto de ferramentas estão corretos: repos, , wit, wiki, pipelines, , work. testplan
• Ao usar X-MCP-Tools, especifique os nomes exatos de ferramentas separados por vírgulas.
• Verifique se há erros de digitação em nomes de cabeçalho – os cabeçalhos diferenciam maiúsculas de minúsculas.

{
  "servers": {
    "ado-remote-mcp": {
      "url": "https://mcp.dev.azure.com/{organization}",
      "type": "http",
      "headers": {
        "X-MCP-Toolsets": "repos,wit"
      }
    }
  }
}

Para obter a lista completa de ferramentas e ferramentas disponíveis, consulte as ferramentas disponíveis.

Modo de somente leitura não restringe gravações

Sintoma: Você configura X-MCP-Readonly, mas as operações de escrita ainda estão disponíveis.

Resolução:

Verifique se o valor do cabeçalho é a cadeia de caracteres "true":

"headers": {
  "X-MCP-Readonly": "true"
}

Erros de resolução de ferramentas

Ferramentas que não aparecem no assistente de IA

Symptom: Depois de conectar o servidor MCP remoto, nenhuma ferramenta de Azure DevOps será exibida no assistente de IA.

Resolução:

1. Confirme se o status do servidor é mostrado como conectado em seu IDE.
   • No VS Code, verifique o status do servidor MCP no painel Saída (View>Output> selecione GitHub Copilot ou MCP na lista suspensa).
2. Recarregue a janela do VS Code (Ctrl+Shift+P>Developer: Recarregar Janela).
3. Verifique se você está no modo agent em GitHub Copilot — as ferramentas MCP aparecem apenas no modo de agente, não no modo de chat.
4. Verifique se você não excede o limite de 128 ferramentas. Se você tiver vários servidores MCP configurados, a contagem combinada de ferramentas poderá exceder esse limite.

Erros de parâmetro obrigatório ausente

Sintoma: As chamadas de ferramenta falham com erros de "parâmetro necessário ausente", normalmente para o nome do projeto.

Resolução:

Esse erro é o erro mais comumente relatado e é o comportamento esperado. Muitas ferramentas exigem um nome de projeto ou outro contexto:

• Inclua o nome do projeto no prompt: "Listar itens de trabalho no projeto Contoso ".
• Se você omitiu a organização de sua URL, inclua a organização em seu prompt também.
• Algumas ferramentas exigem parâmetros específicos. Verifique a documentação de ferramentas disponíveis para obter os parâmetros necessários.

A chamada da ferramenta falha devido a um erro no servidor

Sintoma: Uma chamada de ferramenta retorna um erro de servidor depois de ser invocada corretamente.

Resolução:

• Verifique se o recurso que você está consultando existe (por exemplo, a ID do item de trabalho, o nome do repositório ou a ID do pipeline está correta).
• Confirme se você tem permissões para acessar o recurso.
• Se o erro persistir, crie um problema usando o modelo de problema do Servidor MCP Remoto.

Problemas de integração do Copilot

O assistente de IA não usa ferramentas MCP

Symptom: GitHub Copilot responde à sua pergunta, mas não usa Azure DevOps ferramentas MCP para recuperar dados.

Resolução:

1. Verifique se você está usando agent mode em GitHub Copilot. As ferramentas MCP não estão disponíveis no modo de chat padrão.
2. Seja explícito em seu prompt sobre quais dados do Azure DevOps você precisa. Por exemplo, em vez de "Qual é o meu status de sprint?", tente "Usar Azure DevOps para obter meus itens de trabalho de sprint atuais".
3. Verifique se o servidor MCP é mostrado como conectado a um indicador de status verde.

Dados obsoletos ou em cache retornados

Symptom: O assistente de IA retorna dados de Azure DevOps desatualizados.

Resolução:

Adicione "Não usar dados buscados anteriormente" ao prompt para forçar uma nova consulta. Os assistentes de IA podem armazenar em cache os resultados da ferramenta em uma sessão de conversa.

O agente falha antes da chamada da ferramenta

Sintoma: O assistente de IA falha ou apresenta erro antes de invocar qualquer ferramenta MCP.

Resolução:

Esse problema está fora do limite do MCP Azure DevOps. A falha ocorre na camada de orquestração do assistente de IA:

• Para problemas com o GitHub Copilot, consulte a documentação do GitHub Copilot.
• Reinicie o assistente de IA e tente novamente.
• Se o problema persistir, denuncie-o ao seu provedor assistente de IA.

Erros de cliente sem suporte

Clientes não Microsoft não podem se autenticar

Sintoma: Clientes como Claude Desktop, Claude Code, Cursor ou Codex não podem concluir o handshake OAuth com o servidor MCP remoto.

Resolução:

Clientes não Microsoft não podem se autenticar com o servidor MCP remoto porque Microsoft Entra ID atualmente não dá suporte ao registro dinâmico do cliente, o que esses clientes exigem.

Clientes com suporte no momento:

• Visual Studio Code
• Visual Studio (2022 e posterior)

Para clientes não Microsoft, use o servidor local Azure DevOps MCP Server com autenticação via PAT ou CLI do Azure, em vez disso. Não execute os servidores remotos e locais ao mesmo tempo – escolha aquele que corresponda ao seu cliente.

Dicas de diagnóstico

Habilitar o registro de depuração no VS Code

Para capturar mais detalhes ao solucionar problemas:

1. Abra o painel Saída no VS Code (Exibir>Saída).
2. Selecione GitHub Copilot ou MCP na lista suspensa do canal de saída.
3. Procure o status da conexão, os detalhes do fluxo de autenticação e as mensagens de erro.

Verificar a conexão

Após a instalação, teste o servidor MCP remoto com uma consulta simples:

• "Liste os projetos na minha organização Azure DevOps."
• "Mostrar meus itens de trabalho atribuídos."
• "Quais solicitações de pull precisam da minha revisão?"

Se essas consultas retornarem dados corretos, o servidor estará funcionando corretamente.

FAQs

Posso usar o servidor MCP remoto com um conta Microsoft pessoal?

Não. O servidor MCP remoto exige que sua organização Azure DevOps esteja conectada a Microsoft Entra ID. Não há suporte para MSA (contas de Microsoft pessoais).

Devo usar o servidor MCP remoto ou local?

Use o servidor remoto se o cliente der suporte a ele (Visual Studio Code ou Visual Studio). Use o servidor local somente se você estiver usando um cliente não Microsoft, como Claude Desktop, Claude Code, Cursor ou Codex. Não execute os dois servidores ao mesmo tempo.

Por que vejo ferramentas diferentes com o servidor remoto versus local?

Os servidores remotos e locais podem estar em versões diferentes. O servidor remoto é atualizado independentemente do pacote npm local. Use o X-MCP-Insiders cabeçalho para acessar as ferramentas remotas mais recentes. Para o servidor local, atualize o pacote npm para a versão mais recente.

O servidor MCP funciona com Azure DevOps Server (local)?

Não. Nem o Servidor MCP remoto nem o Servidor MCP local oferecem suporte ao Azure DevOps Server (on-premises). Ambos os servidores exigem serviços de Azure DevOps (nuvem).

Quais dados o servidor MCP remoto acessa?

O servidor remoto acessa os mesmos dados de Azure DevOps que a API REST, com escopo para suas permissões. Ele não acessa dados além do que sua identidade Microsoft Entra está autorizada a ver.

Como relatar um problema com o servidor MCP remoto?

Crie um problema usando o modelo de issue do Servidor MCP Remoto no repositório do GitHub do Azure DevOps MCP Server.

Conteúdo relacionado

• Configurar o servidor remoto Azure DevOps MCP (versão preliminar)
• Visão geral do Servidor MCP do Azure DevOps
• Repositório GitHub do Azure DevOps MCP Server