Saltar a contenido

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 NEO son 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 de NEO, 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 de NEO y los que genera lippia-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.83 y mcp-atlassian@0.23.1 en 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.json en la raíz del proyecto, aunque tu asistente use otro archivo de configuración (Copilot, Codex, Cursor…). Las skills de NEO leen de ahí JIRA_URL / AZURE_DEVOPS_ORG_URL para 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:

  1. Crea .mcp.json en la raíz del proyecto a partir de la plantilla, si todavía no existe.
  2. Verifica que .mcp.json esté en .gitignore.
  3. 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.
  4. Nunca muestra el token en pantalla.
  5. 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.json y 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-stack los 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_expired en qa-stack.yaml), la ejecución corta pidiendo recapturarla, o espera a que te loguees a mano si elegiste refresh.

5. Seguridad: los tokens nunca van a git

  • .mcp.json lleva 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.json llegó a quedar versionado, sacalo del índice: git rm --cached .mcp.json.
  • En clientes que lo permiten (VS Code con inputs, Codex con env_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: true en Jira y permiso Work Items → Read en Azure DevOps.

6. Verificar que quedó bien

Sin importar el cliente:

  1. Reiniciá el asistente (o recargá la ventana) después de cambiar la configuración.
  2. 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.
  3. 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-studio es 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)