Resolver problemas do Azure DevOps MCP Server remoto

Serviços de DevOps do Azure

Este artigo ajuda-o a diagnosticar e resolver problemas comuns com o remote Azure DevOps MCP Server. Para problemas com o servidor MCP local, consulte o guia local de resolução de problemas do servidor MCP.

Falhas de ligação

Servidor não encontrado ou erros de URL

Sintoma: O seu assistente de IA não consegue ligar-se ao servidor MCP remoto, ou verá erros relacionados com URLs.

Resolution:

1. Verifique o formato da URL do servidor no 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 sua empresa.
   • Use apenas o nome da organização (por exemplo, contoso), não a URL Azure DevOps completa.
   • O type deve ser "http", não "stdio".

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

Bloqueios de rede ou firewall

Sintoma: A ligação expira ou é recusada, mas o URL está correto.

Resolution:

• Assegure que a sua rede permite o tráfego HTTPS de saída para mcp.dev.azure.com.
• Se estiveres atrás de um proxy corporativo ou firewall, verifica se mcp.dev.azure.com não está bloqueado. Contacte o seu administrador de rede para adicionar este endpoint à lista de permissões.
• Configurações de VPN podem interferir com a conectividade. Tenta ligar-te sem VPN para isolar o problema.

Disponibilidade de pré-visualizações

Sintoma: Recebes um erro a indicar que o serviço não está disponível.

Resolution:

O servidor MCP remoto está em pré-visualização pública e está a ser implementado gradualmente. Se não conseguir ligar:

• Verifique se a sua organização está ligada ao Microsoft Entra ID.
• Volte mais tarde, pois a versão prévia continua a ser expandida.
• Confirme junto do administrador da sua organização se não existem políticas que bloqueiem funcionalidades de pré-visualização.

Erros de autenticação

O servidor MCP remoto utiliza o Microsoft Entra ID (OAuth) para autenticação. Tokens de acesso pessoal (PATs) não são suportados para o servidor remoto.

O prompt de iniciar sessão falha ou não aparece

Sintoma: O prompt de início de sessão OAuth não aparece, ou a autenticação falha antes de conseguires iniciar sessão.

Resolution:

1. Verifique se a sua conta está ligada ao Microsoft Entra ID. O servidor MCP remoto requer uma identidade suportada pelo Microsoft Entra.
2. Verifica se é possível abrir o teu navegador para o fluxo de OAuth. Se usares VS Code num ambiente remoto ou headless, o redirecionamento OAuth pode não funcionar corretamente.
3. Limpar credenciais em cache:
   • No VS Code, abra a Paleta de Comandos (Ctrl+Shift+P) e execute Contas: Logout. Depois tenta a ligação novamente.
   • Se o problema persistir, recarregue a janela do VS Code (Desenvolvedor: Recarregar a janela).

Falha de autorização após iniciar sessão

Sintoma: Inicia sessão com sucesso, mas recebe um erro de autorização ao tentar aceder à sua organização ou projeto.

Resolution:

• Confirma que tens o nível correto acesso na organização Azure DevOps.
• Confirma que és membro do projeto ao qual estás a tentar aceder.
• Verifica se as permissões do Azure DevOps incluem acesso aos recursos que estás a consultar (por exemplo, itens de trabalho, repositórios ou pipelines).

As políticas de Acesso Condicional bloqueiam o acesso

Sintoma: A política de Acesso Condicional do Microsoft Entra impede o seu início de sessão.

Resolution:

As políticas de Acesso Condicional aplicam-se ao servidor MCP remoto da mesma forma que se aplicam ao Azure DevOps. Se o seu inquilino aplicar políticas como restrições baseadas na localização ou no dispositivo:

• Certifique-se de que está a iniciar sessão a partir de um dispositivo e localização de rede compatíveis.
• Se o seu inquilino usar políticas de Acesso Condicional baseadas na localização, o administrador do seu Microsoft Entra ID pode precisar de permitir a lista dos endereços IP remotos do Servidor MCP: 20.125.155.22 e 40.74.28.81.
• Contacte o administrador do seu Microsoft Entra ID para requisitos específicos de política.

O acesso de convidado (B2B) falha

Sintoma: Um utilizador convidado no inquilino Microsoft Entra não pode aceder ao servidor MCP remoto.

