Guía de configuración del MCP de Playwright

Esta guía resuelve los 4 incidentes de conexión que aparecieron repetidas veces al configurar el servidor MCP de Playwright para los skills de QA (qa-exploratory-test, etc.). Está pensada para que, si te encontrás con alguno de estos errores, sepas exactamente qué revisar y qué comando correr — sin tener que investigar de nuevo.

Requisitos previos

Claude Code CLI instalado y funcionando — todos los comandos de esta guía (claude mcp ...) se corren desde ahí.
Node.js con npx disponible en el PATH — la config final levanta el servidor con npx @playwright/mcp@latest, así que npx tiene que poder resolver y descargar ese paquete.
Navegadores de Playwright instalados — si es la primera vez que usás Playwright en esta máquina, instalá los navegadores antes de configurar el MCP (esto instala Chromium, Firefox y WebKit): npx playwright install

Cómo verificar el estado del MCP (siempre el primer paso)

claude mcp list

Buscá la línea de playwright. Puede darte 3 resultados:

✓ Connected → el server está bien registrado (pero ver el Incidente 3 — "Connected" no siempre significa que las tools ya estén disponibles).
✘ Failed to connect → ver Incidente 1.
Aparece dos veces (en scopes distintos) → ver Incidente 2.

Si claude mcp list muestra ✓ Connected pero las herramientas browser_* no aparecen cuando las buscás (ToolSearch en Claude Code, o simplemente no se pueden invocar), pasá directo al Incidente 3.

Incidente 1 — "Failed to connect" por nombre de paquete incorrecto

Configuración inicial (rota):

{
  "mcpServers": {
    "playwright": {
      "command": "mcp-server-playwright",
      "args": ["--browser", "chromium"]
    }
  }
}

Qué pasa:

claude mcp list
playwright: mcp-server-playwright --browser chromium - ✘ Failed to connect

mcp-server-playwright no es un paquete npm real — no existe con ese nombre. Por eso el proceso nunca arranca.

Pasos a seguir: 1. Eliminá la entrada rota: claude mcp remove playwright 2. Volvé a agregarla con el paquete oficial (@playwright/mcp): claude mcp add playwright -- npx @playwright/mcp@latest --browser chromium --isolated (el flag --isolated es para evitar el Incidente 4 — ver más abajo). 3. Verificá: claude mcp list

Configuración final (correcta):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--browser", "chromium", "--isolated"]
    }
  }
}

Resultado esperado: playwright: npx @playwright/mcp@latest --browser chromium --isolated - ✓ Connected.

Incidente 2 — El servidor está duplicado en dos scopes distintos

Configuración inicial (rota): playwright definido a la vez en scope project (.mcp.json del repo) y en scope local (config personal), cada uno con un comando distinto (por ejemplo uno con el paquete roto del Incidente 1 y otro con el paquete correcto).

Qué pasa:

[Warning] Server "playwright" is defined in multiple scopes with different
endpoints: project (mcp-server-playwright --browser chromium),
local (npx @playwright/mcp@latest). OAuth tokens are stored per endpoint...

Aunque uno de los dos esté bien, el conflicto de scopes hace que las tools browser_* no se registren nunca en la sesión.

Pasos a seguir: 1. Confirmá en qué scopes está definido: claude mcp get playwright 2. Dejá una sola definición. Sacá la del scope que no vas a usar (lo habitual es sacar la de project y quedarte con la de local, para no forzar la config a todo el equipo vía el repo): claude mcp remove playwright -s project 3. Reiniciá VS Code por completo (cerrar y volver a abrir la ventana, no solo el chat) para que la sesión levante limpia.

Configuración final: una sola entrada de playwright, en un solo scope, con el comando correcto del Incidente 1. Verificá con claude mcp list que aparece una sola vez y sin warnings.

Incidente 3 — Las tools no aparecen aunque el server esté "Connected"

Configuración inicial: .mcp.json correcto, claude mcp list en ✓ Connected, pero al buscar las tools (browser_navigate, browser_click, etc.) no aparecen ninguna.

Qué pasa: la sesión de VS Code/Claude Code se abrió antes de que el servidor de Playwright quedara disponible (por ejemplo, lo configuraste o arreglaste con la sesión ya abierta). Las tools de un MCP nuevo no se cargan en caliente dentro de una sesión que ya estaba corriendo.

Pasos a seguir: 1. Cerrá todo VS Code (no solo la pestaña/ventana de chat). 2. Volvé a abrirlo. 3. Empezá una sesión nueva de Claude Code y volvé a intentar.

Configuración final: no cambia nada en el archivo de config — el fix es puramente "reiniciar sesión después de tocar la config del MCP". Regla general: cada vez que agregás, sacás o modificás un servidor MCP, reiniciá VS Code antes de volver a usarlo.

Incidente 4 — "Browser is already in use"

Configuración inicial (rota):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--browser", "chromium"]
    }
  }
}

(sin el flag --isolated)

Qué pasa:

Error: Browser is already in use for
C:\Users\<user>\AppData\Local\ms-playwright-mcp\mcp-chrome-<hash>,
use --isolated to run multiple instances of the same browser

Pasa cuando dos sesiones de Claude Code (o una sesión vieja que quedó colgada) intentan controlar el mismo perfil de Chrome al mismo tiempo. Sin --isolated, todas las sesiones comparten un único perfil de navegador — la segunda que intenta usarlo choca con un lock.

Pasos a seguir: 1. Si tenés otra sesión de Claude Code abierta usando Playwright, cerrala (o esperá a que termine) — eso libera el lock al toque. 2. Para que esto no vuelva a pasar, agregá --isolated a los args del servidor: claude mcp remove playwright claude mcp add playwright -- npx @playwright/mcp@latest --browser chromium --isolated 3. Reiniciá VS Code (ver Incidente 3) y probá de nuevo.

Configuración final (correcta):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--browser", "chromium", "--isolated"]
    }
  }
}

Con --isolated, cada sesión levanta su propio perfil de navegador aislado y pueden correr varias en paralelo sin pisarse.

Configuración final recomendada (resuelve los 4 incidentes de una)

claude mcp add playwright -- npx @playwright/mcp@latest --browser chromium --isolated

Definida una sola vez, en un solo scope, con el paquete oficial @playwright/mcp y el flag --isolated. Después de configurarlo así:

Reiniciá VS Code por completo.
Verificá con claude mcp list → debe aparecer una sola vez como ✓ Connected.
Empezá una sesión nueva y confirmá que las tools browser_* están disponibles antes de correr qa-exploratory-test u otro skill que dependa del browser.