Instalar y configurar un MCP

El archivo de configuración MCP

Los MCP se configuran en un archivo JSON que le indica a Claude Code qué servidores MCP lanzar y cómo conectarlos. Existen dos niveles de configuración: global, para tus herramientas personales, y por proyecto, para el stack técnico de cada repositorio.

Estructura del archivo .mcp.json

{
  "mcpServers": {
    "nombre-del-mcp": {
      "command": "npx",
      "args": ["-y", "@package/mcp-server"],
      "env": {
        "API_KEY": "tu-clave-aqui"
      }
    }
  }
}

Cada entrada en mcpServers define un MCP con:

• command: el comando para lanzar el servidor MCP (npx, uvx, docker, o una ruta a un binario)
• args: los argumentos que se pasan al comando (el paquete npm, las opciones de configuración)
• env (opcional): las variables de entorno necesarias (tokens, claves API)

Instalación de un MCP: los tres métodos

# Sintaxis general
claude mcp add <nombre> -- <comando> <args...>

# Ejemplo: añadir Context7
claude mcp add context7 -- npx -y @upstash/context7-mcp

# Ejemplo: añadir GitHub con un token
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# Ejemplo: añadir un MCP con variables de entorno
claude mcp add slack -e SLACK_BOT_TOKEN=xoxb-tu-token -- npx -y @modelcontextprotocol/server-slack

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_tu_token"
      }
    }
  }
}

{
  "mcpServers": {
    "postgres": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "DATABASE_URL",
        "mcp/postgres"
      ],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@host:5432/dbname"
      }
    }
  }
}

Configuración dentro de Claude Code

Comprobar los MCP instalados

Después de añadir un MCP, reinicia Claude Code y verifica que se haya conectado correctamente.

# Listar todos los MCP configurados
claude mcp list

# Resultado esperado:
# context7: connected
#   Tools: query-docs, resolve-library-id
# github: connected
#   Tools: list_issues, create_pull_request, search_code, ...

# Eliminar un MCP
claude mcp remove <nombre>

# Ver los detalles de un MCP
claude mcp get <nombre>

Alcance de la configuración

# Añadir un MCP a nivel de proyecto (por defecto)
claude mcp add context7 -- npx -y @upstash/context7-mcp

# Añadir un MCP a nivel global (todos los proyectos)
claude mcp add context7 --scope global -- npx -y @upstash/context7-mcp

# Añadir un MCP a nivel de usuario (para este usuario)
claude mcp add context7 --scope user -- npx -y @upstash/context7-mcp

Depuración y solución de problemas

El MCP no se conecta

# Comprobar que npx está instalado
which npx

# Comprobar que el paquete MCP existe
npx -y @upstash/context7-mcp --help

# Si usas uvx (Python)
which uvx

# Ver los logs de conexión MCP
claude mcp logs

# Ver los logs de un MCP concreto
claude mcp logs context7

# Validar tu archivo .mcp.json
cat .mcp.json | python3 -m json.tool

# O con Node.js
node -e "console.log(JSON.parse(require('fs').readFileSync('.mcp.json','utf8')))"

# Lanzar el servidor MCP directamente
npx -y @upstash/context7-mcp

# Si el servidor arranca y queda a la espera de entradas stdin, va bien
# Ctrl+C para salir

Errores habituales y soluciones

Ejemplo completo: configurar tres MCP

Aquí tienes un ejemplo realista de configuración con tres MCP para un proyecto de desarrollo web.

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

Con esta configuración, puedes pedirle a Claude Code:

"Consulta la documentación de Next.js 14, crea una página de error 404 siguiendo las buenas prácticas, pruébala en el navegador y crea una pull request."

Claude Code encadenará automáticamente Context7 (documentación), la edición de archivos (creación de la página), Playwright (prueba visual) y GitHub (pull request).

Próximos pasos

¿Ya tienes tu primer MCP configurado? Descubre ahora los mejores MCP por categoría.

• Entender los MCP: cómo funciona el protocolo MCP explicado
• Mejores MCP de productividad: Gmail, Slack, Calendar, Figma, Lighthouse
• Mejores MCP de desarrollo: Context7, GitHub, Sentry, bases de datos
• Mejores MCP de diseño y UI: Playwright, Chrome DevTools, 21st.dev Magic