Saltar a contenido

Configurar el MCP de Azure DevOps

Esta guía explica, paso a paso, cómo conectar Azure DevOps (Azure Boards) para que NEO lea las historias de usuario directamente desde los work items, sin tener que copiarlas a un archivo.

Nombre del servidor azure-devops (usá siempre este nombre)
Paquete @tiberriver256/mcp-server-azure-devops, que se ejecuta con npx -y
Tipo Local (stdio): se ejecuta en tu computadora
Instancia soportada Azure DevOps Services (https://dev.azure.com/<organización> o https://<organización>.visualstudio.com)
Acceso Solo lectura: NEO nunca modifica work items
Skills que lo usan lippia-neo-fetch-user-story, y a través de ella lippia-neo-read-user-story y lippia-neo-resolve-user-story-source cuando les pasás un link de Azure DevOps

1. ¿Qué hace NEO con Azure DevOps?

Cuando le pasás al asistente un ID (1234) o un link de Azure Boards (https://dev.azure.com/techstore/Web/_workitems/edit/1234):

  1. lippia-neo-resolve-user-story-source reconoce que es un work item de Azure DevOps y verifica que el link sea de tu organización configurada.
  2. lippia-neo-fetch-user-story trae el work item con todos sus campos a través del servidor azure-devops.
  3. Pasa la descripción de HTML a markdown tal cual, sin reordenar ni resumir. En los Bugs, si la descripción está vacía, usa los Repro Steps.
  4. Devuelve la historia en memoria, con el mismo formato que una historia local. No escribe ningún archivo.
  5. lippia-neo-read-user-story la lee y sigue el flujo normal de QA.

NEO solo lee. No comenta, no cambia estados, no edita ni crea work items. Por eso el token recomendado tiene únicamente el permiso Work Items → Read.


2. Antes de empezar

Necesitás Por qué Cómo verificarlo
Node.js (trae npx) El servidor se lanza con npx. Sin npx, nunca arranca node -v · npx --version
Un usuario de Azure DevOps con acceso al proyecto El servidor ve exactamente lo mismo que ve tu usuario Poder abrir el work item en el navegador
La URL de tu organización Se configura en AZURE_DEVOPS_ORG_URL Es la URL con la que entrás, hasta el nombre de la organización (https://dev.azure.com/techstore)

Si no tenés Node.js, instalá la versión LTS desde nodejs.org. Después, abrí una terminal nueva y reiniciá el asistente para que npx quede en el PATH.


3. Paso 1 — Crear el Personal Access Token (PAT)

El servidor no usa tu contraseña: usa un Personal Access Token.

  1. Entrá a Azure DevOps y abrí User settings (el ícono de tu usuario, arriba a la derecha) → Personal access tokens. O andá directo a https://dev.azure.com/<tu-organización>/_usersSettings/tokens.
  2. Hacé clic en New Token.
  3. Completá:
Campo Qué poner
Name Algo que lo identifique, por ejemplo NEO - QA
Organization La organización donde están los work items
Expiration La que permita la política de tu empresa. Anotá la fecha: cuando vence, la conexión deja de funcionar
Scopes Custom defined → Work Items → Read. Nada más
  1. Create y copiá el token en ese momento: después no se puede volver a ver.
  2. Guardalo en un lugar seguro, por ejemplo un gestor de contraseñas. Nunca lo pegues en un archivo que se suba a git.

4. Paso 2 — Indicar en qa-stack.yaml que las historias vienen de Azure DevOps

paths:
  user_stories_storage:
    type: cloud
    cloud_provider_mcp: azure-devops
    local_path: user-stories/   # queda en el default: los work items nunca se guardan acá

# Opcional: ajustes de lectura de Azure DevOps
azure_devops:
  acceptance_criteria_field: Microsoft.VSTS.Common.AcceptanceCriteria   # campo estándar de Azure Boards
  default_project: Web                                                  # Team Project por defecto (opcional)
Campo Para qué Valor por defecto
user_stories_storage.type: cloud + cloud_provider_mcp: azure-devops Le dice a NEO que las historias vienen de Azure DevOps. Sin esto, los links de Azure se rechazan —
azure_devops.acceptance_criteria_field El campo de donde salen los criterios de aceptación Microsoft.VSTS.Common.AcceptanceCriteria
azure_devops.default_project El proyecto que se usa si no viene en el link ni en el pedido —

lippia-neo-bootstrap-stack te pregunta todo esto si elegís "historias en Azure DevOps", y de paso arma .mcp.json (Paso 3).

¿Dónde están los criterios de aceptación?

NEO los busca en este orden y usa el primero que encuentra:

Orden Dónde busca
1 El campo configurado en azure_devops.acceptance_criteria_field (por defecto, el campo Acceptance Criteria de Azure Boards)
2 La descripción del work item: un título "Criterios de aceptación" / "Acceptance Criteria" / "AC", una lista o bloques Gherkin (Dado/Cuando/Entonces)
3 Si no encuentra nada, no los inventa: deja una nota para completarlos a mano

Si tu equipo escribe los criterios en la descripción y deja vacío el campo Acceptance Criteria, poné acceptance_criteria_field: null.

¿De qué proyecto trae el work item?

En este orden: el proyecto que indiques en el pedido → azure_devops.default_project de qa-stack.yaml → AZURE_DEVOPS_DEFAULT_PROJECT de .mcp.json. Si el link trae un proyecto distinto del configurado, NEO usa el del link y te avisa.


5. Paso 3 — Configurar el servidor en tu asistente

Base para todos: .mcp.json en la raíz del proyecto

{
  "mcpServers": {
    "azure-devops": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@tiberriver256/mcp-server-azure-devops"],
      "env": {
        "AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/techstore",
        "AZURE_DEVOPS_AUTH_METHOD": "pat",
        "AZURE_DEVOPS_PAT": "<tu PAT>",
        "AZURE_DEVOPS_DEFAULT_PROJECT": "Web"
      }
    }
  }
}
Clave ¿Obligatoria? Para qué
AZURE_DEVOPS_ORG_URL Sí La URL de la organización
AZURE_DEVOPS_AUTH_METHOD Sí, con el valor "pat" Si no la ponés, el servidor usa otro método (azure-identity) y no toma tu PAT
AZURE_DEVOPS_PAT Sí El token del Paso 1
AZURE_DEVOPS_DEFAULT_PROJECT No Proyecto por defecto

⚠️ Tené este .mcp.json aunque uses otro asistente. Las skills de NEO leen AZURE_DEVOPS_ORG_URL desde .mcp.json para dos cosas: verificar que el link que pasás sea de tu organización, y armar el link de vuelta al work item en el reporte. Si usás Copilot, Codex o Claude Desktop (que guardan la configuración en otro archivo) y no hay .mcp.json con AZURE_DEVOPS_ORG_URL, lippia-neo-resolve-user-story-source considera que Azure DevOps no está configurado y frena con "URL de Azure DevOps pero el proyecto no está configurado para ese proveedor".

.mcp.json tiene que estar en .gitignore: lleva el token. Lo que se versiona es .mcp.json.template.

Según tu asistente

Asistente Qué hacer Detalle del formato
Claude Code (VS Code, CLI o pestaña Code de Claude Desktop) Nada más: lee el .mcp.json de arriba. Recargá la ventana o abrí una sesión nueva y aprobá el servidor IDE
GitHub Copilot en VS Code Cargá el servidor en .vscode/mcp.json con la clave servers, y usá inputs para el token IDE
GitHub Copilot en JetBrains / Visual Studio Mismo contenido con la clave servers JetBrains · Visual Studio
Codex (extensión, CLI o app de ChatGPT) Sección [mcp_servers.azure-devops] en ~/.codex/config.toml IDE · Terminal
Cursor Copiá el bloque tal cual a .cursor/mcp.json IDE
Claude Desktop (chat) Copiá el bloque, sin type, a claude_desktop_config.json y reiniciá la app Escritorio
ChatGPT (chat común) ❌ No sirve: solo acepta servidores remotos. Usá Codex Escritorio

Ejemplo para Copilot en VS Code (.vscode/mcp.json):

{
  "inputs": [
    { "id": "azure-pat", "type": "promptString", "description": "PAT de Azure DevOps", "password": true }
  ],
  "servers": {
    "azure-devops": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@tiberriver256/mcp-server-azure-devops"],
      "env": {
        "AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/techstore",
        "AZURE_DEVOPS_AUTH_METHOD": "pat",
        "AZURE_DEVOPS_PAT": "${input:azure-pat}",
        "AZURE_DEVOPS_DEFAULT_PROJECT": "Web"
      }
    }
  }
}

Ejemplo para Codex (~/.codex/config.toml):

[mcp_servers.azure-devops]
command = "npx"
args = ["-y", "@tiberriver256/mcp-server-azure-devops"]

[mcp_servers.azure-devops.env]
AZURE_DEVOPS_ORG_URL = "https://dev.azure.com/techstore"
AZURE_DEVOPS_AUTH_METHOD = "pat"
AZURE_DEVOPS_PAT = "<tu PAT>"
AZURE_DEVOPS_DEFAULT_PROJECT = "Web"

Por comando, en Claude Code CLI:

claude mcp add --transport stdio --scope project \
  --env AZURE_DEVOPS_ORG_URL=https://dev.azure.com/techstore \
  --env AZURE_DEVOPS_AUTH_METHOD=pat \
  --env AZURE_DEVOPS_PAT=<tu PAT> \
  --env AZURE_DEVOPS_DEFAULT_PROJECT=Web \
  azure-devops -- npx -y @tiberriver256/mcp-server-azure-devops

Otros métodos de autenticación: el servidor también acepta azure-cli (usa la sesión de az login) y azure-identity (credenciales de Azure). NEO está documentado y probado con pat.

¿Y el MCP oficial de Microsoft? Microsoft publica su propio servidor MCP de Azure DevOps. NEO usa @tiberriver256/mcp-server-azure-devops porque es el de su plantilla. No cargues los dos con el mismo nombre.


Azure DevOps tiene dos dominios para la misma organización:

Dominio Ejemplo
Actual https://dev.azure.com/techstore/Web/_workitems/edit/1234
Antiguo https://techstore.visualstudio.com/Web/_workitems/edit/1234

NEO reconoce los dos, pero compara el dominio del link con el de AZURE_DEVOPS_ORG_URL. Si tu equipo comparte links *.visualstudio.com y configuraste https://dev.azure.com/techstore (o al revés), la validación los rechaza. Tenés dos opciones:

  • Pasarle a NEO el ID del work item (1234) en vez del link.
  • Usar en AZURE_DEVOPS_ORG_URL el mismo dominio que usan los links de tu equipo.

7. Verificar que funciona

  1. Reiniciá el asistente (o recargá la ventana). Los servidores se leen al arrancar.
  2. Abrí la lista de servidores (/mcp en Claude Code o Codex, MCP: List Servers en VS Code…) y confirmá que azure-devops figura conectado.
  3. Probalo con un work item real:
/lippia-neo-fetch-user-story https://dev.azure.com/techstore/Web/_workitems/edit/1234

Tiene que devolver el título, el tipo, el estado, la descripción y los criterios de aceptación del work item, indicando de qué campo salieron.


8. Problemas comunes (y qué hacer)

Lo que ves Por qué puede pasar Qué hacer
❌ Azure DevOps MCP no está disponible en este entorno El servidor azure-devops no está configurado o no arrancó Revisar el Paso 3 y reiniciar el asistente
El servidor azure-devops figura como Failed Falta Node.js, o el asistente no encuentra npx en el PATH Instalar Node.js, abrir una terminal nueva y reiniciar el asistente
Error de autenticación aunque el PAT es correcto Falta AZURE_DEVOPS_AUTH_METHOD: "pat" Agregarlo
Error 401 / no autorizado El PAT venció, se creó para otra organización o no tiene el permiso Work Items → Read Crear un PAT nuevo con esa organización y ese permiso
El work item "no existe" Tu usuario no tiene permiso sobre ese proyecto, el ID es de otro proyecto o el ID está mal Abrir el work item en el navegador con tu usuario, o indicar el proyecto correcto
🛑 URL de Azure DevOps pero el proyecto no está configurado para ese proveedor Falta cloud_provider_mcp: azure-devops en qa-stack.yaml, o no hay servidor azure-devops en .mcp.json Completar el Paso 2 y el .mcp.json base del Paso 3
🛑 La URL apunta a una instancia de Azure DevOps distinta a la configurada El link es de otra organización, o usa el otro dominio (visualstudio.com vs. dev.azure.com) Ver la sección 6
No pude resolver el ID del work item La referencia no tiene un número de work item Pasar el ID o el link /_workitems/edit/<ID>
Los criterios de aceptación salen vacíos Tu equipo los escribe en la descripción y el campo Acceptance Criteria está vacío Poner acceptance_criteria_field: null en qa-stack.yaml
Agregaste el servidor pero no aparece El asistente no se reinició VS Code: Developer: Reload Window · CLI: abrir otra sesión · Claude Desktop: cerrar la app por completo