MCP toolkit in Docker Engine on Linux

Greetings,

I’m trying to use the MCP toolkit on an headless machine, therefore I would like to use it with the Docker engine (not Docker Desktop). According to this previous discussion on the topic, it seems to be possible. However, after following the istructions presented there:

  • I have an executable in the expected path:
$ ls ~/.docker/cli-plugins/
docker-mcp
  • Running docker mcp --help results in the usual Docker help text:
$ docker mcp --help                                                                                                                                                      [29/38]
Usage:  docker [OPTIONS] COMMAND                                                                                                                                                            
                                                                                                                                                                                            
A self-sufficient runtime for containers                                                                                                                                                    
                                                                                                                                                                                            
Common Commands:                                                                                                                                                                            
  run         Create and run a new container from an image                                                                                                                                  
  exec        Execute a command in a running container                                                                                                                                      
  ps          List containers                                                                                                                                                               
  build       Build an image from a Dockerfile                                                                                                                                              
  pull        Download an image from a registry                                                                                                                                             
  push        Upload an image to a registry                                                                                                                                                 
  images      List images                                                                                                                                                                   
  login       Authenticate to a registry                                                                                                                                                    
  logout      Log out from a registry                                                                                                                                                       
  search      Search Docker Hub for images                                                                                                                                                  
  version     Show the Docker version information                                                                                                                                           
  info        Display system-wide information                                                                                                                                               
                                                                                                                                                                                            
Management Commands:                                                                                                                                                                        
  builder     Manage builds                                                                                                                                                                 
  container   Manage containers                                                                                                                                                             
  context     Manage contexts                                                                                                                                                               
  image       Manage images                                                                                                                                                                 
  manifest    Manage Docker image manifests and manifest lists                                                                                                                              
  network     Manage networks                                                                                                                                                               
  plugin      Manage plugins                                                                                                                                                                
  system      Manage Docker                                                                                                                                                                 
  trust       Manage trust on Docker images                                                                                                                                                 
  volume      Manage volumes                                                                                                                                                                

Swarm Commands:
  swarm       Manage Swarm

Commands:
  attach      Attach local standard input, output, and error streams to a running container
  commit      Create a new image from a container's changes
  cp          Copy files/folders between a container and the local filesystem
  create      Create a new container
  diff        Inspect changes to files or directories on a container's filesystem
  events      Get real time events from the server
  export      Export a container's filesystem as a tar archive
  history     Show the history of an image
  import      Import the contents from a tarball to create a filesystem image
  inspect     Return low-level information on Docker objects
  kill        Kill one or more running containers
  load        Load an image from a tar archive or STDIN
  logs        Fetch the logs of a container
  pause       Pause all processes within one or more containers
  port        List port mappings or a specific mapping for the container
  rename      Rename a container
  restart     Restart one or more containers
  rm          Remove one or more containers
  rmi         Remove one or more images
  save        Save one or more images to a tar archive (streamed to STDOUT by default)
  start       Start one or more stopped containers
  stats       Display a live stream of container(s) resource usage statistics
  stop        Stop one or more running containers
  tag         Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE
  top         Display the running processes of a container
  unpause     Unpause all processes within one or more containers
  update      Update configuration of one or more containers
  wait        Block until one or more containers stop, then print their exit codes

Global Options:
      --config string      Location of client config files (default "/root/.docker")
  -c, --context string     Name of the context to use to connect to the daemon (overrides DOCKER_HOST env var and default context set with "docker context use")
  -D, --debug              Enable debug mode
  -H, --host list          Daemon socket to connect to
  -l, --log-level string   Set the logging level ("debug", "info", "warn", "error", "fatal") (default "info")
      --tls                Use TLS; implied by --tlsverify
      --tlscacert string   Trust certs signed only by this CA (default "/root/.docker/ca.pem") 
      --tlscert string     Path to TLS certificate file (default "/root/.docker/cert.pem")
      --tlskey string      Path to TLS key file (default "/root/.docker/key.pem")
      --tlsverify          Use TLS and verify the remote
  -v, --version            Print version information and quit

Run 'docker COMMAND --help' for more information on a command.

For more help on how to use Docker, head to https://docs.docker.com/go/guides/
  • Running docker mcp fails:
$ docker mcp
docker: unknown command: docker mcp

Run 'docker --help' for more information

Can you please help me get this to work?
Thank you in advance,

GTP

What do you get when you execute docker-mcp directly? For example:

$HOME/.docker/cli-plugins/docker-mcp

Or just ./docker-mcp when you are in the cli-plugins folder. “mcp” should be among the management commands, and it isn’t. But you also don’t have “buildx”, which should also be in the management section.

Can you also share the output of docker info? Remove anything from the output you wouldn’t share like private registries, usernames or IP addresses. The output of docker version could help too.

But the docker info shows the recognized plugins with their paths and based on the help output it looks like your Docker doesn’t recognize any.

Running it directly works:

$ ./.docker/cli-plugins/docker-mcp 
Docker MCP Toolkit's CLI - Manage your MCP servers and clients.

