Usar el kit de herramientas de MCP desde la CLI

Note

Los comandos de docker mcp documentados aquí están disponibles en Docker Desktop 4.62 y versiones posteriores. Es posible que las versiones anteriores no admitan todos los comandos mostrados.

Los comandos de docker mcp te permiten gestionar perfiles, servidores, credenciales de OAuth y catálogos de MCP desde la terminal. Usa la CLI para scripts, automatización y entornos sin interfaz gráfica (headless).

Perfiles

Crear un perfil

$ docker mcp profile create --name <profile-id>

El ID del perfil se utiliza para hacer referencia al perfil en los comandos siguientes:

$ docker mcp profile create --name web-dev

Listar perfiles

$ docker mcp profile list

Ver un perfil

$ docker mcp profile show <profile-id>

Eliminar un perfil

$ docker mcp profile remove <profile-id>

Caution

Al eliminar un perfil se borran todas las configuraciones y ajustes de sus servidores. Esta acción no se puede deshacer.

Servidores

Explorar el catálogo

Lista los servidores disponibles y sus ID:

$ docker mcp catalog server ls mcp/docker-mcp-catalog

La salida enumera cada servidor por nombre. El nombre (por ejemplo, playwright o github-official) es el ID del servidor que se debe utilizar en las URI catalog://.

Para buscar un ID de servidor en Docker Desktop, abre MCP Toolkit > Catalog, selecciona un servidor y comprueba el campo Server ID.

Añadir servidores a un perfil

Los servidores se referencian mediante una URI. El formato de la URI depende de la procedencia del servidor:

El formato más común es catalog://, donde <catalog-ref> coincide con el campo Catalog y <server-id> coincide con el campo Server ID que se muestra en Docker Desktop o en la salida de catalog server ls:

$ docker mcp profile server add <profile-id> \
  --server catalog://<catalog-ref>/<server-id>

Añade varios servidores en un solo comando:

$ docker mcp profile server add web-dev \
  --server catalog://mcp/docker-mcp-catalog/github-official \
  --server catalog://mcp/docker-mcp-catalog/playwright

Para añadir un servidor definido en un archivo YAML local:

$ docker mcp profile server add my-profile \
  --server file://./my-server.yaml

El archivo YAML define la imagen y la configuración del servidor:

name: my-server
title: My Server
type: server
image: myimage:latest
description: Description of the server

Si el servidor requiere autenticación OAuth, autorízalo en Docker Desktop después de añadirlo. Consulta Autenticación OAuth.

Listar servidores

Lista todos los servidores en todos los perfiles:

$ docker mcp profile server ls

Filtrar por perfil:

$ docker mcp profile server ls --filter profile=web-dev

Eliminar un servidor

$ docker mcp profile server remove <profile-id> --name <server-name>

Elimina varios servidores a la vez:

$ docker mcp profile server remove web-dev \
  --name github-official \
  --name playwright

Configurar los ajustes del servidor

Establece y recupera los valores de configuración para los servidores en un perfil:

$ docker mcp profile config <profile-id> --set <server-id>.<key>=<value>
$ docker mcp profile config <profile-id> --get-all
$ docker mcp profile config <profile-id> --del <server-id>.<key>

Las claves de configuración del servidor y sus valores esperados los define cada servidor. Consulta la documentación del servidor o su entrada en Docker Desktop en MCP Toolkit > Catalog > Configuration.

Gateway

Ejecuta el Gateway de MCP con un perfil específico:

$ docker mcp gateway run --profile <profile-id>

Omite --profile para usar el perfil predeterminado.

Conectar un cliente manualmente

Para conectar cualquier cliente que no figure en Docker Desktop, configúralo para que ejecute el gateway a través de stdio. Por ejemplo, en una configuración de cliente basada en JSON:

{
  "servers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": ["mcp", "gateway", "run", "--profile", "web-dev"],
      "type": "stdio"
    }
  }
}

Para Claude Desktop, el formato es:

{
  "mcpServers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": ["mcp", "gateway", "run", "--profile", "web-dev"]
    }
  }
}

Conectar un cliente con nombre

Conecta un cliente compatible a un perfil:

$ docker mcp client connect <client> --profile <profile-id>

Por ejemplo, para conectar VS Code a un perfil específico del proyecto:

$ docker mcp client connect vscode --profile my-project

Esto crea un archivo .vscode/mcp.json en el directorio actual. Como este es un archivo específico del usuario, añádelo a .gitignore:

$ echo ".vscode/mcp.json" >> .gitignore

Compartir perfiles

Comparte perfiles con tu equipo utilizando registros de OCI o control de versiones.

