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 |
Y una guía para el framework de pruebas Katalon Studio, cuyo servidor MCP crea y ejecuta los tests dentro del proyecto de Katalon:
| Framework | Guía |
|---|---|
| Katalon Studio | Configurar el MCP de Katalon Studio |
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) |
playwright, jira, azure-devops, neo-docs |
| Remoto (HTTP) | El asistente se conecta a una URL | katalon-studio (lo publica Katalon Studio en tu computadora) y los conectores en la nube |
Importante: casi todos los servidores que usa
NEOson locales, así que solo funcionan en clientes que pueden lanzar servidores locales. Algunos, como el chat de ChatGPT, solo aceptan servidores remotos de la nube y no pueden conectarse a los deNEO, que dependen de tu computadora. 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-run-manual-testing, lippia-neo-reproduce-bug, lippia-neo-run-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-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-user-story (y lippia-neo-read-user-story con un link de Azure) |
Solo si las historias están en Azure DevOps · guía |
katalon-studio |
El MCP server integrado en Katalon Studio 11.6+ (HTTP) | Crear, ejecutar y reparar los tests (Groovy) dentro del proyecto de Katalon | lippia-neo-generate-test-suite y lippia-neo-run-and-heal, con el adapter katalon |
Solo si test_framework: katalon · 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,katalon-studio) 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 |
katalon-studio |
Katalon Studio 11.6+ abierto, con el proyecto de la suite abierto y el MCP server habilitado | Ver la guía de Katalon |
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": {}
},
"katalon-studio": {
"type": "http",
"url": "http://127.0.0.1:33699/mcp/stream",
"headers": {
"Authorization": "Bearer <token del MCP server de Katalon>"
}
},
"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 y tu framework no es Katalon, alcanza con playwright. El bloque katalon-studio solo se usa con test_framework: katalon; si el server de Katalon no pide token, quitá headers.
Versiones fijadas. La plantilla fija
@playwright/mcp@0.0.83ymcp-atlassian@0.23.1en lugar de@latest, para que una actualización del paquete no rompa la configuración sin aviso. Si cambiás de versión, hacelo igual en todos los clientes.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 |
url (Katalon) |
Dirección del MCP server de Katalon Studio | La muestra Katalon Studio en la configuración del MCP. No asumas host ni puerto |
headers.Authorization (Katalon) |
Token del MCP server, solo si lo pide | Katalon Studio, con el formato Bearer <token> |
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, o que el framework es Katalon, 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 (para Katalon: la URL del server y si pide token) 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.
Sesión guardada en el MCP de Playwright
Si la app exige login (stack.auth distinto de none), lippia-neo-bootstrap-stack también deja el server playwright listo para explorar ya logueado, sin pedirte las credenciales:
"args": ["-y", "@playwright/mcp@0.0.83", "--browser", "chromium",
"--isolated",
"--storage-state=.auth/auth-state.json",
"--init-script=.auth/auth-state.session-storage.js"]
| Argumento | Para qué |
|---|---|
--isolated |
Obligatorio: Playwright MCP solo carga un storage-state en modo aislado |
--storage-state=<ruta> |
Carga las cookies y el localStorage de la sesión guardada (paths.auth_state_file) |
--init-script=<ruta> |
Reinyecta el sessionStorage, que no viaja en el storage-state |
- La sesión se captura una vez, a mano, con la skill
lippia-neo-setup-authenticated-session: abre un navegador visible, hacés el login vos (también con SSO, 2FA o passkey) y la skill guarda los archivos. No automatiza ni observa ese login. - Esos dos archivos tienen que existir, o el servidor falla al abrir el navegador. Por eso
lippia-neo-bootstrap-stacklos crea vacíos pero válidos si todavía no capturaste la sesión. - La carpeta de la sesión (
.auth/por defecto) va en.gitignore: tiene tokens válidos. - Es la misma sesión que usan Playwright, Cypress, Lippia y Katalon.
- Si la sesión vence (
session.on_expiredenqa-stack.yaml), la ejecución corta pidiendo recapturarla, o espera a que te loguees a mano si elegisterefresh.
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é
La tabla vale para los servidores locales.
katalon-studioes remoto (HTTP): funciona en los clientes de código (Claude Code, Copilot, Codex, Cursor). Ver la guía de Katalon.
| 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 |
La versión de @playwright/mcp espera otra versión del navegador |
npx @playwright/mcp@latest install-browser chrome-for-testing |
katalon-studio figura Failed o timeout |
Katalon Studio no está abierto, o el handshake (~30 s) supera el tiempo de espera | Abrir Katalon Studio y definir MCP_TIMEOUT=60000 (ver Katalon) |
| Playwright MCP falla al abrir el navegador con sesión guardada | Falta el archivo de --storage-state o --init-script, o está vacío (0 bytes) |
Recapturar la sesión con lippia-neo-setup-authenticated-session o volver a ejecutar lippia-neo-bootstrap-stack |
| El mismo servidor aparece dos veces | Está configurado en dos lugares a la vez (usuario y proyecto) | Dejarlo en uno solo (ver Incidente 2) |