Usage: docker mcp [OPTIONS]

Flags:
  -v, --version   Print version information and quit

Available Commands:
  catalog     Manage MCP server catalogs
  client      Manage MCP clients
  config      Manage the configuration
  feature     Manage experimental features
  gateway     Manage the MCP Server gateway
  policy      Manage secret policies
  secret      Manage secrets
  server      Manage servers
  tools       Manage tools
  version     Show the version information

So it seems that Docker is just somehow not “seeing” it.
Here’s the additional information:

$ docker info                                                                                                                                                            [6/119]
Client:                                                                                                                                                                                     
 Version:    28.2.2                                                                                                                                                                         
 Context:    default                                                                                                                                                                        
 Debug Mode: false                                                                                                                                                                          
                                                                                                                                                                                            
Server:                                                                                                                                                                                     
 Containers: 3
  Running: 0
  Paused: 0
  Stopped: 3
 Images: 26
 Server Version: 28.2.2
 Storage Driver: overlay2
  Backing Filesystem: extfs
  Supports d_type: true
  Using metacopy: false
  Native Overlay Diff: true
  userxattr: false
 Logging Driver: json-file
 Cgroup Driver: systemd
 Cgroup Version: 2
 Plugins:
  Volume: local
  Network: bridge host ipvlan macvlan null overlay
  Log: awslogs fluentd gcplogs gelf journald json-file local splunk syslog
 CDI spec directories:
  /etc/cdi
  /var/run/cdi
 Swarm: inactive
 Runtimes: io.containerd.runc.v2 runc
 Default Runtime: runc
 Init Binary: docker-init
 containerd version: 
 runc version: 
 init version: 
 Security Options:
  apparmor
  seccomp
   Profile: builtin
  cgroupns
 Kernel Version: 6.8.0-1041-oracle
 Operating System: Ubuntu 22.04.5 LTS
 OSType: linux
 Architecture: x86_64
 CPUs: 2
 Total Memory: 956.7MiB
 Name: irc
 ID: 218dc706-33b1-469d-b218-aa0d8c112a31
 Docker Root Dir: /var/lib/docker
 Debug Mode: false
 Experimental: false
Insecure Registries:  
  ::1/128 
  127.0.0.0/8                            
 Live Restore Enabled: false 
$ docker version
Client:
 Version:           28.2.2
 API version:       1.50
 Go version:        go1.23.1
 Git commit:        28.2.2-0ubuntu1~22.04.1
 Built:             Wed Sep 10 14:50:16 2025
 OS/Arch:           linux/amd64
 Context:           default

Server:
 Engine:
  Version:          28.2.2
  API version:      1.50 (minimum version 1.24)
  Go version:       go1.23.1
  Git commit:       28.2.2-0ubuntu1~22.04.1
  Built:            Wed Sep 10 14:50:16 2025
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.7.28
  GitCommit:        
 runc:
  Version:          1.3.3-0ubuntu1~22.04.3
  GitCommit:        
 docker-init:
  Version:          0.19.0
  GitCommit:        

I’m running this on a VPS running Ubuntu server:

$ cat /etc/lsb-release 
DISTRIB_ID=Ubuntu
DISTRIB_RELEASE=22.04
DISTRIB_CODENAME=jammy
DISTRIB_DESCRIPTION="Ubuntu 22.04.5 LTS"

Thank you for your help,

GTP

Can you share the output of dpkg -l | grep -E 'docker|containerd'. It looks like you use the distro version of docker, which is not guaranteed to behave like vanilla docker.

I see, I indeed tend to use the distro’s packages for software. Here’s the output:

$ dpkg -l | grep -E 'docker|containerd'
ii  containerd                             1.7.28-0ubuntu1~22.04.1                 amd64        daemon to control runC
ii  docker.io                              28.2.2-0ubuntu1~22.04.1                 amd64        Linux container runtime

Should I add Docker’s repository and reinstall it?

Here are the docs: https://docs.docker.com/engine/install/ubuntu/#uninstall-old-versions, after the uninstallation of the distro version, it describes the installation of the docker repos and the docker-ce package (=vanilla docker)

I followed the instructions to uninstall the unofficial packages and start with a clean installation form Docker’s official repository.

$ dpkg -l | grep -E 'docker|containerd'
rc  containerd                             1.7.28-0ubuntu1~22.04.1                 amd64        daemon to control runC
ii  containerd.io                          2.2.1-1~ubuntu.22.04~jammy              amd64        An open and reliable container runtime
ii  docker-buildx-plugin                   0.30.1-1~ubuntu.22.04~jammy             amd64        Docker Buildx plugin extends build capabilities with BuildKit.
ii  docker-ce                              5:29.1.5-1~ubuntu.22.04~jammy           amd64        Docker: the open-source application container engine
ii  docker-ce-cli                          5:29.1.5-1~ubuntu.22.04~jammy           amd64        Docker CLI: the open-source application container engine
ii  docker-ce-rootless-extras              5:29.1.5-1~ubuntu.22.04~jammy           amd64        Rootless support for Docker.
ii  docker-compose-plugin                  5.0.1-1~ubuntu.22.04~jammy              amd64        Docker Compose (V2) plugin for the Docker CLI.
rc  docker.io                              28.2.2-0ubuntu1~22.04.1                 amd64        Linux container runtime