Compartir a través de un registro de OCI

Los perfiles se comparten como artefactos de OCI a través de cualquier registro compatible con OCI. Las credenciales no se incluyen por razones de seguridad. Los miembros del equipo configuran las credenciales de autenticación por separado después de realizar la descarga (pull).

Para subir (push) un perfil existente llamado web-dev a un registro de OCI:

$ docker mcp profile push web-dev registry.example.com/profiles/web-dev:v1

Para descargar (pull) el mismo perfil:

$ docker mcp profile pull registry.example.com/profiles/team-standard:latest

Compartir a través del control de versiones

Para perfiles específicos del proyecto, puedes utilizar los comandos export e import y almacenar los perfiles en el control de versiones junto con tu código. Los miembros del equipo pueden importar el archivo para obtener la misma configuración.

Para exportar un perfil a tu directorio de proyecto:

$ mkdir -p .docker
$ docker mcp profile export web-dev .docker/mcp-profile.json

Los miembros del equipo que clonen el repositorio pueden importar el perfil:

$ docker mcp profile import .docker/mcp-profile.json

Esto crea un perfil con los servidores y la configuración definidos en el archivo. Cualquier credencial de autenticación debe configurarse por separado si es necesario.

Catálogos personalizados

Los catálogos personalizados te permiten seleccionar una colección enfocada de servidores para tu equipo u organización. Para obtener una descripción general de qué son los catálogos personalizados y cuándo utilizarlos, consulta Catálogos personalizados.

Los catálogos se referencian mediante una referencia de OCI, por ejemplo, registry.example.com/mcp/my-catalog:latest. Los servidores dentro de un catálogo utilizan los mismos esquemas de URI que al añadir servidores a un perfil.

Personalizar el catálogo de Docker

Utiliza el catálogo de Docker como base, luego añade o elimina servidores para adaptarlos a las necesidades de tu organización. Cópialo primero:

$ docker mcp catalog tag mcp/docker-mcp-catalog \
  registry.example.com/mcp/company-tools:latest

Lista los servidores que contiene:

$ docker mcp catalog server ls registry.example.com/mcp/company-tools:latest

Elimina los servidores que tu organización no apruebe:

$ docker mcp catalog server remove \
  registry.example.com/mcp/company-tools:latest \
  --name <server-name>

Añade tus propios servidores privados, empaquetados como imágenes de Docker:

$ docker mcp catalog server add registry.example.com/mcp/company-tools:latest \
  --server docker://registry.example.com/mcp/internal-api:latest \
  --server docker://registry.example.com/mcp/data-pipeline:latest

Súbelo (push) cuando esté listo:

$ docker mcp catalog push registry.example.com/mcp/company-tools:latest

Crear un catálogo desde cero

Para incluir exactamente lo que elijas y nada más, crea un catálogo desde cero. Puedes incluir servidores del catálogo de Docker, tus propias imágenes privadas o ambos.

Crea un catálogo y especifica qué servidores incluir:

$ docker mcp catalog create registry.example.com/mcp/data-tools:latest \
  --title "Data Analysis Tools" \
  --server catalog://mcp/docker-mcp-catalog/sequentialthinking \
  --server catalog://mcp/docker-mcp-catalog/brave \
  --server docker://registry.example.com/mcp/analytics:latest

Ver el resultado:

$ docker mcp catalog show registry.example.com/mcp/data-tools:latest

Súbelo para distribuirlo:

$ docker mcp catalog push registry.example.com/mcp/data-tools:latest

Distribuir un catálogo

Sube tu catálogo para que los miembros de tu equipo puedan importarlo:

$ docker mcp catalog push <oci-reference>

Los miembros del equipo pueden descargarlo (pull) utilizando la CLI:

$ docker mcp catalog pull <oci-reference>

O impórtalo usando Docker Desktop: selecciona MCP Toolkit > Catalog > Import catalog e introduce la referencia de OCI.

Usar un catálogo personalizado con el gateway

Ejecuta el gateway con tu catálogo en lugar del catálogo de Docker predeterminado:

$ docker mcp gateway run --catalog <oci-reference>

Para MCP dinámico, donde los agentes descubren y añaden servidores durante las conversaciones, esto limita lo que los agentes pueden encontrar a tu conjunto seleccionado.

Para habilitar servidores específicos de tu catálogo sin usar un perfil:

$ docker mcp gateway run --catalog <oci-reference> \
  --servers <name1> --servers <name2>

Lecturas adicionales

• Primeros pasos con el kit de herramientas de MCP
• Perfiles de MCP
• Catálogo de MCP
• Gateway de MCP