Receta · Intermedio · 15 min

MCP en Claude Code: conecta Playwright, GitHub y tu base de datos

Q: ¿Dónde pongo los tokens y contraseñas?

Nunca dentro de .mcp.json. Escribe ${VARIABLE} en el archivo y define la variable en tu terminal, o usa ámbito local, que guarda la configuración en tu ~/.claude.json y no se sube al repositorio.

Q: ¿Cuál es la diferencia entre local y user?

Los dos se guardan en ~/.claude.json y no se comparten. local se carga solo en el proyecto donde lo añadiste; user, en todos tus proyectos.

Q: ¿Playwright MCP sirve para aislar sitios peligrosos?

No. Su README aclara que no es una barrera de seguridad, y browser_run_code_unsafe ejecuta JavaScript arbitrario en el proceso del servidor. Úsalo para probar tus propias páginas.

Q: ¿Cómo apago un servidor sin borrarlo?

En /mcp, selecciónalo y desactívalo. Claude Code guarda esa elección por proyecto en ~/.claude.json.

Agrega servidores MCP a Claude Code con claude mcp add, compártelos en .mcp.json, controla permisos y contexto, y evita secretos e inyecciones.

Probado con Claude Code 2.1.316 · revisado 2026-10-31

El problema

Claude Code lee y edita tu código, pero no ve tu web en un navegador, ni los issues de GitHub, ni las tablas de tu base de datos. Terminas copiando y pegando capturas, errores y resultados de consultas. MCP (Model Context Protocol) conecta Claude Code a esas herramientas reales, pero si lo configuras sin cuidado llenas el contexto, filtras tokens en el repositorio o abres la puerta a instrucciones maliciosas.

La solución

1. Entiende los dos tipos de servidor

stdio (local): Claude Code lanza un programa en tu equipo. Todo lo que va después de -- es el comando del servidor, sin cambios.
http (remoto): te conectas a una URL. Es la opción recomendada para servicios en la nube. SSE está obsoleto; usa http si el servicio lo ofrece.

# stdio
claude mcp add [opciones] <nombre> -- <comando> [argumentos...]

# http
claude mcp add --transport http <nombre> <url>

2. Elige el ámbito (scope)

Ámbito	Dónde se carga	Se comparte	Dónde se guarda
`local` (por defecto)	Solo este proyecto	No	`~/.claude.json`
`project`	Solo este proyecto	Sí, con git	`.mcp.json` en la raíz
`user`	Todos tus proyectos	No	`~/.claude.json`

Regla práctica: project para lo que todo el equipo necesita (sin secretos dentro), local para lo que lleva tus credenciales o solo usas tú, user para herramientas personales que quieres en todos lados. Si un servidor existe en varios ámbitos, gana local, luego project, luego user.

3. Playwright MCP: que Claude pruebe tu web en un navegador

Servidor oficial de Microsoft (paquete @playwright/mcp, requiere Node.js 18 o superior). Desde la raíz de tu proyecto:

claude mcp add --scope project playwright -- npx @playwright/mcp@latest --headless --isolated

--headless abre el navegador sin ventana y --isolated guarda el perfil solo en memoria (no quedan cookies en disco). Esto crea o actualiza .mcp.json:

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--headless",
        "--isolated"
      ],
      "env": {}
    }
  }
}

Luego pídele cosas como: «Abre http://localhost:8000, toma un snapshot y dime qué errores salen en la consola». Usará herramientas como browser_navigate, browser_snapshot y browser_console_messages.

4. GitHub MCP en solo lectura, con el token fuera del repositorio

El servidor oficial de GitHub es remoto (https://api.githubcopilot.com/mcp/). Añadir /readonly al final de la URL deja solo las herramientas de lectura. En .mcp.json puedes usar ${VARIABLE}, así el token nunca queda escrito en el archivo:

claude mcp add-json --scope project github '{"type":"http","url":"https://api.githubcopilot.com/mcp/readonly","headers":{"Authorization":"Bearer ${GITHUB_PAT}"}}'

Cada persona exporta su propio token antes de abrir Claude Code (crea un fine-grained token con los permisos mínimos):

export GITHUB_PAT="tu_token_aqui"
claude

Ojo: la expansión ${VARIABLE} funciona en .mcp.json. Con --scope local o user el texto se guarda tal cual en ~/.claude.json y no se expande (lo comprobamos: el servidor responde «Authorization header is badly formatted»).

5. Una base de datos con DBHub (prueba primero con datos de ejemplo)

DBHub (@bytebase/dbhub) habla con PostgreSQL, MySQL, SQL Server, MariaDB, Oracle y SQLite. Para probar sin tocar tus datos, usa su base de ejemplo:

claude mcp add --scope local db -- npx -y @bytebase/dbhub@latest --transport stdio --demo

Para tu base real, pasa la cadena de conexión por la variable DSN y conéctate con un usuario de solo lectura de la base de datos. Usa ámbito local, porque la contraseña queda guardada en tu ~/.claude.json:

claude mcp add --scope local --env DSN="postgres://lector:clave@localhost:5432/miapp" --transport stdio db \
  -- npx -y @bytebase/dbhub@latest --transport stdio

DBHub también permite readonly = true y max_rows para la herramienta execute_sql en su archivo TOML (documentación), pero su propia documentación advierte que eso no sustituye a un usuario con pocos privilegios.

6. Revisa el estado y autentica con /mcp

Dentro de Claude Code escribe /mcp: verás cada servidor con su estado, podrás iniciar sesión OAuth en los remotos que lo piden y desactivar los que no estés usando sin borrarlos. Desde la terminal:

claude mcp list                 # todos los servidores y su salud
claude mcp get playwright       # detalle de uno
claude mcp remove playwright -s project

La primera vez que abras claude en un proyecto con .mcp.json, te pedirá aprobar esos servidores. Para volver a preguntar: claude mcp reset-project-choices.

7. Permisos: aprueba solo aquello en lo que confías

Las herramientas MCP se llaman mcp__<servidor>__<herramienta>. En .claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__playwright__browser_navigate",
      "mcp__playwright__browser_snapshot",
      "mcp__github__get_*"
    ],
    "deny": [
      "mcp__playwright__browser_run_code_unsafe"
    ]
  }
}

