Domina el archivo de configuración que conecta Claude Desktop con los MCP Servers.
El archivo claude_desktop_config.json es el punto de conexión entre Claude Desktop y el mundo de los MCP Servers. Es un archivo JSON simple que enumera todos los servidores MCP a los que Claude puede acceder. Sin él, Claude Desktop no sabe que existen herramientas externas: funciona solo como un chat convencional.
O claude_desktop_config.json es un archivo de configuración en formato JSON que sirve como «catálogo» de MCP Servers disponibles para Claude Desktop. Cada entrada de este archivo describe un server: su nombre, el comando para iniciarlo y los argumentos necesarios. Cuando Claude Desktop se inicia, lee este archivo y intenta conectarse a cada server de la lista. Si el archivo no existe o está vacío, Claude no tendrá acceso a ninguna herramienta MCP y solo funcionará como asistente de chat, sin herramientas externas.
Piensa en el config.json como la "lista de contactos" de Claude Desktop. Así como tu teléfono solo puede llamar a números que están en la agenda, Claude Desktop solo puede usar tools de servers que estén en config.json. Agregar un server al archivo es como agregar un nuevo contacto: a partir de ese momento, Claude sabe que ese server existe y puede conectarse a él.
El archivo de configuración está en un directorio específico de cada sistema operativo. Es importante saber exactamente dónde está, porque editarás este archivo con frecuencia durante el curso. Si el archivo o el directorio aún no existen, tendrás que crearlos manualmente.
La ruta completa del archivo varía según el sistema operativo. Claude Desktop siempre busca el archivo en la misma ubicación y no es posible cambiarla. Tienes que colocar el archivo exactamente en el directorio esperado para que Claude lo encuentre.
~/Library/Application Support/Claude/claude_desktop_config.json
Abrir en la terminal: open ~/Library/Application\ Support/Claude/
%APPDATA%\Claude\claude_desktop_config.json
Abrir en el Explorador: explorer %APPDATA%\Claude
~/.config/Claude/claude_desktop_config.json
Abrir en la terminal: xdg-open ~/.config/Claude/
El archivo puede que no exista inicialmente. Si el directorio Claude existe, pero el archivo no, créalo manualmente con el contenido mínimo: {"mcpServers": {}}. Si tampoco existe el directorio, créalo. En macOS, la carpeta Library está oculta de forma predeterminada: usa Cmd+Shift+. en Finder para mostrar las carpetas ocultas o navega mediante la terminal.
Entender la estructura del archivo de configuración es fundamental. Sigue un formato JSON bien definido, con una jerarquía simple y predecible. Una vez que comprendas el patrón, agregar nuevos servers se vuelve una tarea mecánica que toma unos pocos segundos.
La estructura del archivo es un objeto JSON con un campo principal: "mcpServers". Dentro de él, cada server se representa como una clave (el nombre del server) que apunta a un objeto con dos campos obligatorios:
"python", "npx", "node")["-y", "@pacote/server"])Opcionalmente, un server puede tener el campo "env" para variables de entorno (como API keys).
Aquí tienes un ejemplo completo y comentado del formato:
{
"mcpServers": {
"meu-server": {
"command": "npx",
"args": ["-y", "@pacote/mcp-server"]
},
"outro-server": {
"command": "python",
"args": ["-m", "meu_server"],
"env": {
"API_KEY": "sua-chave-aqui"
}
}
}
}
Cada server es independiente. Puedes tener tantos como quieras, siempre que cada nombre sea único.
Ahora que entiendes la estructura del archivo, veamos el proceso práctico para registrar un nuevo MCP Server. Cada server necesita un nombre identificador, un comando de ejecución y los argumentos correctos. Seguir el proceso paso a paso garantiza que todo funcione a la primera.
Registrar un MCP Server significa agregar una nueva entrada al objeto "mcpServers" de config.json. Cada entrada necesita: un nombre (la clave del objeto; debe ser descriptiva y única), un command (el ejecutable: python, npx, node, uvx, etc.), y args (un array con la ruta o el paquete del server y sus argumentos). Claude Desktop usará esta información para iniciar el server automáticamente cuando lo necesite.
Define un nombre descriptivo para el server. Usa kebab-case (por ejemplo, meu-filesystem, github-tools). El nombre debe indicar claramente qué hace el server.
Identifica el ejecutable correcto: npx para paquetes npm, python o uvx para servers de Python, node para scripts JS directos.
Arma el array de argumentos: para npx, incluye "-y" seguido del nombre del paquete y de cualquier argumento del server. Para Python, usa "-m" seguido del módulo.
Guarda el archivo config.json, cierra Claude Desktop por completo y vuelve a abrirlo. El nuevo server debería aparecer entre las tools disponibles (ícono de martillo).
Configurar el archivo JSON por primera vez es sencillo, pero algunos errores sutiles pueden impedir que se carguen los MCP Servers. Conocer los problemas más comunes y saber diagnosticarlos te ahorra horas de frustración. La mayoría de los problemas se reduce a un JSON mal formado o a rutas incorrectas.
Los errores más frecuentes al configurar config.json son:
\\) o usa barras normales (/).command especificado no está en el PATH del sistema. Claude Desktop no encuentra npx o python.Claude Desktop no muestra mensajes de error claros cuando el config.json tiene problemas. Si los servers no aparecen después de reiniciar, el primer paso siempre es validar el JSON. Pega el contenido del archivo en jsonlint.com o usa la validación de VS Code (que subraya automáticamente los errores de sintaxis). Una sola coma de más puede invalidar todo el archivo.
Después de crear o editar config.json, es esencial validar que todo funcione. La validación consiste en reiniciar Claude Desktop, verificar que los servers aparezcan en la interfaz y confirmar que las tools estén disponibles. Es un proceso sencillo, pero debe realizarse correctamente.
La validación de la configuración sigue un flujo preciso: guardar el archivo config.json, cerrar por completo Claude Desktop (no basta con minimizarlo: ciérralo por completo, incluida la bandeja del sistema), volver a abrir la aplicación, y verificar el ícono de martillo (🔨) en el área de entrada del chat. Si aparece el ícono, haz clic en él para ver la lista de tools disponibles. Si los servers están conectados, verás los nombres de las tools de cada server. Si el ícono no aparece, hay un problema de configuración que debes investigar.
Guarda el config.json y cierra Claude Desktop por completo. En Windows, revisa la bandeja del sistema (system tray). En macOS, usa Cmd+Q.
Abre Claude Desktop de nuevo. Espera unos segundos a que se inicien los servers. Busca el ícono de martillo (🔨) junto al campo de entrada.
Haz clic en el ícono del martillo para ver la lista de tools. Cada server aporta sus propias tools. Verifica que aparezcan todas las esperadas.
Si el ícono no aparece, revisa los logs de Claude Desktop para encontrar mensajes de error relacionados con el inicio de los servers MCP.
Si todo sale bien, el ícono de martillo mostrará un número al lado, lo que indica cuántas tools están disponibles. Al hacer clic en él, verás cada tool con su nombre y descripción. Esta es la confirmación definitiva de que MCP funciona. En el siguiente módulo, haremos exactamente eso con un server de ejemplo real.
Siguiente Módulo: 2.6 — Primera prueba: MCP Server de ejemplo