Running the MCP plugin by invoking it directly still works:

$ ./.docker/cli-plugins/docker-mcp 
Docker MCP Toolkit's CLI - Manage your MCP servers and clients.

Usage: docker mcp [OPTIONS]

Flags:
  -v, --version   Print version information and quit

Available Commands:
  catalog     Manage MCP server catalogs
  client      Manage MCP clients
  config      Manage the configuration
  feature     Manage experimental features
  gateway     Manage the MCP Server gateway
  policy      Manage secret policies
  secret      Manage secrets
  server      Manage servers
  tools       Manage tools
  version     Show the version information

But invoking it from Docker’s CLI still doesn’t:

$ docker mcp
docker: unknown command: docker mcp

Run 'docker --help' for more information

Any ideas on what isn’t working here?
Thank you for your help so far,

GTP

You share the output of docker info again. It should list all cli extensions.

I can only imagine that a setting in ~/.docker or /etc/docker/daemon.json might cause the behavior.

Here it is:

$ docker info                                                                                                                                                           [10/206]
Client: Docker Engine - Community                                                                                                                                                           
 Version:    29.1.5                                                                                                                                                                         
 Context:    default                                                                                                                                                                        
 Debug Mode: false                                                                                                                                                                          
 Plugins:                                                                                                                                                                                   
  buildx: Docker Buildx (Docker Inc.)                                                                                                                                                       
    Version:  v0.30.1                                                                                                                                                                       
    Path:     /usr/libexec/docker/cli-plugins/docker-buildx                                                                                                                                 
  compose: Docker Compose (Docker Inc.)                                                                                                                                                     
    Version:  v5.0.1                                                                                                                                                                        
    Path:     /usr/libexec/docker/cli-plugins/docker-compose                                  

Server:                                        
 Containers: 1                                 
  Running: 0                                   
  Paused: 0                                    
  Stopped: 1                                   
 Images: 1                                     
 Server Version: 29.1.5                        
 Storage Driver: overlayfs                     
  driver-type: io.containerd.snapshotter.v1                                                   
 Logging Driver: json-file                     
 Cgroup Driver: systemd                        
 Cgroup Version: 2                             
 Plugins:                                      
  Volume: local                                
  Network: bridge host ipvlan macvlan null overlay                                            
  Log: awslogs fluentd gcplogs gelf journald json-file local splunk syslog                    
 CDI spec directories:                         
  /etc/cdi                                     
  /var/run/cdi                                 
 Swarm: inactive                               
 Runtimes: io.containerd.runc.v2 runc          
 Default Runtime: runc                         
 Init Binary: docker-init                      
 containerd version: dea7da592f5d1d2b7755e3a161be07f43fad8f75                                 
 runc version: v1.3.4-0-gd6d73eb8              
 init version: de40ad0                         
 Security Options:                             
  apparmor                                     
  seccomp                                      
   Profile: builtin                            
  cgroupns                                     
 Kernel Version: 6.8.0-1041-oracle             
 Operating System: Ubuntu 22.04.5 LTS          
 OSType: linux                                 
 Architecture: x86_64                          
 CPUs: 2                                       
 Total Memory: 956.7MiB                        
 Name: irc                                     
 ID: 8e7cad3e-6f19-4dbb-8c68-b0f812290f2b  
 Docker Root Dir: /var/lib/docker              
 Debug Mode: false                             
 Experimental: false                           
 Insecure Registries:                          
  ::1/128                                      
  127.0.0.0/8                                  
 Live Restore Enabled: false                   
 Firewall Backend: iptables

Thanks again,

GTP

It does list cli plugins. The question remains, why it doesn’t show those located in ~/.docker/cli-plugins/.

I tried it earlier successfully by downloading a release from the github repo:

wget https://github.com/docker/mcp-gateway/releases/download/v0.36.0/docker-mcp-linux-amd64.tar.gz
mkdir -p "$HOME/.docker/cli-plugins/"
tar xzf docker-mcp-linux-amd64.tar.gz
mv docker-mcp "$HOME/.docker/cli-plugins/"

I solved it by creating a symbolic link: $ sudo ln -s /home/ubuntu/.docker/cli-plugins/docker-mcp /usr/libexec/docker/cli-plugins/docker-mcp. Now it seems to work:

$ docker mcp
Docker MCP Toolkit's CLI - Manage your MCP servers and clients.

Usage: docker mcp [OPTIONS]

Flags:
  -v, --version   Print version information and quit

Available Commands:
  catalog     Manage MCP server catalogs
  client      Manage MCP clients
  config      Manage the configuration
  feature     Manage experimental features
  gateway     Manage the MCP Server gateway
  policy      Manage secret policies
  secret      Manage secrets
  server      Manage servers
  tools       Manage tools
  version     Show the version information

Thanks everyone for your help.

GTP