Saltar a contenido

Configurar MCP en el IDE

Esta guía muestra cómo cargar los servidores MCP de NEO (playwright, jira, azure-devops) en cada editor de código. Antes de empezar, revisá en Configurar los MCP qué servidores necesitás y qué datos van en cada uno.

En todos los ejemplos, <token> y los demás valores entre < > son datos tuyos. Nunca subas a git un archivo que tenga tokens reales.

Editor + asistente Archivo Clave raíz
Claude Code en VS Code .mcp.json (raíz del proyecto) mcpServers
GitHub Copilot en VS Code .vscode/mcp.json servers
GitHub Copilot en JetBrains mcp.json (se abre desde el chat) servers
GitHub Copilot en Visual Studio .mcp.json / .vs/mcp.json servers
Codex en VS Code ~/.codex/config.toml [mcp_servers.<nombre>]
Cursor .cursor/mcp.json mcpServers

Fijate en la clave raíz: Claude Code y Cursor usan mcpServers, pero Copilot usa servers. Si copiás el .mcp.json de NEO a un archivo de Copilot sin cambiar esa clave, el servidor no aparece.


Claude Code en VS Code

Es el caso más simple, porque NEO ya usa el formato de Claude Code.

Opción 1 — Archivo del proyecto (recomendada)

  1. En la raíz del repositorio de pruebas, creá .mcp.json (o copiá .mcp.json.template a .mcp.json) con la configuración de referencia.
  2. Completá los valores reales de los servidores que uses.
  3. Verificá que .mcp.json esté en .gitignore.
  4. Recargá VS Code: Ctrl+Shift+P → Developer: Reload Window.
  5. La primera vez, Claude Code te pide aprobar los servidores del proyecto. Aceptalos.

También podés dejar que lippia-neo-bootstrap-stack cree y complete .mcp.json por vos (ver La forma más rápida).

Opción 2 — Desde el chat

En el panel de Claude Code, escribí /mcp. Desde ahí podés agregar, quitar, habilitar y autenticar servidores. Usa la misma configuración que la CLI (ver Claude Code CLI).

Dónde puede quedar guardado

Alcance Archivo Cuándo usarlo
Proyecto .mcp.json en la raíz del repositorio La opción de NEO: la configuración viaja con el proyecto (fuera de git si tiene tokens)
Local (por defecto al agregar con claude mcp add) ~/.claude.json, asociado a la carpeta del proyecto Solo para vos y solo en ese proyecto
Usuario ~/.claude.json Para tenerlo en todos tus proyectos, por ejemplo el de Playwright

No cargues el mismo servidor en dos alcances. Si playwright está a la vez en el usuario y en el proyecto, aparece duplicado y puede fallar (ver Incidente 2).

Sin escribir el token en el archivo

Claude Code acepta variables de entorno dentro de .mcp.json, con la forma ${VARIABLE} o ${VARIABLE:-valor_por_defecto}:

"env": {
  "JIRA_URL": "https://tu-sitio.atlassian.net/",
  "JIRA_USERNAME": "tu.email@empresa.com",
  "JIRA_API_TOKEN": "${JIRA_API_TOKEN}"
}

Así el token vive en una variable de entorno de tu sistema y no en el archivo. Esa variable tiene que estar definida antes de abrir VS Code.

⚠️ Tres cuidados si usás esta opción:

  • ${VARIABLE} se reemplaza solo por una variable del sistema operativo, nunca por otra clave del mismo bloque. "CONFLUENCE_URL": "${JIRA_URL}wiki" no funciona si JIRA_URL solo está definida en el bloque.
  • Usala solo para los tokens. JIRA_URL y AZURE_DEVOPS_ORG_URL tienen que quedar escritas completas, porque las skills de NEO las leen directamente del archivo para validar los links (ver Jira y Azure DevOps).
  • La forma estándar de NEO (y la que usa lippia-neo-bootstrap-stack) es escribir los valores directamente en .mcp.json, que está en .gitignore. Esta opción es una alternativa, no un requisito.

Verificar

Escribí /mcp en el chat. Cada servidor tiene que figurar como Connected. Otros estados posibles:

