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):
lippia-neo-resolve-user-story-sourcereconoce que es un work item de Azure DevOps y verifica que el link sea de tu organización configurada.lippia-neo-fetch-user-storytrae el work item con todos sus campos a través del servidorazure-devops.- 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.
- Devuelve la historia en memoria, con el mismo formato que una historia local. No escribe ningún archivo.
lippia-neo-read-user-storyla lee y sigue el flujo normal de QA.
NEOsolo 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.
- 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. - Hacé clic en New Token.
- 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 |
- Create y copiá el token en ese momento: después no se puede volver a ver.
- 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-stackte 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.jsonaunque uses otro asistente. Las skills deNEOleenAZURE_DEVOPS_ORG_URLdesde.mcp.jsonpara 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.jsonconAZURE_DEVOPS_ORG_URL,lippia-neo-resolve-user-story-sourceconsidera 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 deaz login) yazure-identity(credenciales de Azure).NEOestá documentado y probado conpat.¿Y el MCP oficial de Microsoft? Microsoft publica su propio servidor MCP de Azure DevOps.
NEOusa@tiberriver256/mcp-server-azure-devopsporque es el de su plantilla. No cargues los dos con el mismo nombre.
6. Links con dominio visualstudio.com
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
NEOel ID del work item (1234) en vez del link. - Usar en
AZURE_DEVOPS_ORG_URLel mismo dominio que usan los links de tu equipo.
7. Verificar que funciona
- Reiniciá el asistente (o recargá la ventana). Los servidores se leen al arrancar.
- Abrí la lista de servidores (
/mcpen Claude Code o Codex, MCP: List Servers en VS Code…) y confirmá queazure-devopsfigura conectado. - 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 |