Configurar los MCP
Esta sección explica cómo conectar los servidores MCP que usa NEO con tu asistente de IA, sea que trabajes desde un editor de código (VS Code, JetBrains, Visual Studio, Cursor), desde una app de escritorio (Claude Desktop, ChatGPT Desktop, GitHub Copilot app) o desde la terminal.
| Dónde trabajás | Guía |
|---|---|
| Un editor de código con la extensión del asistente (Claude Code, GitHub Copilot, Codex, Cursor) | Configurar MCP en el IDE |
| Una app de escritorio (Claude Desktop, ChatGPT Desktop, GitHub Copilot app) | Configurar MCP en apps de escritorio |
| La terminal (Claude Code CLI, Codex CLI, GitHub Copilot CLI) | Configurar MCP en la terminal |
Y una guía por cada proveedor de historias de usuario, con el paso a paso para sacar el token, la configuración completa y cómo cargarla en cada herramienta:
| Proveedor | Guía |
|---|---|
| Jira (y Confluence) | Configurar el MCP de Jira |
| Azure DevOps (Azure Boards) | Configurar el MCP de Azure DevOps |
1. ¿Qué es un MCP?
Un MCP (Model Context Protocol) es un "enchufe" estándar que le da al asistente de IA acceso a una herramienta externa: un navegador, Jira, Azure DevOps, etc. El asistente no tiene esas capacidades por sí solo. Las consigue conectándose a un servidor MCP, un pequeño programa que se ejecuta en tu computadora (o en internet) y expone herramientas como browser_navigate o jira_get_issue.
Analogía: el asistente es la persona que hace el trabajo; cada servidor MCP es una herramienta que le prestás. Si no le prestás el navegador, no puede entrar a la aplicación a probarla.
Hay dos tipos de servidores MCP:
| Tipo | Cómo funciona | Ejemplo |
|---|---|---|
Local (stdio) |
El asistente lanza un programa en tu computadora con un comando (npx, uvx) |
Los tres servidores que usa NEO |
| Remoto (HTTP) | El asistente se conecta a una URL en internet | Conectores en la nube |
Importante: los tres servidores que usa
NEOson locales. Por eso solo funcionan en clientes que pueden lanzar servidores locales. Algunos, como el chat de ChatGPT, solo aceptan servidores remotos. Está detallado en cada guía.
2. ¿Qué servidores MCP usa NEO?
| Servidor | Paquete | Para qué lo usa NEO |
Skills que lo necesitan | ¿Obligatorio? |
|---|---|---|---|---|
playwright |
@playwright/mcp |
Abrir un navegador real, navegar la app, hacer clics y sacar screenshots | lippia-neo-scripted-execution, lippia-neo-bug-reproduction, lippia-neo-exploratory-session, lippia-neo-discover-exploratory-areas |
Sí, para explorar la app en vivo |
jira |
mcp-atlassian |
Leer historias de usuario de Jira y páginas de Confluence | lippia-neo-fetch-jira-user-story (y lippia-neo-read-user-story cuando le pasás un link de Jira) |
Solo si las historias están en Jira · guía |
azure-devops |
@tiberriver256/mcp-server-azure-devops |
Leer work items de Azure Boards | lippia-neo-fetch-azure-user-story (y lippia-neo-read-user-story con un link de Azure) |
Solo si las historias están en Azure DevOps · guía |
neo-docs |
neo-docs-mcp (se ejecuta con uvx) |
Consultar esta documentación mientras trabajás, con links a cada sección | Ninguna: lo usa el asistente para responder sobre NEO |
Opcional, recomendado · guía |
Mantené esos nombres (
playwright,jira,azure-devops) en cualquier cliente. Son los que usa la plantilla deNEOy los que generalippia-neo-bootstrap-stack, así que te conviene no cambiarlos para que la configuración sea igual en todas las herramientas.
Qué tiene que estar instalado en la computadora
| Servidor | Requisito | Cómo verificarlo |
|---|---|---|
playwright |
Node.js (trae npx) y el navegador del MCP |
node -v · npx @playwright/mcp install-browser chrome-for-testing |
jira |
uv (trae uvx), el ejecutor de paquetes de Python |
uvx --version (si no está: docs.astral.sh/uv) |
azure-devops |
Node.js (trae npx) |
node -v |
3. La configuración de referencia
Todos los clientes necesitan los mismos datos. Solo cambia el archivo donde se escriben y el formato. Esta es la configuración de referencia de NEO (la plantilla .mcp.json.template que usa lippia-neo-bootstrap-stack):
{
"mcpServers": {
"playwright": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@playwright/mcp@latest", "--browser", "chromium"],
"env": {}
},
"jira": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-atlassian"],
"env": {
"JIRA_URL": "https://tu-sitio.atlassian.net/",
"JIRA_USERNAME": "tu.email@empresa.com",
"JIRA_API_TOKEN": "<API token de Atlassian, NO tu contraseña>",
"CONFLUENCE_URL": "https://tu-sitio.atlassian.net/wiki",
"CONFLUENCE_USERNAME": "tu.email@empresa.com",
"CONFLUENCE_API_TOKEN": "<API token de Atlassian>",
"READ_ONLY_MODE": "true"
}
},
"azure-devops": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@tiberriver256/mcp-server-azure-devops"],
"env": {
"AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/tu-org",
"AZURE_DEVOPS_AUTH_METHOD": "pat",
"AZURE_DEVOPS_PAT": "<Personal Access Token, scope Work Items → Read>",
"AZURE_DEVOPS_DEFAULT_PROJECT": "<opcional>"
}
}
}
}
Cargá solo los servidores que necesites. Si tus historias viven como archivos .md en el repositorio, alcanza con playwright.
Si usás Jira o Azure DevOps, mantené siempre este
.mcp.jsonen la raíz del proyecto, aunque tu asistente use otro archivo de configuración (Copilot, Codex, Cursor…). Las skills deNEOleen de ahíJIRA_URL/AZURE_DEVOPS_ORG_URLpara validar los links que les pasás, y sin ese dato se detienen. Detalle en Jira y Azure DevOps.
Qué significa cada dato
| Dato | Qué es | Dónde se consigue |
|---|---|---|
JIRA_URL |
Tu sitio de Jira Cloud | La URL con la que entrás a Jira (https://<sitio>.atlassian.net/) |
JIRA_USERNAME |
Tu email de Atlassian | — |
JIRA_API_TOKEN |
Un token de API (no tu contraseña) | id.atlassian.com/manage-profile/security/api-tokens |
CONFLUENCE_* |
Lo mismo para Confluence (las skills leen las páginas enlazadas a la historia) | Mismo sitio y mismo tipo de token |
READ_ONLY_MODE |
Que el servidor no pueda modificar nada en Jira | Dejalo en "true": NEO solo lee |
AZURE_DEVOPS_ORG_URL |
La URL de tu organización | https://dev.azure.com/<organización> |
AZURE_DEVOPS_AUTH_METHOD |
Método de autenticación | Poné "pat" explícitamente: si no lo ponés, el servidor usa otro método por defecto (azure-identity) |
AZURE_DEVOPS_PAT |
Personal Access Token | Azure DevOps → User settings → Personal access tokens, con permiso Work Items → Read |
AZURE_DEVOPS_DEFAULT_PROJECT |
Proyecto por defecto | Opcional |
4. La forma más rápida: dejar que lippia-neo-bootstrap-stack lo haga
Si trabajás con Claude Code, no hace falta escribir nada a mano. Cuando ejecutás lippia-neo-bootstrap-stack y elegís que las historias vienen de Jira o Azure DevOps, la skill:
- Crea
.mcp.jsonen la raíz del proyecto a partir de la plantilla, si todavía no existe. - Verifica que
.mcp.jsonesté en.gitignore. - Te pide los datos de conexión y completa solo las claves que faltan o tienen un valor de ejemplo, sin pisar valores reales.
- Nunca muestra el token en pantalla.
- Te avisa que reinicies el asistente, porque los servidores MCP se cargan al arrancar.
Para otros clientes (Copilot, Codex, Claude Desktop, ChatGPT), tomá los datos de ese
.mcp.jsony pasalos al formato de tu cliente, siguiendo su guía.
5. Seguridad: los tokens nunca van a git
.mcp.jsonlleva los valores literales (tokens incluidos) y por eso está en.gitignore. Lo único que se versiona es.mcp.json.template, con valores de ejemplo.- Si en tu repositorio
.mcp.jsonllegó a quedar versionado, sacalo del índice:git rm --cached .mcp.json. - En clientes que lo permiten (VS Code con
inputs, Codex conenv_vars, Claude Code con${VARIABLE}), podés evitar escribir el token en el archivo y pedirlo o tomarlo del entorno. Está en cada guía. - Usá tokens de solo lectura siempre que se pueda:
READ_ONLY_MODE: trueen Jira y permiso Work Items → Read en Azure DevOps.
6. Verificar que quedó bien
Sin importar el cliente:
- Reiniciá el asistente (o recargá la ventana) después de cambiar la configuración.
- Abrí la lista de servidores MCP del cliente (
/mcp, MCP: List Servers, Connectors… según la guía) y confirmá que cada servidor figura como conectado. - Hacé una prueba simple:
Usando el MCP de Playwright, abrí https://techstore-staging.com y decime el título de la página.
Traé la historia TECH-123 de Jira y mostrame sus criterios de aceptación.
Si alguno falla, mirá los problemas comunes de abajo y, para Playwright, la guía Configuración del MCP de Playwright.
7. Qué cliente soporta qué
| Cliente | Servidores locales (lo que usa NEO) |
Archivo de configuración | Guía |
|---|---|---|---|
| Claude Code (VS Code / CLI / pestaña Code de la app de escritorio) | ✅ | .mcp.json (proyecto) o ~/.claude.json (usuario) |
IDE · Terminal |
| GitHub Copilot en VS Code | ✅ | .vscode/mcp.json |
IDE |
| GitHub Copilot en JetBrains | ✅ | mcp.json (se abre desde el chat) |
IDE |
| GitHub Copilot en Visual Studio | ✅ | .mcp.json / .vs/mcp.json |
IDE |
| GitHub Copilot CLI | ✅ | ~/.copilot/mcp-config.json o .mcp.json |
Terminal |
| Codex (extensión, CLI y app de escritorio de ChatGPT) | ✅ | ~/.codex/config.toml |
IDE · Terminal · Escritorio |
| Cursor | ✅ | .cursor/mcp.json |
IDE |
| Claude Desktop (chat) | ✅ | claude_desktop_config.json |
Escritorio |
| GitHub Copilot app (escritorio) | ✅ | Toma la configuración del repositorio o de Copilot CLI | Escritorio |
| ChatGPT (chat y conectores) | ❌ Solo servidores remotos | — | Escritorio |
8. Problemas comunes (y qué hacer)
| Lo que ves | Por qué puede pasar | Qué hacer |
|---|---|---|
| El servidor no aparece en la lista | El cliente no se reinició después de cambiar la configuración, o el archivo está en otra ruta | Reiniciar y revisar la ruta en la guía de tu cliente |
Failed to connect / spawn npx ENOENT |
Node.js no está instalado o no está en el PATH | Instalar Node.js y reiniciar el cliente |
El servidor jira no arranca |
Falta uv / uvx |
Instalar uv (docs.astral.sh/uv) |
| Jira devuelve 401 | Se usó la contraseña en vez de un API token, o el email no coincide | Generar un token nuevo y revisar JIRA_USERNAME |
| Azure DevOps no autentica con el PAT | Falta AZURE_DEVOPS_AUTH_METHOD: "pat" |
Agregarlo |
| El servidor figura conectado, pero el asistente no usa las herramientas | El cliente no está en modo agente, o las herramientas están deshabilitadas | Ver la guía de tu cliente (Copilot y Visual Studio tienen un selector de herramientas) |
Browser "chrome-for-testing" is not installed |
@playwright/mcp@latest se actualizó y espera otra versión del navegador |
npx @playwright/mcp@latest install-browser chrome-for-testing |
| El mismo servidor aparece dos veces | Está configurado en dos lugares a la vez (usuario y proyecto) | Dejarlo en uno solo (ver Incidente 2) |