Estado Qué significa
Pending approval Falta aprobar el servidor del proyecto
Failed No pudo arrancar. Revisá el comando o que Node.js / uv estén instalados
Needs authentication El servidor pide login (no aplica a los de NEO, que usan token)

GitHub Copilot en VS Code

Copilot usa los servidores MCP en el modo agente del chat.

Opción 1 — Archivo del workspace

Creá .vscode/mcp.json en el proyecto. La clave raíz es servers, y los secretos se piden con inputs, así no quedan escritos en el archivo:

{
  "inputs": [
    { "id": "jira-token",  "type": "promptString", "description": "API token de Atlassian", "password": true },
    { "id": "azure-pat",   "type": "promptString", "description": "PAT de Azure DevOps",    "password": true }
  ],
  "servers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest", "--browser", "chromium"]
    },
    "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": "${input:jira-token}",
        "CONFLUENCE_URL": "https://tu-sitio.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "tu.email@empresa.com",
        "CONFLUENCE_API_TOKEN": "${input:jira-token}",
        "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": "${input:azure-pat}"
      }
    }
  }
}

La primera vez que arranca el servidor, VS Code te pide el token y lo guarda de forma segura. Con inputs, .vscode/mcp.json no tiene secretos y se puede versionar.

Según la documentación de VS Code, también detecta un .mcp.json en la raíz del proyecto (con clave mcpServers), como el que genera NEO. Si ya lo tenés, probá primero con MCP: List Servers: puede que no haga falta crear .vscode/mcp.json.

Opción 2 — Desde la paleta de comandos

Ctrl+Shift+P → MCP: Add Server → elegí Command (stdio) y completá el comando (npx), los argumentos y el nombre. Podés guardarlo en el workspace o en tu configuración de usuario (MCP: Open User Configuration).

Verificar

  1. Ctrl+Shift+P → MCP: List Servers: cada servidor tiene que estar en ejecución. Desde ahí podés iniciarlo, reiniciarlo o ver su log.
  2. La primera vez (y cada vez que cambia la configuración), VS Code pregunta si confiás en el servidor. Aceptá.
  3. En el chat de Copilot, pasá a modo Agent y abrí Configure Tools (el ícono de herramientas): tienen que aparecer las herramientas de playwright (browser_*) y de los demás servidores.

GitHub Copilot en JetBrains (IntelliJ, WebStorm…)

  1. Abrí el chat de Copilot (ícono de Copilot → Open Chat) y pasá a modo Agent.
  2. Hacé clic en el ícono de herramientas (Configure your MCP server) → Add MCP Tools. Se abre el archivo mcp.json.
  3. Pegá los servidores con la clave raíz servers:
{
  "servers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest", "--browser", "chromium"]
    },
    "jira": {
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "JIRA_URL": "https://tu-sitio.atlassian.net/",
        "JIRA_USERNAME": "tu.email@empresa.com",
        "JIRA_API_TOKEN": "<token>",
        "READ_ONLY_MODE": "true"
      }
    }
  }
}
  1. Guardá y volvé al chat: las herramientas aparecen en el selector del modo agente.

En cuentas Copilot Business o Enterprise, la organización tiene que tener habilitada la política "MCP servers in Copilot". Si no ves la opción, pedíselo al administrador de GitHub de tu organización.


GitHub Copilot en Visual Studio

Requiere Visual Studio 2022 17.14 o superior (o Visual Studio 2026).

  1. Creá el archivo en una de estas ubicaciones (Visual Studio las lee en este orden):
Archivo Alcance
%USERPROFILE%\.mcp.json Todas tus soluciones
<carpeta de la solución>\.vs\mcp.json Esa solución, solo en tu máquina
<carpeta de la solución>\.mcp.json Esa solución, compartible
<carpeta de la solución>\.vscode\mcp.json Compatible con VS Code
  1. Usá la clave raíz servers, con el mismo contenido que en JetBrains.
  2. También podés hacerlo por interfaz: en el chat de Copilot, modo Agent → Tools → + → Add custom MCP server.
  3. Al guardar el archivo, el agente se reinicia solo.
  4. Habilitá las herramientas a mano: en Visual Studio vienen deshabilitadas por defecto. Activalas desde el selector Tools del chat.

