Docker Desktop not detected on macOS: servers fail with `command not found: docker` despite `docker_available: true`

[algis-dumbris]

Summary

On a stock macOS machine with Docker Desktop installed and running, mcpproxy cannot launch any Docker-based upstream server. The spawned process fails with zsh:1: command not found: docker, even though:

• Docker Desktop is installed (/Applications/Docker.app)
• The Docker daemon is running (socket present at ~/.docker/run/docker.sock)
• mcpproxy's own status reports docker_available: true / global_enabled: true

The root cause is that a default Docker Desktop install does not place the docker CLI on a standard PATH directory. The binary lives inside the app bundle:

/Applications/Docker.app/Contents/Resources/bin/docker

Docker Desktop only symlinks it into /usr/local/bin if the user opts into "install CLI tools" (which requires admin privileges). mcpproxy spawns upstream servers with a sanitized PATH that does not include the app-bundle bin directory, so docker is unresolvable at spawn time.

This makes Docker isolation / Docker-based servers fail out-of-the-box for any user who installed Docker Desktop the default way.

Environment

• mcpproxy: v0.39.0 (personal), darwin/arm64
• macOS: 26.5.1 (arm64, Apple Silicon)
• Docker Desktop CLI: Docker version 29.5.3, build d1c06ef (resolvable only via full path)
• command -v docker → NOT FOUND (no symlink in /usr/local/bin or /opt/homebrew/bin)

PATH mcpproxy uses when spawning servers (from logs):

/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin

Note /Applications/Docker.app/Contents/Resources/bin is absent.

Steps to reproduce

1. Fresh macOS machine. Install Docker Desktop the default way (do not run the optional "install CLI tools" / privileged helper step). Start Docker Desktop.
2. Confirm the daemon is up but the CLI is not on PATH:
   • ls ~/.docker/run/docker.sock → exists
   • command -v docker → not found
   • /Applications/Docker.app/Contents/Resources/bin/docker --version → works
3. Add a Docker-based upstream server, e.g. a server whose command is docker run --rm -i … <image>.
4. Observe it never connects.

Expected

mcpproxy either:

• discovers Docker Desktop's bundled CLI path automatically and uses it, or
• surfaces a clear, actionable error ("Docker CLI not found on PATH — install Docker Desktop CLI tools or add /Applications/Docker.app/Contents/Resources/bin to PATH") instead of a raw repeated command not found.

And docker_available should reflect whether the docker binary is actually resolvable on the spawn PATH, not just whether Docker is configured/enabled.

Actual

• Server stays in Error state, retrying (observed retry_count: 21).
• last_error / health detail is a wall of repeated:

  failed to connect: stdio transport (command="docker", docker_isolation=true):
  server process exited before completing the MCP initialize handshake; recent stderr:
    | zsh:1: command not found: docker
    | zsh:1: command not found: docker
    | ... (repeated ~20x)
  

• Meanwhile upstream_servers list reports "docker_status":{"available":true,"global_enabled":true,...} and per-server "docker_available":true — which is misleading, since the CLI is not actually invocable.

Suggested fixes

1. PATH enhancement / Docker discovery: when resolving docker, also probe well-known Docker Desktop locations, especially /Applications/Docker.app/Contents/Resources/bin on macOS (and the equivalent on Windows/Linux). If found, prepend it to the spawn PATH or invoke via absolute path.
2. Accurate availability check: make docker_available test actual binary resolvability on the PATH used for spawning (e.g. exec.LookPath("docker") against that PATH), not just config/daemon presence.
3. Better diagnostics: detect command not found: <cmd> from spawn stderr and replace the repeated raw output with a single actionable message pointing the user to install/symlink the CLI; consider de-duplicating the repeated stderr lines and capping retries with a clearer terminal error.

Workaround (for other users hitting this)

Symlink the bundled CLI into a PATH dir mcpproxy already uses, e.g.:

ln -sf "/Applications/Docker.app/Contents/Resources/bin/docker" /opt/homebrew/bin/docker

(or enable Docker Desktop's "Install CLI tools" so it symlinks into /usr/local/bin), then restart the affected servers.

[algis-dumbris]

Update: v0.39.1 — partially fixed, core issue remains

Tested on mcpproxy v0.39.1 (darwin/arm64, macOS 26.5.1, Docker Desktop 29.5.3), with the docker CLI still not on the user PATH (no symlink in /usr/local/bin or /opt/homebrew/bin).

✅ Improved

• Detection added: upstream_servers list now reports the bundled CLI:

  "docker_status": { "available": true, "docker_path": "/Applications/Docker.app/Contents/Resources/bin/docker", ... }

• Actionable error instead of a raw dump:

  Docker CLI not found on PATH. Install Docker Desktop CLI tools, or it is bundled at /Applications/Docker.app/Contents/Resources/bin/docker — restart the affected servers.

• Repeated stderr collapsed: command not found: docker (repeated 7×).

❌ Still broken (the core bug)

Docker-based servers still fail to start. mcpproxy now discovers docker_path but does not use it when spawning the server — it still invokes bare docker, which is unresolvable on the spawn PATH:

failed to connect: stdio transport (command="docker", docker_isolation=true):
server process exited before completing the MCP initialize handshake; recent stderr:
Docker CLI not found on PATH. Install Docker Desktop CLI tools, or it is bundled at
/Applications/Docker.app/Contents/Resources/bin/docker — restart the affected servers.
  | zsh:1: command not found: docker (repeated 7×): transport error: transport closed

Both jira-gcore and slack-gcore remain in Error state.

Ask

Please wire the discovered docker_path into the actual spawn — either invoke docker by its absolute path, or prepend its directory (/Applications/Docker.app/Contents/Resources/bin) to the PATH used to launch upstream servers. Right now detection + diagnostics are correct, but the spawn path isn't using them, so the failure persists.

Manual workaround still required:

ln -sf "/Applications/Docker.app/Contents/Resources/bin/docker" /opt/homebrew/bin/docker