mcp__github__* cubre todas las herramientas del servidor github, y mcp__github__get_* solo las que empiezan por get_. Un comodín sin servidor, como "mcp__*", no aprueba nada en allow (sí sirve en deny para bloquear todo MCP).

8. Cuida el contexto

Por defecto Claude Code usa tool search: al empezar solo carga los nombres de las herramientas y las instrucciones de cada servidor, y trae la definición completa cuando la necesita. Aun así, cada servidor suma nombres, instrucciones y respuestas largas: Claude Code avisa cuando una herramienta MCP devuelve más de 10 000 tokens y corta en 25 000 por defecto (MAX_MCP_OUTPUT_TOKENS). Desactiva en /mcp lo que no uses en esta tarea y revisa el consumo con /context.

Compruébalo

Después del paso 3 (y del 4, sin exportar GITHUB_PAT), en la raíz del proyecto:

claude mcp list

Salida real con Claude Code 2.1.316 (recortada a nuestros servidores):

Checking MCP server health…

playwright: npx @playwright/mcp@latest --headless --isolated - ⏸ Pending approval (run `claude` to approve)
github: https://api.githubcopilot.com/mcp/readonly (HTTP) - ⏸ Pending approval (run `claude` to approve)
[Contains warnings] Project config (shared via .mcp.json)
 └ [Warning] [github] mcpServers.github: Missing environment variables: GITHUB_PAT

claude mcp get playwright

playwright:
  Scope: Project config (shared via .mcp.json)
  Status: ⏸ Pending approval (run `claude` to approve)
  Type: stdio
  Command: npx
  Args: @playwright/mcp@latest --headless --isolated
  Environment:

To remove this server, run: claude mcp remove playwright -s project

«Pending approval» es lo esperado: abre claude, aprueba los servidores del proyecto y luego /mcp debe mostrarlos conectados. La advertencia de GITHUB_PAT desaparece cuando exportas la variable.

Por qué funciona

Claude Code actúa como cliente MCP: arranca cada servidor stdio como un proceso hijo (o se conecta por HTTP), pide su lista de herramientas y se las ofrece a Claude con el prefijo mcp__<servidor>__. Cada llamada pasa por el mismo sistema de permisos que Bash o Edit. .mcp.json es un archivo normal del repositorio, por eso sirve para compartir la configuración y por eso nunca debe llevar secretos. Más detalles en la documentación oficial de MCP en Claude Code y en la de permisos.

Errores típicos

claude mcp add dice «Added» pero /mcp muestra error → el comando no valida credenciales → revisa el token o la URL y confirma en /mcp que aparece la marca de conectado.
Missing environment variables: GITHUB_PAT → no exportaste la variable en esa terminal → export GITHUB_PAT=... y vuelve a abrir claude.
«Authorization header is badly formatted» con --scope local → ${GITHUB_PAT} no se expande fuera de .mcp.json → usa --scope project con la variable, o pega el token solo en ámbito local.
El servidor con --env no arranca → el nombre quedó pegado a --env y se leyó como otro par CLAVE=valor → pon otra opción (por ejemplo --transport stdio) entre --env y el nombre.
La sesión va lenta o se queda sin contexto → demasiados servidores o respuestas gigantes → desactiva servidores en /mcp y pide resultados acotados (con LIMIT, un selector concreto, etc.).

Preguntas frecuentes

¿Es seguro conectar cualquier servidor MCP?

No. Instala solo servidores en los que confíes: un servidor stdio corre en tu equipo con tus permisos. Además, los que leen contenido externo (páginas web, issues, filas de una base) pueden traer inyección de instrucciones: texto que intenta que Claude haga algo que tú no pediste. Por eso conviene GitHub en solo lectura, usuarios de base de datos con pocos privilegios y revisar cada acción antes de aprobarla.

¿Dónde pongo los tokens y contraseñas?

Nunca dentro de .mcp.json. Escribe ${VARIABLE} en el archivo y define la variable en tu terminal, o usa ámbito local, que guarda la configuración en tu ~/.claude.json y no se sube al repositorio.

¿Cuál es la diferencia entre local y user?

Los dos se guardan en ~/.claude.json y no se comparten. local se carga solo en el proyecto donde lo añadiste; user, en todos tus proyectos.

¿Playwright MCP sirve para aislar sitios peligrosos?

No. Su README aclara que no es una barrera de seguridad, y browser_run_code_unsafe ejecuta JavaScript arbitrario en el proceso del servidor. Úsalo para probar tus propias páginas.

¿Cómo apago un servidor sin borrarlo?

En /mcp, selecciónalo y desactívalo. Claude Code guarda esa elección por proyecto en ~/.claude.json.

Todas las recetas