Codex en VS Code

La extensión de Codex comparte la configuración con Codex CLI y con la app de escritorio de ChatGPT: todo vive en ~/.codex/config.toml (en Windows, %USERPROFILE%\.codex\config.toml). También podés usar .codex/config.toml dentro del proyecto, solo en proyectos marcados como de confianza.

El formato es TOML, no JSON:

[mcp_servers.playwright]
command = "npx"
args = ["-y", "@playwright/mcp@latest", "--browser", "chromium"]

[mcp_servers.jira]
command = "uvx"
args = ["mcp-atlassian"]
env_vars = ["JIRA_API_TOKEN", "CONFLUENCE_API_TOKEN"]   # toma estos valores de tu entorno

[mcp_servers.jira.env]
JIRA_URL = "https://tu-sitio.atlassian.net/"
JIRA_USERNAME = "tu.email@empresa.com"
CONFLUENCE_URL = "https://tu-sitio.atlassian.net/wiki"
CONFLUENCE_USERNAME = "tu.email@empresa.com"
READ_ONLY_MODE = "true"

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

[mcp_servers.azure-devops.env]
AZURE_DEVOPS_ORG_URL = "https://dev.azure.com/tu-org"
AZURE_DEVOPS_AUTH_METHOD = "pat"

Con env_vars, el token no queda escrito en el archivo: Codex lo toma de las variables de entorno de tu sistema. Si preferís, podés ponerlo directamente en la sección .env.

También lo podés agregar por comando (ver Codex CLI). Para verificar, escribí /mcp en el chat de Codex.


Cursor

  1. Creá .cursor/mcp.json en el proyecto (o ~/.cursor/mcp.json para todos tus proyectos).
  2. Usá la clave raíz mcpServers: el mismo formato que el .mcp.json de NEO, así que podés copiar la configuración de referencia tal cual.
  3. Para no escribir tokens, Cursor acepta ${env:VARIABLE} dentro de env, o un envFile que apunte a un archivo de variables.
  4. Reiniciá Cursor después de editar el archivo.
  5. Para ver errores: panel Output → MCP Logs.

Katalon Studio (servidor remoto)

Si tu framework es Katalon, sumá el servidor katalon-studio. A diferencia de los demás, es remoto (HTTP): no lleva command ni args, lleva type: http y la url que muestra Katalon Studio. La guía completa, con el paso a paso y los problemas comunes, está en Configurar el MCP de Katalon Studio.

Editor + asistente Cómo se carga
Claude Code, Cursor "katalon-studio": { "type": "http", "url": "<URL>", "headers": { "Authorization": "Bearer <token>" } } bajo mcpServers
GitHub Copilot (VS Code, JetBrains, Visual Studio) El mismo bloque bajo servers (en VS Code, con inputs para el token)
Codex [mcp_servers.katalon-studio] con url = "<URL>" y, si pide token, bearer_token_env_var = "<VARIABLE>"

Katalon Studio tiene que estar abierto con el proyecto de la suite, y el primer handshake tarda ~30 segundos: definí MCP_TIMEOUT=60000 antes de abrir el IDE.


Problemas comunes en el IDE

Lo que ves Por qué puede pasar Qué hacer
Copilot no muestra el servidor Se usó la clave mcpServers en vez de servers Cambiar la clave raíz a servers
El servidor está, pero el chat no usa sus herramientas El chat no está en modo agente, o las herramientas están deshabilitadas Pasar a modo Agent y activarlas en Configure Tools / Tools
En Windows, npx no arranca desde el IDE El IDE no encuentra npx en el PATH Reiniciar el IDE después de instalar Node.js. Si sigue fallando, usar "command": "cmd" y "args": ["/c", "npx", "-y", "@playwright/mcp@latest"]
Claude Code no toma los cambios de .mcp.json Los servidores se leen al arrancar Developer: Reload Window
Claude Code muestra el servidor como Pending approval Los servidores del proyecto se aprueban la primera vez Aprobarlo desde /mcp
El token quedó en un archivo versionado Se escribió el valor literal en un archivo que no está en .gitignore Sacarlo del repositorio, revocar el token y usar inputs / ${VARIABLE} / env_vars