Skip to content

Latest commit

 

History

History
114 lines (86 loc) · 3.97 KB

MCPX_DOCKER_MISSING_TOOLCHAIN.md

File metadata and controls

114 lines (86 loc) · 3.97 KB
id MCPX_DOCKER_MISSING_TOOLCHAIN
title MCPX_DOCKER_MISSING_TOOLCHAIN
sidebar_label MISSING_TOOLCHAIN
description The Docker isolation image is missing a tool the server shells out to at runtime (most often git).

MCPX_DOCKER_MISSING_TOOLCHAIN

Severity: error Domain: Docker

What happened

The container started and the server's interpreter ran, but a tool the server shells out to is not installed in the image. The failure text comes from inside the container, e.g.:

Git executable not found. Ensure that Git is installed and available.
  × Failed to resolve `--with` requirement
  ╰─▶ Git operation failed
sh: 1: git: not found

This is a different failure from MCPX_DOCKER_EXEC_NOT_FOUND, which is the container's entrypoint interpreter missing — reported by the OCI runtime before the server process runs at all.

Common cause: a git dependency in a slim Python image

By far the most common case is an MCP server distributed only as a git URL:

{
  "name": "my-server",
  "command": "uvx",
  "args": ["--from", "my-server@git+https://github.com/o/r", "my-server"]
}

uv clones the repository with git, and the Python default image is Astral's slim uv image, which does not contain git:

$ docker run --rm --entrypoint sh ghcr.io/astral-sh/uv:python3.13-bookworm-slim -c 'git --version'
sh: 1: git: not found
$ docker run --rm --entrypoint sh ghcr.io/astral-sh/uv:python3.13-bookworm -c 'git --version'
git version 2.39.5

Is this handled automatically?

Yes, for git dependencies with no per-server image override. MCPProxy detects a git+ URL in a Python package runner's arguments and swaps in a git-capable image: whatever docker_isolation.default_images.uvx-git names if you set it, otherwise ghcr.io/astral-sh/uv:python3.13-bookworm (pulled from docker_isolation.registry when you configured one). Servers without a git dependency keep the small slim image.

So if you still see this code, one of these applies:

Situation Fix
The server pins isolation.image The override opts out of the automatic selection. Remove it, or pin an image that ships the tool.
default_images.uvx-git was retargeted to an image without git Point it at an image that has git.
default_images.uvx-git was set to "" That is the opt-out — the server keeps your uvx/python image. Remove the empty value, or pin an image that ships git.
You retargeted default_images.uvx/python at your own registry and never set uvx-git MCPProxy will not pull a public image behind a mirrored install, so the server ran on your image (a warning naming this key is in the log). Point uvx-git at a git-capable image in your registry.
The server is a node/npx (or other non-Python) runner The selection is Python-only, because node:22 already ships git. Pin an isolation.image that has the tool.
The missing tool is not git (e.g. make, gcc, cargo) There is no automatic selection for it — pin an isolation.image that ships it.
You are running an older MCPProxy Upgrade, or set the image explicitly.

How to fix

Remove a per-server override so the automatic selection applies

{ "name": "my-server", "command": "uvx", "args": ["--from", "my-server@git+https://github.com/o/r", "my-server"] }

Or point the shared key at your own image

{
  "docker_isolation": {
    "default_images": { "uvx-git": "my-registry.example/uv-git:1" }
  }
}

Or pin this one server to an image that ships the tool

{ "isolation": { "image": "ghcr.io/astral-sh/uv:python3.13-bookworm" } }

Verify the image has the tool

docker run --rm --entrypoint sh <image> -c 'git --version'

Related