Solución de problemas del servidor MCP de Azure DevOps remoto

servicios de Azure DevOps

Este artículo le ayuda a diagnosticar y resolver problemas comunes con el servidor MCP remoto de Azure DevOps. Para ver los problemas del servidor MCP local, consulte la guía de solución de problemas del servidor MCP local.

Fallos de conexión

Servidor no encontrado o errores de URL

Síntoma: El asistente de IA no puede conectarse al servidor MCP remoto o verá errores relacionados con direcciones URL.

Resolución:

1. Compruebe el formato de dirección URL del servidor en mcp.json:

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

2. Confirme lo siguiente:

   • Use https://mcp.dev.azure.com/{organization} — sustituya {organization} por el nombre real de su organización.
   • Use solo el nombre de la organización (por ejemplo, contoso), no la dirección URL de Azure DevOps completa.
   • type debe ser "http", no "stdio".

3. Si omite el nombre de la organización de la dirección URL (https://mcp.dev.azure.com/), debe proporcionar el nombre de la organización como contexto en cada llamada de herramienta.

Bloques de red o firewall

Síntoma: La conexión agota el tiempo de espera o se rechaza, pero la dirección URL es correcta.

Resolución:

• Asegúrese de que la red permite el tráfico HTTPS saliente a mcp.dev.azure.com.
• Si está detrás de un proxy corporativo o firewall, compruebe que mcp.dev.azure.com no está bloqueado. Póngase en contacto con su administrador de red para añadir este punto de conexión a la lista de permitidos.
• Las configuraciones de VPN pueden interferir con la conectividad. Intente conectarse sin VPN para aislar el problema.

Errores de autenticación

El servidor MCP remoto usa Microsoft Entra ID (OAuth) para la autenticación. Los tokens de acceso personal (PAT) no se admiten para el servidor remoto.

Se produce un error en la solicitud de inicio de sesión o no aparece

Síntoma: La solicitud de inicio de sesión de OAuth no aparece o se produce un error en la autenticación antes de poder iniciar sesión.

Resolución:

1. Compruebe que la cuenta está conectada a Microsoft Entra ID. El servidor MCP remoto requiere una identidad respaldada por Microsoft Entra.
2. Compruebe que el explorador puede abrirse para el flujo de OAuth. Si utilizas VS Code en un entorno remoto o sin interfaz gráfica, es posible que la redirección de OAuth no funcione correctamente.
3. Borrar credenciales almacenadas en caché:
   • En VS Code, abra la paleta de comandos (Ctrl+Mayús+P) y ejecute Cuentas: Cerrar sesión. A continuación, vuelva a intentar la conexión.
   • Si el problema persiste, vuelva a cargar la ventana de VS Code (Desarrollador: Volver a cargar ventana).

Error de autorización después del inicio de sesión

Síntoma: Inicia sesión correctamente, pero recibe un error de autorización al intentar acceder a su organización o proyecto.

Resolución:

• Confirme que tiene el nivel de acceso correcto en la organización de Azure DevOps.
• Compruebe que es miembro del proyecto al que intenta acceder.
• Compruebe que los permisos de Azure DevOps incluyan acceso a los recursos que está consultando (por ejemplo, elementos de trabajo, repositorios o canalizaciones).

Las directivas de acceso condicional bloquean el acceso

Symptom: Una directiva de Acceso condicional de Microsoft Entra bloquea el inicio de sesión.

Resolución:

Las directivas de acceso condicional se aplican al servidor MCP remoto de la misma manera que se aplican a Azure DevOps. Si el inquilino aplica directivas como restricciones basadas en la ubicación o basadas en dispositivos:

• Asegúrese de que inicia sesión desde un dispositivo compatible y una ubicación de red.
• Si el inquilino usa directivas de acceso condicional basadas en la ubicación, es posible que el administrador de Microsoft Entra ID tenga que enumerar las direcciones IP remotas del servidor MCP: 20.125.155.22 y 40.74.28.81.
• Póngase en contacto con el administrador de Microsoft Entra ID para conocer los requisitos de directiva específicos.

El acceso de invitado (B2B) falla

Symptom: Un usuario invitado del inquilino de Microsoft Entra no puede acceder al servidor MCP remoto.

Resolución:

Para que el acceso de invitado funcione, el usuario debe ser:

1. Añadido al inquilino de Microsoft Entra como usuario invitado.
2. Se ha agregado a la organización de Azure DevOps con los permisos adecuados.
3. Se concede acceso a los proyectos y recursos específicos que necesitan.
4. Uso de la dirección URL específica de la organización (https://mcp.dev.azure.com/{organization}). Los usuarios invitados no pueden usar la dirección URL raíz (https://mcp.dev.azure.com/): deben incluir el nombre de la organización en la dirección URL.

Si falta alguno de estos pasos, se produce un error en el acceso. Trate este problema igual que un problema de acceso de invitado estándar Azure DevOps.

Códigos de error AADSTS

Síntoma: Aparece un código de error que empieza por AADSTS (por ejemplo, AADSTS50076, AADSTS700016).

Resolución:

Los errores AADSTS son errores de autenticación de Microsoft Entra ID y no problemas específicos de MCP. Los códigos más comunes son:

Para obtener una lista completa de los códigos de error, consulte Microsoft Entra códigos de error de autenticación y autorización.

Problemas de Entra

No se encuentra la aplicación empresarial Azure DevOps MCP en el inquilino

No puede encontrar la aplicación empresarial Azure DevOps MCP en Microsoft Entra ID>Aplicaciones empresariales, y la autenticación remota de MCP Server falla.

Resolución:

El siguiente procedimiento crea la entidad de servicio que falta para Azure DevOps MCP en tu inquilino.

• Quién debe ejecutar esto: un usuario con permisos administrador de aplicaciones, administrador de aplicaciones en la nube o administrador global en el inquilino.
• Requisito previo: instale CLI de Azure.
• Id. de aplicación: 2a72489c-aab2-4b65-b93a-a91edccf33b8.

Ejecute cada paso uno por uno y guarde la salida del comando.

1. Paso 0: inicie sesión en su inquilino (sustituya <yourTenantId>):

   az login --tenant <yourTenantId> --allow-no-subscriptions
   

   az account show --query "{tenant:tenantId, user:user.name}" -o table
   

   Confirme que el valor del inquilino coincide con su ID de inquilino.

2. Paso 1: Confirmar que la aplicación falta actualmente:

   az rest --method get --url "https://graph.microsoft.com/v1.0/servicePrincipals(appId='2a72489c-aab2-4b65-b93a-a91edccf33b8')"
   

   Resultado esperado: 404 con Request_ResourceNotFound. Este resultado confirma el problema.

3. Paso 2: Creación de la aplicación en el inquilino:

   az ad sp create --id 2a72489c-aab2-4b65-b93a-a91edccf33b8
   

4. Paso 3: Compruebe que la aplicación ya existe:

   az rest --method get --url "https://graph.microsoft.com/v1.0/servicePrincipals(appId='2a72489c-aab2-4b65-b93a-a91edccf33b8')"
   

   Resultado esperado: 200 respuesta que contiene "displayName": "Azure DevOps MCP" y "accountEnabled": true.

5. Paso 4: Confirmar en el portal:

   Vaya a portal.azure.com>Microsoft Entra ID>Aplicaciones empresariales, establezca Tipo de aplicación en Todas las aplicaciones y busque Azure DevOps MCP o 2a72489c-aab2-4b65-b93a-a91edccf33b8.

Ahora debería aparecer la aplicación y puede administrar sus permisos.

Problemas de configuración del servidor

Configuración incorrecta mcp.json

Síntoma: El servidor MCP remoto se conecta, pero las herramientas no se cargan o se produce un comportamiento inesperado.

Resolución:

Compruebe que mcp.json usa el formato correcto para el servidor remoto:

• El servidor remoto usa "type": "http" y "url".
• El servidor local usa "type": "stdio", "command"y "args".

No mezcle formatos de configuración remotos y locales. No ejecute ambos servidores al mismo tiempo: elija uno:

• Servidor remoto: se recomienda para entornos admitidos, como Visual Studio Code, Visual Studio, Microsoft Foundry, Microsoft Copilot Studio y GitHub Copilot. No se requiere ninguna instalación local.
• Servidor local : se usa para clientes que no Microsoft (Claude Desktop, Claude Code, Cursor, Codex) que no admiten la autenticación Microsoft Entra.

El conjunto de herramientas o el filtrado de herramientas no funcionan

Síntoma: Puede configurar X-MCP-Toolsets o X-MCP-Tools encabezados, pero la lista de herramientas no coincide con las expectativas.

Resolución:

• No combines los encabezados X-MCP-Toolsets y X-MCP-Tools, ya que son mutuamente excluyentes.
• Compruebe que los nombres del conjunto de herramientas son correctos: repos, wit, wikipipelines, , work, . testplan
• Al usar X-MCP-Tools, especifique nombres exactos de herramientas separados por comas.
• Compruebe si hay errores tipográficos en los nombres de encabezado: los encabezados distinguen mayúsculas de minúsculas.

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

Para obtener la lista completa de conjuntos de herramientas y herramientas disponibles, consulte Herramientas disponibles.

Modo de solo lectura que no restringe la escritura

Síntoma: Estableces X-MCP-Readonly, pero las operaciones de escritura siguen disponibles.

Resolución:

Compruebe que el valor del encabezado es la cadena "true":

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

Errores de resolución de la herramienta

Herramientas que no aparecen en el asistente de IA

Symptom: Después de conectar el servidor MCP remoto, no aparecen herramientas de Azure DevOps en el asistente de IA.

Resolución:

1. Confirme que el estado del servidor se muestra como conectado en el IDE.
   • En VS Code, Compruebe el estado del servidor MCP en el panel Salida (View>Output> seleccione GitHub Copilot o MCP en la lista desplegable).
2. Vuelva a cargar la ventana de VS Code (Ctrl+Mayús+P>Developer: Volver a cargar ventana).
3. Compruebe que está en modo agent en GitHub Copilot: las herramientas de MCP solo aparecen en modo de agente, no en modo de chat.
4. Compruebe que no supere el límite de 128 herramientas. Si tiene varios servidores MCP configurados, es posible que el recuento de herramientas combinado supere este límite.

Errores por falta de parámetros obligatorios

Síntoma: Las llamadas a herramientas fallan con errores de "falta un parámetro obligatorio", normalmente relacionados con el nombre del proyecto.

Resolución:

Este error es el error que se notifica con más frecuencia y es el comportamiento esperado. Muchas herramientas requieren un nombre de proyecto u otro contexto:

• Incluya el nombre del proyecto en su solicitud: "Enumera los elementos de trabajo del proyecto Contoso."
• Si ha omitido la organización en la URL, inclúyala también en la línea de comandos.
• Algunas herramientas requieren parámetros específicos. Consulte la documentación herramientas disponibles para conocer los parámetros necesarios.

La llamada a la herramienta falla con un error del servidor

Síntoma: Una llamada a herramienta devuelve un error de servidor después de invocarse correctamente.

Resolución:

• Compruebe que el recurso que está consultando existe (por ejemplo, el identificador del elemento de trabajo, el nombre del repositorio o el identificador de canalización es correcto).
• Confirme que tiene permisos para acceder al recurso.
• Si el error persiste, cree un problema mediante la plantilla de problema del servidor MCP remoto.

problemas de integración de Copilot

El asistente para IA no usa herramientas de MCP

Symptom: GitHub Copilot responde a su pregunta, pero no usa Azure DevOps herramientas de MCP para recuperar datos.

Resolución:

1. Asegúrese de que usa agent mode en GitHub Copilot. Las herramientas de MCP no están disponibles en el modo de chat estándar.
2. Sé explícito en tu instrucción sobre qué datos de Azure DevOps necesitas. Por ejemplo, en lugar de «¿Cuál es el estado de mi sprint?», prueba «Usa Azure DevOps para obtener los elementos de trabajo de mi sprint actual».
3. Compruebe que el servidor MCP se muestra como conectado con un indicador de estado verde.

Se han devuelto datos obsoletos o en caché

Symptom: El asistente para IA devuelve datos de Azure DevOps obsoletos.

Resolución:

Añada No utilizar datos recuperados anteriormente a la línea de comandos para forzar una nueva consulta. Los asistentes de IA pueden almacenar en caché los resultados de la herramienta dentro de una sesión de conversación.

El agente falla antes de la llamada a la herramienta

Síntoma: El asistente de IA produce un error o se produce un error antes de invocar cualquier herramienta MCP.

Resolución:

Este problema está fuera del límite Azure DevOps MCP. El error se produce en la capa de orquestación del asistente de IA:

• Para problemas de GitHub Copilot, consulte la documentación de GitHub Copilot.
• Reinicie el asistente de IA e inténtelo de nuevo.
• Si el problema persiste, notifique al proveedor del asistente de IA.

Errores de cliente no compatibles

Los clientes que no Microsoft no se pueden autenticar

Síntoma: Los clientes como Claude Desktop, Claude Code, Cursor o Codex no pueden completar el protocolo de enlace de OAuth con el servidor MCP remoto.

Resolución:

Los clientes que no Microsoft no se pueden autenticar con el servidor MCP remoto porque Microsoft Entra ID no admite actualmente el registro dinámico de cliente, que estos clientes requieren.

Clientes admitidos actualmente:

• Código de Visual Studio
• Visual Studio (2022 y versiones posteriores)
• Microsoft Foundry
• Microsoft Copilot Studio
• GitHub Copilot
• CLI de GitHub Copilot
• aplicación Copilot de GitHub

En el caso de los clientes que no son de Microsoft, use el local Azure DevOps servidor MCP con autenticación PAT o CLI de Azure en su lugar. No ejecute los servidores remotos y locales al mismo tiempo, elija el que coincida con el cliente.

Sugerencias de diagnóstico

Habilite el registro de depuración en VS Code

Para capturar más detalles al solucionar problemas:

1. Abra el panel Salida en VS Code (Ver>salida).
2. Seleccione GitHub Copilot o MCP en la lista desplegable del canal de salida.
3. Busque el estado de conexión, los detalles del flujo de autenticación y los mensajes de error.

Verifique la conexión

Después de la instalación, pruebe el servidor MCP remoto con una consulta sencilla:

• "Enumere los proyectos de mi organización de Azure DevOps".
• "Mostrar mis elementos de trabajo asignados."
• "¿Qué solicitudes de incorporación de cambios necesitan mi revisión?"

Si estas consultas devuelven datos correctos, el servidor funciona correctamente.

FAQs

¿Puedo usar el servidor MCP remoto con un cuenta Microsoft personal?

No. El servidor MCP remoto requiere que la organización de Azure DevOps esté conectada a Microsoft Entra ID. No se admiten cuentas de Microsoft personales (MSA).

¿Debo usar el servidor MCP remoto o local?

Use el servidor remoto si el entorno lo admite. Se recomienda el servidor remoto porque no requiere ninguna instalación local y Azure DevOps administra sus actualizaciones. Use el servidor local solo si usa un cliente como Claude Desktop, Claude Code, Cursor o Codex que no se puede autenticar en el servidor remoto. No ejecute ambos servidores al mismo tiempo.

¿Por qué veo diferentes herramientas con el servidor remoto frente al servidor local?

Los servidores remotos y locales pueden estar en diferentes versiones. El servidor remoto se actualiza independientemente del paquete npm local. Use el X-MCP-Insiders encabezado para acceder a las herramientas remotas más recientes. Para el servidor local, actualice el paquete npm a la versión más reciente.

¿Funciona el servidor MCP con Azure DevOps Server (local)?

No. Ni el servidor de MCP local ni el remoto admiten Azure DevOps Server (local). Ambos servidores requieren Azure DevOps Services (nube).

¿A qué datos accede el servidor MCP remoto?

El servidor remoto accede a los mismos datos de Azure DevOps que la API REST, limitados a sus permisos. No tiene acceso a los datos más allá de lo que su identidad de Microsoft Entra está autorizada para ver.

¿Cómo se notifica un problema con el servidor MCP remoto?

Cree una incidencia usando la Remote MCP Server issue template en el repositorio de GitHub de Azure DevOps MCP Server.

Contenido relacionado

• Configuración del servidor MCP de Azure DevOps remoto
• Introducción al servidor MCP de Azure DevOps
• Repositorio de GitHub del servidor MCP de Azure DevOps