Una configuración práctica de Docker MCP Toolkit, desde el primer interruptor hasta la primera llamada a una herramienta. Activa el gateway, crea un perfil, elige servidores firmados del catálogo, conecta Claude Desktop y Claude Code, y luego prueba, depura y protege cada contenedor.
La mayoría de las configuraciones de MCP empiezan igual. Pegas un bloque JSON en Claude Desktop, pegas otro ligeramente distinto en Claude Code, lanzas un tercer servidor con npx y dejas un token de acceso personal en texto plano dentro de un archivo de configuración. Funciona hasta que deja de funcionar, y entonces tienes que revisar tres archivos para averiguar por qué ha desaparecido una herramienta. El Docker MCP Toolkit sustituye ese montón por una sola capa gestionada: servidores que se ejecutan como contenedores, un catálogo que los proporciona y un único gateway al que se conecta Claude. Este artículo configura las tres piezas, conecta Claude Desktop y Claude Code, y muestra cómo comprobar que cada herramienta está activa antes de depender de ella.
El Toolkit vive dentro de Docker Desktop. Ejecuta servidores MCP como contenedores aislados, los agrupa en perfiles con nombre y expone cada perfil a las aplicaciones de IA a través del MCP Gateway. Claude nunca lanza un servidor por su cuenta. Se comunica con un solo punto de acceso, y el gateway envía cada solicitud al contenedor adecuado.
La ventaja práctica es la separación. Tu editor, tu aplicación de chat y tu agente de terminal apuntan al mismo gateway, mientras que los servidores, sus credenciales y sus límites de recursos quedan en manos de Docker, en lugar de copiarse en la configuración de cada cliente.
Piensa en el gateway como en una recepción. Cada solicitud de Claude llega allí. El gateway elige el servidor que debe responder, inicia su contenedor cuando hace falta y devuelve el resultado. La cadena es corta: Claude, después el gateway y por último el servidor en contenedor.
El gateway es de código abierto, con licencia MIT, y se instala como plugin de la CLI de Docker, así que docker mcp --help funciona en cuanto el Toolkit está activado. Por defecto usa stdio, que sirve para un solo cliente. Cuando varios clientes necesitan el mismo gateway, ejecútalo sobre HTTP con streaming:
docker mcp gateway run --port 8080 --transport streaming
La capa de contenedores es lo que hace que todo sea más ordenado. Antes del Toolkit, cada servidor necesitaba su propio entorno de ejecución en tu equipo: Node para uno, Python para otro, una versión fijada para un tercero. Un servidor en contenedor lleva consigo su entorno de ejecución, así que lo único que tu equipo necesita es Docker. Actualizar o eliminar un servidor deja de ser una tarea de limpieza, porque el servidor nunca se instaló en el equipo anfitrión.
Tres términos sostienen todo el sistema, y cada comando de este artículo afecta a uno de ellos.
| Elemento | Qué es | Dónde se gestiona |
|---|---|---|
| Catálogo | Una colección seleccionada de servidores MCP empaquetados como imágenes de contenedor | Pestaña Catalog, docker mcp catalog ls |
| Perfil | Un grupo con nombre de servidores y sus ajustes para un proyecto o flujo de trabajo | Pestaña Profiles, docker mcp profile list |
| Cliente | La aplicación de IA que se conecta, como Claude Desktop o Claude Code | Pestaña Clients, docker mcp client ls |
💡 Consejo: un mismo perfil puede servir a varios clientes. Configúralo una vez y todas las aplicaciones conectadas verán las mismas herramientas.
Necesitas muy poco, pero cada requisito importa.
El Toolkit requiere Docker Desktop 4.62 o posterior, y se activa desde un interruptor beta:
Ahora aparece una entrada MCP Toolkit en el menú de Docker Desktop. Si usaste una versión anterior del Toolkit, tu configuración existente se migra a un perfil llamado default, así que no hay que reconstruir nada.
Aquí importan dos clientes de Claude. Claude Desktop se conecta desde la pestaña Clients con un solo botón. Claude Code se conecta desde la terminal con un comando. La documentación de Docker también menciona Cursor, Zed y Visual Studio Code, lo que resulta útil si tu equipo usa editores distintos, ya que todos pueden leer el mismo perfil.
💡 Consejo: instala Claude Code antes de empezar si vas a usar la ruta de terminal. La comprobación de conexión que verás más adelante depende de su comando
claude mcp list.
Un perfil es un espacio de trabajo. Un perfil de investigación puede contener un servidor de búsqueda y un servidor de notas, mientras que un perfil de publicación incluye GitHub y un servidor de monitorización. Mantenerlos separados hace que Claude solo vea las herramientas que importan para la tarea en curso.
Tres configuraciones de perfil ilustran la idea:
El mismo resultado requiere dos comandos:
docker mcp profile create --name dev-tools --server catalog://<server-reference>
docker mcp profile list
Sustituye el marcador por la referencia de un servidor de tu catálogo. Tres subcomandos más se encargan del mantenimiento:
docker mcp profile server add y remove cambian la lista de servidores.docker mcp profile config <id> --set (o --get, --del) edita los ajustes de un perfil.docker mcp profile tools <id> --enable (o --disable) controla qué herramientas puede invocar Claude.El catálogo de Docker MCP incluye cientos de servidores. Las páginas de Docker dan una cifra de más de 200 en un sitio y de más de 300 en otro, lo que sugiere que sigue creciendo. Explóralo desde la pestaña Catalog, selecciona Add to y elige tu perfil. Los servidores marcados como Configuration Required necesitan una credencial o un ajuste antes de funcionar.
El catálogo combina tres tipos de servidor:
mcp de Docker Hub.
💡 Consejo: los equipos que necesitan un control más estricto pueden crear un catálogo personalizado e importarlo con
docker mcp catalog pull <oci-reference>, de modo que las personas solo vean servidores aprobados.
Empieza poco a poco. Cada servidor que añades pone más descripciones de herramientas delante de Claude, y un perfil ajustado mantiene sus elecciones más precisas. Cuatro puntos de partida sencillos:
| Objetivo | Servidor para probar | Tipo |
|---|---|---|
| Revisar pull requests | GitHub | Servidor remoto |
| Buscar notas del equipo | Notion | Servidor remoto |
| Revisar paneles | Grafana | Socio verificado |
| Inspeccionar pagos | Stripe | Socio verificado |
Los servidores remotos como GitHub usan OAuth. Docker abre una ventana del navegador, apruebas el acceso y la credencial queda gestionada por Docker en lugar de pegarse en un JSON. Para los servidores que necesitan secretos estáticos, ejecuta docker mcp secret --help para ver las opciones, y docker mcp oauth --help para los comandos de autorización. La documentación de Docker añade que las solicitudes que contienen información sensible se bloquean.
💡 Consejo: nunca pegues un token real en una ventana de chat ni en una configuración compartida. Si un servidor pide uno, guárdalo a través del Toolkit.
Tras el reinicio, abre el menú Búsqueda y herramientas. Debería aparecer una entrada llamada MCP_DOCKER, activada. Ahora todos los servidores de tu perfil están detrás de esa única entrada.
Claude Code se conecta con un solo comando:
docker mcp client connect claude-code --global
claude mcp list
El segundo comando debería mostrar una línea como MCP_DOCKER: docker mcp gateway run - ✓ Connected. Para vincular un cliente a un solo perfil en lugar de a todos, el comando de conexión acepta --profile, como en docker mcp client connect vscode --profile my_profile. La forma general es docker mcp client connect [client-name] --profile [id].
El indicador --global aplica la conexión a todo el sistema en lugar de al proyecto actual, lo que resulta adecuado en un equipo personal. Omítelo cuando un único repositorio deba tener su propio conjunto de herramientas.
Algunos clientes leen su propio archivo JSON y no tienen botón de conexión. Añade el gateway como servidor stdio:
{
"servers": {
"MCP_DOCKER": {
"command": "docker",
"args": ["mcp", "gateway", "run", "--profile", "my_profile"],
"type": "stdio"
}
}
}
Usa el nombre de la propiedad de nivel superior que documente tu cliente, porque algunos esperan mcpServers donde este fragmento dice servers. Una sola entrada reemplaza el conjunto de bloques de servidor separados que tenías antes.
Como el gateway mantiene tus herramientas en un solo lugar, nada de esto hay que reconstruirlo al cambiar de cliente. Si pasas de Claude Desktop a Claude Code, el mismo perfil te acompaña.
Ejecuta un prompt que fuerce una llamada real a una herramienta. El ejemplo que propone Docker funciona bien: "Usa el servidor MCP de GitHub para mostrarme mis pull requests abiertas." Si Claude responde con datos de tu cuenta, toda la cadena funciona. Para una vista de más bajo nivel, docker mcp tools ls lista cada herramienta que el gateway expone en ese momento, y docker mcp client ls muestra qué clientes están conectados.
Prueba en tres pasos. Primero, pide a Claude que liste las herramientas que ve, lo que confirma que el perfil se cargó. Segundo, llama a una herramienta de solo lectura, como listar pull requests, lo que confirma que las credenciales funcionan. Tercero, y solo entonces, prueba una acción que cambie algo, y hazlo en un repositorio desechable o en un espacio de pruebas, para que una errata no cueste nada.
El gateway necesita entre 15 y 25 segundos para arrancar. La mayoría de los momentos de "está roto" son en realidad "todavía se está iniciando". Espera medio minuto antes de cambiar nada y revisa después esta tabla.
| Síntoma | Causa probable | Solución |
|---|---|---|
Falta MCP_DOCKER en Claude Desktop | No se reinició la aplicación | Cierra Claude Desktop y ábrelo de nuevo |
| No conectado justo después de encender el equipo | El gateway aún se está iniciando | Espera y ejecuta claude mcp list otra vez |
| El servidor muestra Configuration Required | Falta una credencial o la aprobación de OAuth | Termina la configuración en la pestaña Catalog |
| Faltan las herramientas de un servidor | Herramientas desactivadas en el perfil | Vuelve a activarlas con docker mcp profile tools |
Docker aplica protecciones por defecto. Cada contenedor de servidor tiene un tope de 1 CPU y 2 GB de memoria, el acceso al sistema de archivos permanece desactivado hasta que lo concedas, y las imágenes del espacio de nombres mcp están firmadas digitalmente. Dentro de un perfil, una lista de herramientas permitidas limita qué puede invocar Claude.
Una función merece una decisión deliberada. Dynamic MCP permite a Claude buscar en el catálogo y añadir un servidor en mitad de una conversación, usando las herramientas de gestión que expone el gateway: mcp-find, mcp-add, mcp-config-set, mcp-remove, mcp-exec y una code-mode experimental. Se activa automáticamente con el Toolkit. Si quieres un conjunto fijo de herramientas, desactívala:
docker mcp feature disable dynamic-tools
Vuelve a activarla más tarde con docker mcp feature enable dynamic-tools.
La configuración genera mucho texto que leer: mensajes de error, comandos de perfil, notas para tus compañeros. Claude Sonnet 5 está en la colección de modelos de lenguaje (LLM) de PicassoIA y se ocupa exactamente de eso. Lee una petición sencilla o una traza de pila, acepta una captura de pantalla y devuelve comandos o soluciones que puedes contrastar con la documentación de Docker.
Esta es la rutina, de principio a fin:
claude mcp list.low es el valor por defecto y omite el pensamiento extendido, así que las respuestas llegan rápido. Súbelo a high o max si el problema es enrevesado y abarca varios archivos.docker mcp exactos y una frase de contexto."| Ajuste | Qué hace | Valor sugerido |
|---|---|---|
| Effort | Controla cuánto razonamiento ocurre antes de la respuesta | low para consultas, high para depurar |
| Image | Envía una captura de pantalla con la solicitud | Una ventana de Docker Desktop recortada |
| System Prompt | Fija el rol y el tono de la sesión | Un breve encargo de asistente de DevOps |
| Max Tokens | Limita la longitud de la respuesta | 8192 |
💡 Consejo: Sonnet 5 no puede ver tu equipo. Trata sus comandos como borradores y compruébalos uno a uno con la documentación de Docker antes de ejecutarlos.
Otros modelos de la plataforma se adaptan a hábitos distintos. Claude Fable 5 está pensado para tareas de programación más difíciles, GPT 5.6 Sol aborda código complejo, Gemini 3.1 Pro gestiona preguntas multimodales largas y Kimi K2.6 está diseñado para trabajo con agentes.
Una vez que Claude llega a tus servidores a través de un solo gateway, el siguiente paso es darle algo que mirar a esos flujos de trabajo. Un servidor de GitHub puede redactar las notas de la versión, un servidor de Notion puede guardar el encargo y un modelo de imagen puede crear la foto de cabecera en la misma sesión.
Cada foto de este artículo se creó con P Image, generada a partir de prompts largos y muy específicos que nombran la lente, la luz y las texturas de las superficies. Para otros estilos, prueba Flux 2 Pro, GPT Image 2, Seedream 4.5 o Nano Banana Pro. Cuando una imagen debe moverse, Seedance 2.0, Veo 3.1 y Kling v3 Video convierten un prompt o una sola imagen en clips cortos.
Abre Picasso IA, elige un modelo y describe una escena como le darías un encargo a un fotógrafo: el sujeto, el ángulo, la luz, la lente. Genera algunas variaciones, conserva la que encaje con tu artículo e insértala. La primera imagen tarda un minuto, y la segunda, menos.
Elige tu idioma
