Tu primera conexión MCP: configurar Claude Desktop

En la lección 1 entendimos qué es MCP y por qué existe. Ahora toca configurarlo.

Lo que necesitas

Antes de empezar, confirma que tienes:

Claude Desktop — última versión instalada
Node.js (v18+) — necesario para ejecutar servidores MCP (verifica con node -v)
Un editor de texto — VS Code, Cursor o el que prefieras

El archivo de configuración

La configuración MCP de Claude Desktop vive en un archivo JSON:

Sistema	Ruta
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

Si el archivo no existe, créalo.

Conectar tu primer servidor: filesystem

El servidor más simple es el de sistema de archivos. Le da a la IA acceso de lectura y escritura a una carpeta de tu disco.

Paso 1: Abre el archivo de configuración

# macOS
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Paso 2: Escribe esta configuración

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/tu-usuario/Documents"
      ],
      "env": {}
    }
  }
}

Importante: La última línea de args es la carpeta a la que le das acceso a la IA. Nunca pongas tu directorio home entero ni la raíz del disco. Solo la carpeta de trabajo que necesites.

Paso 3: Reinicia Claude Desktop completamente

En macOS: clic derecho en el ícono del Dock → “Salir”. Verifica que no quede como proceso en la barra de menú. Vuelve a abrirlo.

Paso 4: Verifica la conexión

En la ventana de chat de Claude Desktop, busca el ícono de herramientas (🔨) junto al campo de texto. Si aparece, la conexión fue exitosa. Haz clic para ver las herramientas disponibles.

✅ Quick Check: ¿Por qué es peligroso poner / como ruta en el servidor filesystem? (Porque la IA tendría acceso a todo tu disco — archivos del sistema, claves SSH, documentos personales. Solo expón la carpeta que necesitas.)

Conectar múltiples servidores

Agregar más servidores es tan simple como añadir entradas al objeto mcpServers:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/tu-usuario/proyectos"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Cada servidor tiene un nombre único (filesystem, github). Claude Desktop los inicia todos al arrancar.

Variables de entorno para API keys

Escribir claves API directamente en el archivo de configuración es inaceptable:

// ❌ Nunca hagas esto
"env": {
  "GITHUB_TOKEN": "ghp_ABC123tokenreal"
}

// ✅ Usa variables de entorno
"env": {
  "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}

Configura la variable en tu terminal:

# Añade a ~/.zshrc o ~/.bashrc
export GITHUB_TOKEN="ghp_ABC123..."

Si usas un archivo .env, asegúrate de que esté en .gitignore.

Solución de errores comunes

Problema	Causa	Solución
No aparece el ícono de herramientas	Claude Desktop no se reinició bien	Cierra completamente (incluyendo procesos en segundo plano) y reabre
“Server disconnected”	Node.js no instalado	Ejecuta `node -v` — si no aparece versión, instálalo
Error de parsing JSON	Sintaxis incorrecta	Revisa comas extras o faltantes, llaves sin cerrar
Un servidor específico falla	Variable de entorno vacía	Verifica con `echo $GITHUB_TOKEN`
npx da timeout	Problema de red	Ejecuta `npx -y @modelcontextprotocol/server-filesystem --help` manualmente

✅ Quick Check: Si después de editar la configuración no ves cambios en Claude Desktop, ¿qué es lo primero que debes verificar? (Que cerraste la aplicación completamente, incluyendo procesos en segundo plano. En macOS revisa la barra de menú.)

Puntos clave

El archivo de configuración es claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/)
Se agregan servidores dentro del objeto mcpServers — cada uno con nombre único
Las API keys van en variables de entorno, nunca en texto plano
El servidor filesystem solo debe exponer la carpeta de trabajo (principio de mínimo privilegio)
Después de cualquier cambio, reinicio completo de Claude Desktop

Siguiente lección

Ya tienes Claude Desktop conectado a tu primer servidor MCP. Pero con 8,600+ servidores disponibles, ¿cuáles vale la pena instalar? En la lección 3 te muestro los 5 servidores esenciales que cubren desarrollo, búsqueda y comunicación.