Resolution:

Para o acesso de convidados ao trabalho, o utilizador deve ser:

1. Adicionado ao Microsoft Entra tenant como utilizador convidado.
2. Adicionado à organização Azure DevOps com as permissões apropriadas.
3. Concederam-lhes acesso aos projetos e recursos específicos de que precisam.
4. Usando o URL específico da organização (https://mcp.dev.azure.com/{organization}). Os utilizadores convidados não podem usar a URL raiz (https://mcp.dev.azure.com/) — devem incluir o nome da organização na URL.

Se algum destes passos estiver em falta, o acesso falha. Trate este problema da mesma forma que um problema padrão de acesso de convidados no Azure DevOps.

Códigos de erro AADSTS

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

Resolution:

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

Para uma lista completa de códigos de erro, veja 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 liga-se mas as ferramentas não carregam, ou então surgem comportamentos inesperados.

Resolution:

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

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

Não misture formatos de configuração remota e local. Não execute ambos os servidores ao mesmo tempo — escolha um:

• Servidor remoto — Utilize para o Visual Studio Code e o Visual Studio. Não é necessária instalação local.
• Servidor local — Utilizar para clientes não-Microsoft (Claude Desktop, Claude Code, Cursor, Codex) que não suportam autenticação Microsoft Entra.

Conjunto de ferramentas ou filtragem de ferramentas não funciona

Sintoma: Configura os cabeçalhos X-MCP-Toolsets ou X-MCP-Tools, mas a lista de ferramentas não corresponde ao esperado.

Resolution:

• Não combine os cabeçalhos X-MCP-Toolsets e X-MCP-Tools — 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 nomes exatos de ferramentas separados por vírgulas.
• Verifique se existem erros tipográficos nos nomes dos cabeçalhos - 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 a lista completa de conjuntos de ferramentas e ferramentas disponíveis, consulte Ferramentas disponíveis.

O modo apenas de leitura não restringe as operações de escrita

Sintoma: Define X-MCP-Readonly , mas as operações de escrita continuam disponíveis.

Resolution:

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

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

Erros de resolução de ferramentas

Ferramentas que não aparecem no assistente de IA

Sintoma: Depois de ligar o servidor MCP remoto, nenhuma ferramenta de Azure DevOps aparece no seu assistente de IA.

Resolution:

1. Confirma que o estado do servidor aparece como ligado no teu IDE.
   • No VS Code, verifique o estado do servidor MCP no painel de saída (View>Output>: selecione GitHub Copilot ou MCP na lista pendente).
2. Recarregar a janela do VS Code (Ctrl+Shift+P>Programador: Recarregar Janela).
3. Confirma se estás em modo agente no GitHub Copilot—as ferramentas MCP só aparecem no modo agente, não no modo chat.
4. Verifique se não ultrapassa o limite de 128 ferramentas. Se tiveres vários servidores MCP configurados, o número combinado de ferramentas pode ultrapassar este limite.

Faltam erros de parâmetros obrigatórios

Sintoma: As chamadas à ferramenta falham com erros de "falta de um parâmetro obrigatório", tipicamente relativos ao nome do projeto.

Resolution:

Este erro é o mais frequentemente reportado e é um comportamento esperado. Muitas ferramentas requerem um nome de projeto ou outro contexto:

• Inclua o nome do projeto no seu prompt: "Listar itens de trabalho no projeto Contoso ."
• Se omitiste a organização do teu URL, inclui também a organização no teu prompt.
• Algumas ferramentas exigem parâmetros específicos. Consulte a documentação de Ferramentas Disponíveis para os parâmetros necessários.

Chamada de ferramenta falha com erro de servidor

Sintoma: Uma chamada de ferramenta devolve um erro de servidor após ser invocada corretamente.

Resolution:

• Verifica se o recurso que estás a consultar existe (por exemplo, o ID do item de trabalho, nome do repositório ou ID do pipeline está correto).
• Confirma que tens permissões para aceder ao recurso.
• Se o erro persistir, abra uma ocorrência utilizando o modelo de ocorrência do Remote MCP Server.

Problemas de integração do Copilot

O assistente de IA não utiliza ferramentas MCP

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

Resolution:

1. Certifica-te de que estás a usar o modo agente no GitHub Copilot. As ferramentas MCP não estão disponíveis no modo de chat padrão.
2. Seja explícito no seu prompt sobre os dados do Azure DevOps de que precisa. Por exemplo, em vez de "Qual é o meu estado de sprint?", tenta "Usar Azure DevOps para obter os meus itens de trabalho de sprint atuais."
3. Verifica se o servidor MCP aparece como ligado com um indicador de estado verde.

Foram devolvidos dados obsoletos ou em cache

Sintoma: O assistente de IA devolve dados Azure DevOps desatualizados.

Resolution:

Adicione "Não use dados previamente buscados" ao seu prompt para forçar uma consulta nova. Os assistentes de IA podem guardar em cache os resultados das ferramentas durante uma sessão de conversa.

O agente falhou antes da invocação da ferramenta

Sintoma: O assistente de IA falha ou comete erros antes de invocar qualquer ferramenta MCP.

Resolution:

Esta questão está fora dos limites do Azure DevOps MCP. A falha ocorre na camada de orquestração do assistente de IA:

• Para GitHub Copilot questões, consulte GitHub Copilot documentação.
• Reinicia o assistente de IA e tenta novamente.
• Se o problema persistir, reporte ao seu fornecedor assistente de IA.

Erros de cliente não suportados

Clientes que não são da Microsoft não conseguem autenticar

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

Resolution:

Os clientes que não são da Microsoft não conseguem autenticar-se com o servidor MCP remoto porque o Microsoft Entra ID atualmente não suporta registo dinâmico de clientes, que estes clientes exigem.

Clientes atualmente suportados:

• Código do Visual Studio
• Visual Studio (2022 e posteriores)

Para clientes não Microsoft, utilize o local Azure DevOps MCP Server com autenticação PAT ou CLI do Azure em vez disso. Não execute simultaneamente os servidores remoto e local — escolha aquele que corresponde ao seu cliente.

Dicas de diagnóstico

Ativar o registo de depuração no VS Code

Para captar mais detalhes quando estiver a fazer a resolução de problemas:

1. Abra o painel de Saída em VS Code (Ver>Saída).
2. Selecione GitHub Copilot ou MCP no menu suspenso do canal de saída.
3. Procura o estado da ligação, detalhes do fluxo de autenticação e mensagens de erro.

Verifique a ligação

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

• "Lista os projetos na minha organização Azure DevOps."
• Mostra os meus itens de trabalho atribuídos.
• Quais os pull requests que precisam de ser revistos por mim?

Se estas consultas devolverem dados corretos, o servidor está a funcionar corretamente.

FAQs

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

Não. O servidor MCP remoto exige que a sua organização Azure DevOps esteja ligada ao Microsoft Entra ID. Contas pessoais da Microsoft (MSA) não são suportadas.

Devo usar o servidor MCP remoto ou local?

Utilize o servidor remoto se o seu cliente o suportar (Visual Studio Code ou Visual Studio). Usa o servidor local apenas se estiveres a usar um cliente que não seja da Microsoft, como Claude Desktop, Claude Code, Cursor ou Codex. Não execute ambos os servidores ao mesmo tempo.

Porque é que vejo ferramentas diferentes no servidor remoto em comparação com o 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 aceder às ferramentas remotas mais recentes. Para o servidor local, atualiza o pacote npm para a versão mais recente.

O MCP Server funciona com o Azure DevOps Server (on-premises)?

Não. Nem o servidor MCP remoto nem o local suportam o Azure DevOps Server (on-premises). Ambos os servidores requerem Azure DevOps Services (cloud).

A que dados o servidor MCP remoto acede?

O servidor remoto acede aos mesmos dados do Azure DevOps que a API REST, com o âmbito das suas permissões. Não acede a dados para além do que a sua identidade Microsoft Entra está autorizada a ver.

Como posso reportar um problema com o servidor MCP remoto?

Crie um problema usando o modelo de problema Remote MCP Server no repositório GitHub Azure DevOps MCP Server.

Conteúdo relacionado

• Configurar o Servidor MCP Remoto do Azure DevOps (pré-visualização)
• Azure DevOps Visão geral do servidor MCP
• Repositório do GitHub do servidor MCP do Azure DevOps