Risolvere i problemi relativi al server MCP Azure DevOps remoto

Servizi di Azure DevOps

Questo articolo consente di diagnosticare e risolvere i problemi comuni relativi al remote Azure DevOps MCP Server. Per i problemi del server MCP locale, vedere la guida alla risoluzione dei problemi del server MCP locale.

Errori di connessione

Server non trovato o errori dell'URL

Sintomo: L'assistente di intelligenza artificiale non può connettersi al server MCP remoto o vengono visualizzati errori correlati all'URL.

Risoluzione:

1. Verifica il formato dell'URL del server nel tuo mcp.json:

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

2. Verificare quanto segue:

   • Usare https://mcp.dev.azure.com/{organization} : sostituire {organization} con il nome effettivo dell'organizzazione.
   • Usare solo il nome dell'organizzazione (ad esempio, contoso), non l'URL Azure DevOps completo.
   • Deve type essere "http", non "stdio".

3. Se si omette il nome dell'organizzazione dall'URL (https://mcp.dev.azure.com/), è necessario specificare il nome dell'organizzazione come contesto in ogni chiamata allo strumento.

Blocchi di rete o firewall

Sintomo: La connessione va in timeout o viene rifiutata, ma l'URL è corretto.

Risoluzione:

• Assicurarsi che la rete consenta il traffico HTTPS in uscita verso mcp.dev.azure.com.
• Se ti trovi dietro un proxy aziendale o un firewall, verifica che mcp.dev.azure.com non sia bloccato. Contatta l'amministratore di rete per aggiungere questo endpoint all'elenco consentito.
• Le configurazioni VPN potrebbero interferire con la connettività. Provare a connettersi senza VPN per isolare il problema.

Disponibilità dell'anteprima

Sintomo: Viene visualizzato un errore che indica che il servizio non è disponibile.

Risoluzione:

Il server MCP remoto è in anteprima pubblica e viene implementato gradualmente. Se non riesci a connetterti:

• Verificare che l'organizzazione sia connessa a Microsoft Entra ID.
• Torna più tardi, poiché l'anteprima continua ad ampliarsi.
• Verificare con l'amministratore dell'organizzazione che nessun criterio blocchi le funzionalità di anteprima.

Errori di autenticazione

Il server MCP remoto usa Microsoft Entra ID (OAuth) per l'autenticazione. I token di accesso personale non sono supportati per il server remoto.

La richiesta di accesso ha esito negativo o non viene visualizzata

Sintomo: La richiesta di accesso OAuth non viene visualizzata o l'autenticazione non riesce prima di poter accedere.

Risoluzione:

1. Verificare che l'account sia connesso a Microsoft Entra ID. Il server MCP remoto richiede un'identità supportata da Microsoft Entra.
2. Verificare che il browser possa essere aperto per il flusso OAuth. Se si usa VS Code in un ambiente remoto o headless, il reindirizzamento OAuth potrebbe non funzionare correttamente.
3. Cancellare le credenziali memorizzate nella cache:
   • In VS Code, apri la Raccolta comandi (Ctrl+Shift+P) ed esegui Accounts: Sign Out. Quindi prova di nuovo la connessione.
   • Se il problema persiste, ricaricare la finestra di VS Code (Developer: Reload Window).

Errore di autorizzazione dopo l'accesso

Sintomo: L'accesso viene eseguito correttamente, ma viene visualizzato un errore di autorizzazione quando si tenta di accedere all'organizzazione o al progetto.

Risoluzione:

• Verificare di avere il livello di accesso corretto nell'organizzazione Azure DevOps.
• Verificare di essere un membro del progetto a cui si sta tentando di accedere.
• Verificare che le autorizzazioni di Azure DevOps includano l'accesso alle risorse su cui si sta eseguendo una query, ad esempio elementi di lavoro, repository o pipeline.

I criteri di accesso condizionale bloccano l'accesso

Sintomo: Un criterio di Accesso condizionale di Microsoft Entra blocca l'accesso.

Risoluzione:

I criteri di accesso condizionale si applicano al server MCP remoto nello stesso modo in cui si applicano alle Azure DevOps. Se il tenant applica criteri quali restrizioni basate sulla posizione o basate sul dispositivo:

• Assicurarsi di eseguire l'accesso da un dispositivo e un percorso di rete conformi.
• Se il tenant usa criteri di accesso condizionale basati sulla posizione, l'amministratore Microsoft Entra ID potrebbe dover elencare gli indirizzi IP del server MCP remoti: 20.125.155.22 e 40.74.28.81.
• Contatta l'amministratore di Microsoft Entra ID per conoscere i requisiti specifici dei criteri.

L'accesso guest (B2B) non funziona

Symptom: Un utente guest nel tenant Microsoft Entra non può accedere al server MCP remoto.

Risoluzione:

Affinché l'accesso guest funzioni, l'utente deve essere:

1. Aggiunto al tenant Microsoft Entra come utente ospite.
2. Aggiunta all'organizzazione Azure DevOps con autorizzazioni appropriate.
3. È stato concesso l'accesso a progetti e risorse specifici necessari.
4. Uso dell'URL specifico dell'organizzazione (https://mcp.dev.azure.com/{organization}). Gli utenti guest non possono usare l'URL radice (https://mcp.dev.azure.com/): devono includere il nome dell'organizzazione nell'URL.

Se uno di questi passaggi non è presente, l'accesso non riesce. Tratta questo problema come un problema standard di Azure DevOps relativo all'accesso guest.

Codici di errore AADSTS

Sintomo: Viene visualizzato un codice di errore che inizia con AADSTS (ad esempio, AADSTS50076, AADSTS700016).

Risoluzione:

AADSTS errori sono errori di autenticazione di Microsoft Entra ID, non errori specifici di MCP. I codici comuni includono:

Per un elenco completo dei codici di errore, vedere Microsoft Entra codici di errore di autenticazione e autorizzazione.

Problemi di configurazione del server

Configurazione non corretta mcp.json

Sintomo: Il server MCP remoto si connette ma gli strumenti non vengono caricati o si ottiene un comportamento imprevisto.

Risoluzione:

mcp.json Verificare che usi il formato corretto per il server remoto:

• Il server remoto usa "type": "http" e "url".
• Il server locale usa "type": "stdio", "command"e "args".

Non combinare formati di configurazione remoti e locali. Non eseguire entrambi i server contemporaneamente: scegliere uno:

• Server remoto — Usare per Visual Studio Code e Visual Studio. Non è necessaria alcuna installazione locale.
• Server locale : usare per client non Microsoft (Claude Desktop, Claude Code, Cursor, Codex) che non supportano l'autenticazione Microsoft Entra.

Il set di strumenti o il filtro degli strumenti non funziona

Sintomo: Si configurano le intestazioni X-MCP-Toolsets o X-MCP-Tools, ma l'elenco degli strumenti non corrisponde a quanto previsto.

Risoluzione:

• Non combinare le intestazioni X-MCP-Toolsets e X-MCP-Tools: sono reciprocamente esclusive.
• Verificare che i nomi dei set di strumenti siano corretti: repos, wit, wikipipelines, worktestplan.
• Quando si usa X-MCP-Tools, specificare nomi esatti degli strumenti separati da virgole.
• Verifica la presenza di errori di digitazione nei nomi delle intestazioni: le intestazioni distinguono tra maiuscole e minuscole.

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

Per l'elenco completo dei set di strumenti e degli strumenti disponibili, vedere Strumenti disponibili.

Modalità di sola lettura che non limita le scritture

Sintomo: Si imposta X-MCP-Readonly, ma le operazioni di scrittura sono ancora disponibili.

Risoluzione:

Verificare che il valore dell'intestazione sia la stringa "true":

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

Errori di risoluzione dello strumento

Strumenti non visualizzati nell'assistente intelligenza artificiale

Symptom: Dopo aver connesso il server MCP remoto, nell'assistente intelligenza artificiale non vengono visualizzati strumenti di Azure DevOps.

Risoluzione:

1. Verificare che lo stato del server risulti connesso nel tuo IDE.
   • In VS Code, controllare lo stato del server MCP nel pannello Output (ViewOutput<>c3 /> selezionare GitHub Copilot o MCP dall'elenco a discesa).
2. Ricaricare la finestra di VS Code (CTRL+MAIUSC+P>Developer: Ricarica finestra).
3. Verificare di essere in modalità agent in GitHub Copilot: gli strumenti MCP vengono visualizzati solo in modalità agente, non in modalità chat.
4. Verifica che non superi il limite di 128 strumenti. Se sono configurati più server MCP, il numero combinato di strumenti potrebbe superare questo limite.

Errori di parametro obbligatori mancanti

Sintomo: Le chiamate degli strumenti hanno esito negativo con errori di "parametro obbligatorio mancante", in genere per il nome del progetto.

Risoluzione:

Questo errore è l'errore più comunemente segnalato ed è il comportamento previsto. Molti strumenti richiedono un nome di progetto o un altro contesto:

• Includere il nome del progetto nel prompt: "Elencare gli elementi di lavoro nel progetto Contoso ".
• Se hai omesso l'organizzazione dal tuo URL, includi anche l'organizzazione nel prompt.
• Alcuni strumenti richiedono parametri specifici. Per i parametri obbligatori, vedere la documentazione degli strumenti disponibili .

La chiamata allo strumento ha esito negativo e viene visualizzato un errore del server

Sintomo: Una chiamata allo strumento restituisce un errore del server dopo essere stato richiamato correttamente.

Risoluzione:

• Verificare che la risorsa su cui si sta eseguendo una query esista( ad esempio, l'ID dell'elemento di lavoro, il nome del repository o l'ID della pipeline è corretto).
• Verificare di disporre delle autorizzazioni per accedere alla risorsa.
• Se l'errore persiste, creare un problema usando il modello di problema server MCP remoto.

Problemi di integrazione di Copilot

Assistente intelligenza artificiale non usa strumenti MCP

Symptom: GitHub Copilot risponde alla domanda, ma non usa strumenti MCP Azure DevOps per recuperare i dati.

Risoluzione:

1. Assicurarsi di usare la modalità agent in GitHub Copilot. Gli strumenti MCP non sono disponibili in modalità chat standard.
2. Sii esplicito nel prompt riguardo a quali dati di Azure DevOps ti servono. Ad esempio, invece di "Qual è lo stato dello sprint?", provare "Usa Azure DevOps per ottenere gli elementi di lavoro sprint correnti".
3. Verificare che il server MCP sia connesso con un indicatore di stato verde.

Restituiti dati obsoleti o memorizzati nella cache

Symptom: L'assistente intelligenza artificiale restituisce dati di Azure DevOps obsoleti.

Risoluzione:

Aggiungi "Non usare i dati recuperati in precedenza" nel prompt per imporre una nuova query. Gli assistenti di intelligenza artificiale potrebbero memorizzare nella cache i risultati degli strumenti all'interno di una sessione di conversazione.

Agent ha esito negativo prima della chiamata dello strumento

Sintomo: L'assistente di intelligenza artificiale ha esito negativo o genera errori prima di richiamare qualsiasi strumento MCP.

Risoluzione:

Questo problema non rientra nel limite mcp Azure DevOps. L'errore si verifica nel livello di orchestrazione dell'assistente di intelligenza artificiale:

• Per GitHub Copilot problemi, vedere GitHub Copilot documentazione.
• Riavviare l'assistente intelligenza artificiale e riprovare.
• Se il problema persiste, segnalarlo al provider di assistenti di intelligenza artificiale.

Errori del client non supportati

I client non Microsoft non possono eseguire l'autenticazione

Sintomo: I client come Claude Desktop, Claude Code, Cursor o Codex non possono completare l'handshake OAuth con il server MCP remoto.

Risoluzione:

I client non Microsoft non possono eseguire l'autenticazione con il server MCP remoto perché Microsoft Entra ID attualmente non supporta la registrazione client dinamica, che questi client richiedono.

Client attualmente supportati:

• Visual Studio Code
• Visual Studio (2022 e versioni successive)

Per i client non Microsoft, usa invece il server MCP locale di Azure DevOps con autenticazione PAT o tramite interfaccia della riga di comando di Azure. Non eseguire contemporaneamente i server remoti e locali, scegliere quello che corrisponde al client.

Suggerimenti di diagnostica

Abilitare la registrazione di debug in VS Code

Per acquisire maggiori dettagli durante la risoluzione dei problemi:

1. Aprire il pannello Output in VS Code (Visualizza>output).
2. Selezionare GitHub Copilot o MCP dall'elenco a discesa del canale di output.
3. Cercare lo stato della connessione, i dettagli del flusso di autenticazione e i messaggi di errore.

Verificare la connessione

Dopo l'installazione, testare il server MCP remoto con una query semplice:

• "Elencare i progetti nell'organizzazione Azure DevOps."
• "Mostra gli elementi di lavoro assegnati".
• Quali pull request devono essere esaminate da me?

Se queste query restituiscono dati corretti, il server funziona correttamente.

Domande frequenti

È possibile usare il server MCP remoto con un account Microsoft personale?

No Il server MCP remoto richiede che l'organizzazione Azure DevOps sia connessa a Microsoft Entra ID. Gli account Microsoft personali (MSA) non sono supportati.

È consigliabile usare il server MCP remoto o locale?

Usare il server remoto se il client lo supporta (Visual Studio Code o Visual Studio). Usare il server locale solo se si usa un client non Microsoft come Claude Desktop, Claude Code, Cursor o Codex. Non eseguire entrambi i server contemporaneamente.

Perché vengono visualizzati diversi strumenti con il server remoto e locale?

I server remoti e locali potrebbero trovarsi in versioni diverse. Il server remoto viene aggiornato indipendentemente dal pacchetto npm locale. Usare l'intestazione X-MCP-Insiders per accedere agli strumenti remoti più recenti. Per il server locale, aggiornare il pacchetto npm alla versione più recente.

Il server MCP funziona con Azure DevOps Server (locale)?

No Né il server MCP remoto né il server MCP locale supporta Azure DevOps Server (locale). Entrambi i server richiedono Azure DevOps Servizi (cloud).

Quali dati accede al server MCP remoto?

Il server remoto accede agli stessi dati di Azure DevOps a cui accede l'API REST, in base alle tue autorizzazioni. Non accede ai dati oltre a ciò che l'identità Microsoft Entra è autorizzata a visualizzare.

Come si segnala un problema con il server MCP remoto?

Crea una segnalazione usando il modello di segnalazione per Remote MCP Server nel repository GitHub di Azure DevOps MCP Server.

Contenuti correlati

• Configurare il server MCP remoto di Azure DevOps (anteprima)
• Panoramica del server MCP di Azure DevOps
• Repository GitHub del server MCP di Azure DevOps