Skip to content
Merged
9 changes: 5 additions & 4 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -925,9 +925,10 @@ See [Logging Documentation](logging.md) for complete details.
"docker_isolation": {
"enabled": false,
"default_images": {
"python": "python:3.11",
"node": "node:20",
"npx": "node:20"
"python": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim",
"uvx": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim",
"node": "node:22",
"npx": "node:22"
},
"registry": "docker.io",
"network_mode": "bridge",
Expand All @@ -945,7 +946,7 @@ See [Logging Documentation](logging.md) for complete details.
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | boolean | `false` | Enable Docker isolation globally |
| `default_images` | object | See below | Map of runtime type to Docker image |
| `default_images` | object | See below | Map of runtime type to Docker image, merged over the built-in map (a partial map only overrides the keys it lists). The optional `uvx-git` key — **not** part of the built-in map — overrides the git-capable image used instead of the Python default when a Python package runner installs from a `git+` URL (the slim uv image has no git); set it to `""` to opt out. Setting it always wins, including at the value MCPProxy ships. Leave it unset and MCPProxy picks the image: your own `uvx`/`python` image if you retargeted it at your registry, otherwise `ghcr.io/astral-sh/uv:python3.13-bookworm` — qualified with `registry` when you set one |
| `registry` | string | `"docker.io"` | Docker registry to use |
| `network_mode` | string | `"bridge"` | Docker network mode |
| `memory_limit` | string | `"512m"` | Memory limit for containers |
Expand Down
73 changes: 63 additions & 10 deletions docs/docker-isolation.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,15 +96,15 @@ Add to your `~/.mcpproxy/mcp_config.json`:
"network_mode": "bridge",
"registry": "docker.io",
"default_images": {
"python": "python:3.11",
"python3": "python:3.11",
"uvx": "python:3.11",
"pip": "python:3.11",
"pipx": "python:3.11",
"node": "node:20",
"npm": "node:20",
"npx": "node:20",
"yarn": "node:20",
"python": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim",
"python3": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim",
"uvx": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim",
"pip": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim",
"pipx": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim",
"node": "node:22",
"npm": "node:22",
"npx": "node:22",
"yarn": "node:22",
"go": "golang:1.21-alpine",
"cargo": "rust:1.75-slim",
"rustc": "rust:1.75-slim",
Expand All @@ -131,9 +131,62 @@ Add to your `~/.mcpproxy/mcp_config.json`:
| `timeout` | Container startup timeout | `"30s"` |
| `network_mode` | Docker network mode | `"bridge"` |
| `registry` | Docker registry to use | `"docker.io"` |
| `default_images` | Runtime to image mappings | See above |
| `default_images` | Runtime to image mappings. The optional `uvx-git` key (not shipped in the defaults) overrides the git-capable image used when a Python runner installs from a `git+` URL | See above |
| `extra_args` | Additional docker run arguments | `[]` |

### Git dependencies (`uvx-git`)

The Python default image is Astral's **slim** `uv` image, which does not contain
`git`. A server installed straight from a repository —

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

— cannot resolve without it, and fails with `Git executable not found` /
`Git operation failed` ([`MCPX_DOCKER_MISSING_TOOLCHAIN`](errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md)).

MCPProxy detects the `git+` URL in a Python package runner's arguments and runs
that server only on a git-capable image — everyone else keeps the small slim
image. By default that is `ghcr.io/astral-sh/uv:python3.13-bookworm`, which
ships git. Set the **`uvx-git`** key to use your own mirror or a custom build:

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

`default_images` from your config file is merged **over** the built-in map, so a
partial map like the one above only changes the keys it lists — every other
runtime keeps its built-in image.

**Mirrored / air-gapped registries.** `uvx-git` is deliberately *not* part of
the built-in map, so its presence in your config means exactly one thing: you
chose that image, and it is used — even if you set it to the same public value
MCPProxy ships. Two things follow:

- If you set `registry`, the built-in git-capable image is pulled from **your**
registry (`<registry>/astral-sh/uv:python3.13-bookworm`) rather than from
`ghcr.io`.
- If you retargeted `uvx`/`python` at your own registry and never set
`uvx-git`, the server runs on **your** image instead of MCPProxy reaching
outside your registry for a public one, and a warning naming this key is
logged. Point `uvx-git` at a git-capable image to get the substitution back:

```json
{ "docker_isolation": { "default_images": { "uvx-git": "mirror.internal/astral/uv:python3.13-bookworm" } } }
```

To turn the substitution off entirely, set the key to an empty string; those
servers then keep whatever `uvx`/`python` image you configured:

```json
{ "docker_isolation": { "default_images": { "uvx-git": "" } } }
```

A per-server `isolation.image` override always wins over this selection, so a
pinned image must ship git itself. `node`/`npx` need no equivalent: `node:22`
already includes git, and the substitution never applies to them.

### Per-Server Configuration

You can override isolation settings per server:
Expand Down
1 change: 1 addition & 0 deletions docs/errors/MCPX_DOCKER_EXEC_NOT_FOUND.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,7 @@ docker run --rm <image> which uvx # or: node, npx, python3 …
## Related

- [Docker Isolation](../features/docker-isolation.md)
- [`MCPX_DOCKER_MISSING_TOOLCHAIN`](MCPX_DOCKER_MISSING_TOOLCHAIN.md) — the interpreter is present but a tool it calls (e.g. `git`) is not
- [`MCPX_DOCKER_IMAGE_PULL_FAILED`](MCPX_DOCKER_IMAGE_PULL_FAILED.md)
- [`MCPX_DOCKER_DAEMON_DOWN`](MCPX_DOCKER_DAEMON_DOWN.md)
</content>
Expand Down
114 changes: 114 additions & 0 deletions docs/errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
---
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`](MCPX_DOCKER_EXEC_NOT_FOUND.md), 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:

```jsonc
{
"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:

```console
$ 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

```jsonc
{ "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

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

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

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

### Verify the image has the tool

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

## Related

- [Docker Isolation](../features/docker-isolation.md)
- [`MCPX_DOCKER_EXEC_NOT_FOUND`](MCPX_DOCKER_EXEC_NOT_FOUND.md)
- [`MCPX_DOCKER_IMAGE_PULL_FAILED`](MCPX_DOCKER_IMAGE_PULL_FAILED.md)
1 change: 1 addition & 0 deletions docs/errors/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,7 @@ Run `mcpproxy doctor list-codes` for the machine-readable list.
- [`MCPX_DOCKER_DAEMON_DOWN`](MCPX_DOCKER_DAEMON_DOWN.md) — daemon unreachable
- [`MCPX_DOCKER_IMAGE_PULL_FAILED`](MCPX_DOCKER_IMAGE_PULL_FAILED.md) — pull failed
- [`MCPX_DOCKER_EXEC_NOT_FOUND`](MCPX_DOCKER_EXEC_NOT_FOUND.md) — image missing the runtime interpreter (e.g. no `uvx`)
- [`MCPX_DOCKER_MISSING_TOOLCHAIN`](MCPX_DOCKER_MISSING_TOOLCHAIN.md) — image missing a tool the server calls at runtime (e.g. no `git` for a `git+https://…` dependency)
- [`MCPX_DOCKER_NO_PERMISSION`](MCPX_DOCKER_NO_PERMISSION.md) — socket permission denied
- [`MCPX_DOCKER_SNAP_APPARMOR`](MCPX_DOCKER_SNAP_APPARMOR.md) — snap Docker AppArmor block

Expand Down
73 changes: 63 additions & 10 deletions docs/features/docker-isolation.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,15 +89,15 @@ Add to your `~/.mcpproxy/mcp_config.json`:
"network_mode": "bridge",
"registry": "docker.io",
"default_images": {
"python": "python:3.11",
"python3": "python:3.11",
"uvx": "python:3.11",
"pip": "python:3.11",
"pipx": "python:3.11",
"node": "node:20",
"npm": "node:20",
"npx": "node:20",
"yarn": "node:20",
"python": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim",
"python3": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim",
"uvx": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim",
"pip": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim",
"pipx": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim",
"node": "node:22",
"npm": "node:22",
"npx": "node:22",
"yarn": "node:22",
"go": "golang:1.21-alpine",
"cargo": "rust:1.75-slim",
"rustc": "rust:1.75-slim",
Expand All @@ -124,9 +124,62 @@ Add to your `~/.mcpproxy/mcp_config.json`:
| `timeout` | Container startup timeout | `"30s"` |
| `network_mode` | Docker network mode | `"bridge"` |
| `registry` | Docker registry to use | `"docker.io"` |
| `default_images` | Runtime to image mappings | See above |
| `default_images` | Runtime to image mappings. The optional `uvx-git` key (not shipped in the defaults) overrides the git-capable image used when a Python runner installs from a `git+` URL | See above |
| `extra_args` | Additional docker run arguments | `[]` |

### Git dependencies (`uvx-git`)

The Python default image is Astral's **slim** `uv` image, which does not contain
`git`. A server installed straight from a repository —

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

— cannot resolve without it, and fails with `Git executable not found` /
`Git operation failed` ([`MCPX_DOCKER_MISSING_TOOLCHAIN`](../errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md)).

MCPProxy detects the `git+` URL in a Python package runner's arguments and runs
that server only on a git-capable image — everyone else keeps the small slim
image. By default that is `ghcr.io/astral-sh/uv:python3.13-bookworm`, which
ships git. Set the **`uvx-git`** key to use your own mirror or a custom build:

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

`default_images` from your config file is merged **over** the built-in map, so a
partial map like the one above only changes the keys it lists — every other
runtime keeps its built-in image.

**Mirrored / air-gapped registries.** `uvx-git` is deliberately *not* part of
the built-in map, so its presence in your config means exactly one thing: you
chose that image, and it is used — even if you set it to the same public value
MCPProxy ships. Two things follow:

- If you set `registry`, the built-in git-capable image is pulled from **your**
registry (`<registry>/astral-sh/uv:python3.13-bookworm`) rather than from
`ghcr.io`.
- If you retargeted `uvx`/`python` at your own registry and never set
`uvx-git`, the server runs on **your** image instead of MCPProxy reaching
outside your registry for a public one, and a warning naming this key is
logged. Point `uvx-git` at a git-capable image to get the substitution back:

```json
{ "docker_isolation": { "default_images": { "uvx-git": "mirror.internal/astral/uv:python3.13-bookworm" } } }
```

To turn the substitution off entirely, set the key to an empty string; those
servers then keep whatever `uvx`/`python` image you configured:

```json
{ "docker_isolation": { "default_images": { "uvx-git": "" } } }
```

A per-server `isolation.image` override always wins over this selection, so a
pinned image must ship git itself. `node`/`npx` need no equivalent: `node:22`
already includes git, and the substitution never applies to them.

### Per-Server Configuration

You can override isolation settings per server:
Expand Down
10 changes: 10 additions & 0 deletions internal/config/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -1560,6 +1560,16 @@ func DefaultDockerIsolationConfig() *DockerIsolationConfig {
"pip": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim",
"pipx": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim",

// NOTE: no GitCapableImageKey ("uvx-git") entry. The slim image
// above has no git, so a server installed from a git URL
// (`uvx --from …git+https://…`) cannot resolve at all, and
// mcpproxy substitutes a git-capable image per-server — but that
// substitution is decided in code (core.resolveDefaultImage), not
// by seeding a value here. Seeding it would write a public ghcr.io
// URL into every operator's config file on the next save and make
// the key's presence unable to mean "the operator chose this".
// See internal/config/isolation_git.go (#1143).

// Node.js environments - full image for git deps and native modules (LTS until Apr 2028)
"node": "node:22",
"npm": "node:22",
Expand Down
Loading
Loading