From c472db59cc2930050d295648ba1913525aa7c30e Mon Sep 17 00:00:00 2001 From: Algis Dumbris Date: Wed, 11 Nov 2026 15:43:09 +0200 Subject: [PATCH 1/4] docs(docker): compose example with stdio servers in sidecars (#1707) --- .github/workflows/compose-example.yml | 38 +++++ docs/operations/compose-stdio-sidecars.md | 131 ++++++++++++++++++ examples/compose-stdio-sidecars/.gitignore | 3 + examples/compose-stdio-sidecars/README.md | 8 ++ .../compose-stdio-sidecars/docker-compose.yml | 83 +++++++++++ .../compose-stdio-sidecars/gen-secrets.sh | 18 +++ .../mcpproxy/mcp_config.json | 17 +++ .../compose-stdio-sidecars/sidecar/Dockerfile | 16 +++ examples/compose-stdio-sidecars/test.sh | 63 +++++++++ website/sidebars.js | 1 + 10 files changed, 378 insertions(+) create mode 100644 .github/workflows/compose-example.yml create mode 100644 docs/operations/compose-stdio-sidecars.md create mode 100644 examples/compose-stdio-sidecars/.gitignore create mode 100644 examples/compose-stdio-sidecars/README.md create mode 100644 examples/compose-stdio-sidecars/docker-compose.yml create mode 100755 examples/compose-stdio-sidecars/gen-secrets.sh create mode 100644 examples/compose-stdio-sidecars/mcpproxy/mcp_config.json create mode 100644 examples/compose-stdio-sidecars/sidecar/Dockerfile create mode 100755 examples/compose-stdio-sidecars/test.sh diff --git a/.github/workflows/compose-example.yml b/.github/workflows/compose-example.yml new file mode 100644 index 000000000..e2d812626 --- /dev/null +++ b/.github/workflows/compose-example.yml @@ -0,0 +1,38 @@ +name: Compose example + +# Validates examples/compose-stdio-sidecars and runs it end to end. Path-filtered: +# it does not run on unrelated changes. + +on: + pull_request: + paths: + - 'examples/compose-stdio-sidecars/**' + - '.github/workflows/compose-example.yml' + push: + branches: [main] + paths: + - 'examples/compose-stdio-sidecars/**' + - '.github/workflows/compose-example.yml' + workflow_dispatch: + +permissions: + contents: read + +jobs: + compose-stdio-sidecars: + name: Compose stdio sidecars + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - name: Validate the compose file + working-directory: examples/compose-stdio-sidecars + run: | + ./gen-secrets.sh + docker compose config --quiet + python3 -c 'import json; json.load(open("mcpproxy/mcp_config.json"))' + + - name: Bring the stack up and check it + working-directory: examples/compose-stdio-sidecars + run: ./test.sh diff --git a/docs/operations/compose-stdio-sidecars.md b/docs/operations/compose-stdio-sidecars.md new file mode 100644 index 000000000..ce8b0813f --- /dev/null +++ b/docs/operations/compose-stdio-sidecars.md @@ -0,0 +1,131 @@ +--- +id: compose-stdio-sidecars +title: Docker Compose with stdio servers in sidecars +sidebar_label: Compose with Sidecars +description: 'Run mcpproxy in Docker Compose with each stdio MCP server in its own sidecar container on an internal network, so a compromised stdio package cannot read the data volume, the API key or the OAuth token database.' +keywords: [docker compose, sidecar, stdio, supergateway, internal network, isolation, data volume, require_mcp_auth, file secrets, stop_grace_period] +--- + +# Docker Compose with stdio servers in sidecars + +When mcpproxy runs a stdio MCP server itself, the server is a child process in the +same container as the data directory. A compromised or malicious stdio package can then +read `/data`, which holds the proxy's `api_key` and the OAuth token database. This page +shows a Compose layout that avoids that: each stdio server runs in **its own sidecar +container**, wrapped to streamable HTTP, on a network with no route out. mcpproxy +connects to it over HTTP like any other remote server. + +The layout comes from [issue #1707](https://github.com/smart-mcp-proxy/mcpproxy-go/issues/1707), +contributed and tested by [@james-crowley](https://github.com/james-crowley). The ready-to-copy +files are in [`examples/compose-stdio-sidecars/`](https://github.com/smart-mcp-proxy/mcpproxy-go/tree/main/examples/compose-stdio-sidecars) +and CI starts the stack on every change to them. + +## Layout + +``` + 127.0.0.1:18080 + │ + ┌─────────── front (normal bridge) ───────────┐ + │ │ │ + │ ┌────┴─────┐ │ + │ │ mcpproxy │──── /data volume (this container only) + │ └────┬─────┘ │ + └────────────────────┼────────────────────────┘ + ┌────── back (internal: true, no route out) ──┐ + │ │ http://everything:8000/mcp + Bearer key + │ ┌──────┴───────┐ │ + │ │ sidecar │ supergateway --stateful + │ │ (stdio srv) │ read-only, no capabilities + │ └──────────────┘ │ + └─────────────────────────────────────────────┘ +``` + +- **`front`** is a normal bridge. Only mcpproxy is on it, and its port is published on + `127.0.0.1` only. +- **`back`** is `internal: true`: no gateway, no route to the internet. mcpproxy and the + sidecars are on it; a sidecar is on no other network. +- The proxy's `/data` volume is mounted **only in the mcpproxy container**. No container + gets the Docker socket. +- Each sidecar requires an API key, read from a Compose file secret. mcpproxy sends it + as `Authorization: Bearer ${file:/run/secrets/sidecar_api_key}`. +- The sidecar runs read-only as an unprivileged user with `cap_drop: [ALL]` and + `no-new-privileges`. + +## Run it + +```bash +cd examples/compose-stdio-sidecars +./gen-secrets.sh # creates ./secrets/{mcpproxy_api_key,sidecar_api_key} +docker compose up --build --wait +curl -H "X-API-Key: $(cat secrets/mcpproxy_api_key)" \ + http://127.0.0.1:18080/api/v1/servers/everything/tools +``` + +The demo server is `@modelcontextprotocol/server-everything`, so the example needs no +credentials. To wrap a different server, change `SERVER_PKG` in the `sidecar/Dockerfile` +build argument and the `--stdio=` command in `docker-compose.yml`, add one sidecar service +per server, and add a matching entry to `mcpproxy/mcp_config.json`. + +The mcpproxy image needs **v0.72.0 or newer**: `${file:}` references and +`MCPPROXY_API_KEY_FILE` are not in earlier releases. The example pins v0.73.0 by digest. + +## What each setting is for + +| Setting | Why | +|---|---| +| `--stateful` | supergateway's default is stateless: every request gets a fresh child process, so a server that keeps per-session state loses it between calls. See [the stateless pitfall](#the-stateless-pitfall). | +| `--apiKeyFile` | The sidecar refuses requests without its key, so another container on `back` cannot use it. | +| `--healthEndpoint /healthz --healthCheck server` and a Compose `healthcheck` | `/healthz` really starts the wrapped server (initialize plus ping) and answers without the API key. With `depends_on: condition: service_healthy`, mcpproxy starts only once the sidecar works, instead of logging `connection refused` and retrying. | +| `--sessionTimeout=120000` | Reaps a session mcpproxy abandoned after 2 minutes instead of the 30-minute default. See [limits](#limits). | +| `stop_grace_period: 60s` | mcpproxy's graceful-shutdown bound is 60 s; Compose's default of 10 s would cut it short. See [Shutdown Behavior](/operations/shutdown-behavior). | +| `./mcpproxy:/config:ro` | A directory, not a single file: mcpproxy saves its config by `rename(2)`, which fails on a single-file bind mount. Read-only keeps the declarative file as the source of truth, so mcpproxy does not rewrite your copy. | +| `"require_mcp_auth": true` | mcpproxy has to be on `back` to reach the sidecars, so a sidecar can reach `http://mcpproxy:8080/mcp`. Without MCP authentication a compromised sidecar could use the proxy. With it, the sidecar gets `401`. | +| `"quarantined": false`, `"trust_mode": "manual"` | The sidecar is an operator-authored entry, so it starts approved; `manual` still holds any later tool change for review. Remove `quarantined` to review the server first. | +| Pinned images (by digest) | A digest cannot be moved under you. Bump the tag and digest together. | + +## Which servers go in a sidecar + +Keep the proxy's own stdio spawning for servers you trust and that need the host or +the proxy's environment. Put a server in a sidecar when you do not fully trust the package, +or when it needs something the proxy container should not have (a browser, a cloud CLI, +different credentials). Pass a sidecar only the secrets that server needs, through its own +`environment` or file secrets, never through the proxy's. + +## The stateless pitfall + +supergateway 4.2.0 runs stateless unless told otherwise. In the test behind this example +a counter server called three times in one MCP session returned `count=1, count=1, +count=1` and no `Mcp-Session-Id`; with `--stateful` it returned `1, 2, 3`, one child per +session. Playwright keeps its open page between calls only with `--stateful`. Any server +with state needs the flag, and the example sets it on every sidecar. + +## Limits + +- **One upstream session per server for all clients.** mcpproxy keeps a single session to + each upstream, so `--stateful` is per proxy, not per MCP client: a second client sees + the first client's browser page. +- **A restart loses state.** Each mcpproxy start opens a new session and so a new child + process. If a sidecar restarts, mcpproxy re-initializes on the `404` by itself, but state + such as a Playwright page is gone. +- **Abandoned sessions linger up to `--sessionTimeout`.** mcp-go's `DELETE` that closes a + session does not carry the configured headers, so a key-protected sidecar refuses it and + the session's child process stays until the timeout. mcpproxy's own ping keeps a live + session alive, which is why a short timeout is safe. +- **Not every server was tried.** The layout was tested with the demo server, Terraform, + Grafana, Playwright and chrome-devtools MCP servers. Browser sidecars are large (about + 1 GB of image and 350-500 MB of memory with Chromium running). Servers that need + network access, such as most API servers, need the sidecar on a non-internal network + too, which gives up the no-egress guarantee for that sidecar; put it on its own network, + not `back`. +- **supergateway is one wrapper.** Any stdio-to-HTTP wrapper that supports sessions and an + API key fits the same layout; supergateway is what has been tested. +- **The example is not TLS.** It publishes on `127.0.0.1`. To expose it, put a reverse + proxy in front and see [Reverse Proxy Deployment](/operations/reverse-proxy). + +## Checks the CI job runs + +`examples/compose-stdio-sidecars/test.sh` builds the sidecar, starts the stack, waits for +both health checks and then checks that the proxy lists `everything:echo` with the API +key; that `/mcp` without a credential and the sidecar without its key both return `401`; +that the sidecar cannot reach `1.1.1.1` or `example.com`; that `/data` does not exist in +the sidecar; and that no container mounts the Docker socket. diff --git a/examples/compose-stdio-sidecars/.gitignore b/examples/compose-stdio-sidecars/.gitignore new file mode 100644 index 000000000..bdd91b76d --- /dev/null +++ b/examples/compose-stdio-sidecars/.gitignore @@ -0,0 +1,3 @@ +secrets/ +# the repo-wide .gitignore excludes mcp_config.json; this one is the example config +!mcp_config.json diff --git a/examples/compose-stdio-sidecars/README.md b/examples/compose-stdio-sidecars/README.md new file mode 100644 index 000000000..42b18b4e7 --- /dev/null +++ b/examples/compose-stdio-sidecars/README.md @@ -0,0 +1,8 @@ +# mcpproxy with stdio servers in sidecars + +Docker Compose example: mcpproxy plus a stdio MCP server in its own sidecar container on an `internal: true` network. Walkthrough and limits: [docs/operations/compose-stdio-sidecars.md](../../docs/operations/compose-stdio-sidecars.md). + +```bash +./gen-secrets.sh && docker compose up --build --wait +./test.sh # optional: runs the checks CI runs, then tears the stack down +``` diff --git a/examples/compose-stdio-sidecars/docker-compose.yml b/examples/compose-stdio-sidecars/docker-compose.yml new file mode 100644 index 000000000..084306cad --- /dev/null +++ b/examples/compose-stdio-sidecars/docker-compose.yml @@ -0,0 +1,83 @@ +# mcpproxy with a stdio MCP server running in its own sidecar container. +# Walkthrough: docs/operations/compose-stdio-sidecars.md +# +# front : normal bridge. mcpproxy only; published on 127.0.0.1. +# back : internal: true (no gateway, no route out). mcpproxy and the sidecars. +# +# A sidecar has no route to the internet, mounts nothing from mcpproxy (the +# /data volume, with the API key and the OAuth token database, is mounted in the +# mcpproxy container only), and no container gets the docker socket. +# +# Run ./gen-secrets.sh once, then: docker compose up --build --wait + +name: mcpproxy-sidecars + +x-sidecar: &sidecar + restart: unless-stopped + networks: [back] + secrets: [sidecar_api_key] + read_only: true + tmpfs: [/tmp] + cap_drop: [ALL] + security_opt: ["no-new-privileges:true"] + healthcheck: + # supergateway answers /healthz without the API key. With --healthCheck server + # it starts the stdio child, runs initialize + ping and stops it again, so + # "healthy" means the wrapped server really starts. + test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:8000/healthz').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"] + interval: 30s + timeout: 15s + retries: 3 + start_period: 20s + +services: + mcpproxy: + # Pinned by digest (v0.73.0). ${file:} references and MCPPROXY_API_KEY_FILE + # need v0.72.0 or newer. Bump tag and digest together. + image: ghcr.io/smart-mcp-proxy/mcpproxy-server:v0.73.0@sha256:0f6cd65a3bc63f117d7f0fff7c539836c076f1834db620bf5fa9bbdd62578919 + command: ["serve", "--listen=0.0.0.0:8080", "--config=/config/mcp_config.json", "--data-dir=/data"] + environment: + MCPPROXY_API_KEY_FILE: /run/secrets/mcpproxy_api_key + secrets: [mcpproxy_api_key, sidecar_api_key] + volumes: + # A directory, not a single file: mcpproxy saves its config by rename(2), + # which fails on a single-file bind mount. + - ./mcpproxy:/config:ro + - mcpproxy_data:/data # mounted ONLY here + ports: ["127.0.0.1:${MCPPROXY_PORT:-18080}:8080"] + networks: [front, back] + restart: unless-stopped + # The default stop_grace_period (10 s) is shorter than mcpproxy's 60 s + # graceful-shutdown bound. + stop_grace_period: 60s + depends_on: + everything: {condition: service_healthy} + + everything: + <<: *sidecar + build: + context: ./sidecar + args: + SERVER_PKG: "@modelcontextprotocol/server-everything@2.3.0" + image: mcpproxy-sidecar-everything:2.3.0 + command: + - --stdio=mcp-server-everything + - --outputTransport=streamableHttp + - --stateful # one child per MCP session; the default is stateless + - --sessionTimeout=120000 # reap abandoned sessions after 2 min instead of 30 + - --port=8000 + - --apiKeyFile=/run/secrets/sidecar_api_key + - --healthEndpoint=/healthz + - --healthCheck=server + +networks: + front: {} + back: + internal: true + +volumes: + mcpproxy_data: {} + +secrets: + mcpproxy_api_key: {file: ./secrets/mcpproxy_api_key} + sidecar_api_key: {file: ./secrets/sidecar_api_key} diff --git a/examples/compose-stdio-sidecars/gen-secrets.sh b/examples/compose-stdio-sidecars/gen-secrets.sh new file mode 100755 index 000000000..7f84f82f4 --- /dev/null +++ b/examples/compose-stdio-sidecars/gen-secrets.sh @@ -0,0 +1,18 @@ +#!/bin/sh +# Create the two file secrets the compose file mounts. Safe to re-run: existing +# files are kept, so a running stack's keys do not change under it. +set -eu +cd "$(dirname "$0")" +umask 077 +mkdir -p secrets +for name in mcpproxy_api_key sidecar_api_key; do + if [ ! -s "secrets/$name" ]; then + # 256 random bits as hex. + printf '%s' "$(od -An -N32 -tx1 /dev/urandom | tr -d ' \n')" > "secrets/$name" + fi + # The sidecar runs as uid 1000 and mcpproxy as root, and both must read the + # file through the bind mount. The directory (0700) is what keeps other host + # users out, so the files themselves are world-readable. + chmod 0644 "secrets/$name" +done +echo "secrets ready in $(pwd)/secrets" diff --git a/examples/compose-stdio-sidecars/mcpproxy/mcp_config.json b/examples/compose-stdio-sidecars/mcpproxy/mcp_config.json new file mode 100644 index 000000000..e4dfd2f7f --- /dev/null +++ b/examples/compose-stdio-sidecars/mcpproxy/mcp_config.json @@ -0,0 +1,17 @@ +{ + "listen": "0.0.0.0:8080", + "enable_socket": false, + "data_dir": "/data", + "require_mcp_auth": true, + "mcpServers": [ + { + "name": "everything", + "protocol": "streamable-http", + "url": "http://everything:8000/mcp", + "headers": { "Authorization": "Bearer ${file:/run/secrets/sidecar_api_key}" }, + "quarantined": false, + "trust_mode": "manual", + "enabled": true + } + ] +} diff --git a/examples/compose-stdio-sidecars/sidecar/Dockerfile b/examples/compose-stdio-sidecars/sidecar/Dockerfile new file mode 100644 index 000000000..83b11969c --- /dev/null +++ b/examples/compose-stdio-sidecars/sidecar/Dockerfile @@ -0,0 +1,16 @@ +# One stdio MCP server wrapped to streamable HTTP by supergateway. +# Change SERVER_PKG (and the --stdio command in docker-compose.yml) to wrap a +# different server; run one sidecar per server. +FROM node:24-bookworm-slim@sha256:01d566e8d94d8c619591d78652babfccd3c6992a3dffa9ed5ab39e11cf6c70e9 + +ARG SUPERGATEWAY_VERSION=4.2.0 +ARG SERVER_PKG=@modelcontextprotocol/server-everything@2.3.0 + +RUN npm install -g --no-audit --no-fund "supergateway@${SUPERGATEWAY_VERSION}" "${SERVER_PKG}" \ + && npm cache clean --force + +# The base image's unprivileged user (uid 1000). The compose file also runs the +# container read-only with every capability dropped. +USER node +WORKDIR /home/node +ENTRYPOINT ["supergateway"] diff --git a/examples/compose-stdio-sidecars/test.sh b/examples/compose-stdio-sidecars/test.sh new file mode 100755 index 000000000..48e645b7e --- /dev/null +++ b/examples/compose-stdio-sidecars/test.sh @@ -0,0 +1,63 @@ +#!/bin/sh +# Bring the example up, check it does what the walkthrough claims, tear it down. +# Needs docker compose v2 and curl. Used by .github/workflows/compose-example.yml. +set -eu +cd "$(dirname "$0")" + +PORT="${MCPPROXY_PORT:-18080}" +export MCPPROXY_PORT="$PORT" +fail() { echo "FAIL: $*" >&2; docker compose logs --tail=80 >&2 || true; exit 1; } +cleanup() { docker compose down -v --remove-orphans >/dev/null 2>&1 || true; } +trap cleanup EXIT + +./gen-secrets.sh +KEY="$(cat secrets/mcpproxy_api_key)" + +docker compose up --build --wait --wait-timeout 300 || fail "stack did not become healthy" + +# 1. The proxy lists the sidecar's tools. The tool list arrives after the first +# discovery pass, so poll for it. +n=0 +until curl -fsS -H "X-API-Key: $KEY" "http://127.0.0.1:$PORT/api/v1/servers/everything/tools" 2>/dev/null | grep -q '"name":"echo"'; do + n=$((n + 1)) + [ "$n" -le 40 ] || fail "everything:echo never appeared through the proxy" + sleep 3 +done +echo "ok: tools listed through the proxy" + +# 2. /mcp refuses a request without a credential (require_mcp_auth: true). +code="$(curl -s -o /dev/null -w '%{http_code}' -X POST "http://127.0.0.1:$PORT/mcp" -d '{}')" +[ "$code" = "401" ] || fail "unauthenticated /mcp returned $code, want 401" +echo "ok: /mcp without a credential is refused" + +# 3. The sidecar's own endpoint refuses a request without its key. node is the +# only tool in the sidecar image, so the probes are node one-liners. +code="$(docker compose exec -T everything node -e "fetch('http://127.0.0.1:8000/mcp',{method:'POST'}).then(r=>console.log(r.status))")" +[ "$code" = "401" ] || fail "sidecar /mcp without its key returned $code, want 401" +echo "ok: sidecar refuses a request without its key" + +# 4. The sidecar cannot reach the internet (neither by IP nor by name) ... +if docker compose exec -T everything node -e "fetch('http://1.1.1.1',{signal:AbortSignal.timeout(5000)}).then(()=>process.exit(0),()=>process.exit(1))"; then + fail "sidecar reached 1.1.1.1" +fi +if docker compose exec -T everything node -e "fetch('https://example.com',{signal:AbortSignal.timeout(5000)}).then(()=>process.exit(0),()=>process.exit(1))"; then + fail "sidecar reached example.com" +fi +echo "ok: sidecar has no route out" + +# 5. ... and cannot see the proxy's data directory. +if docker compose exec -T everything test -e /data; then + fail "/data is visible in the sidecar" +fi +echo "ok: /data is not visible in the sidecar" + +# 6. No container has the docker socket. +for svc in mcpproxy everything; do + id="$(docker compose ps -q "$svc")" + if docker inspect -f '{{range .Mounts}}{{.Source}} {{end}}' "$id" | grep -q docker.sock; then + fail "$svc mounts the docker socket" + fi +done +echo "ok: no docker socket" + +echo "PASS" diff --git a/website/sidebars.js b/website/sidebars.js index fcaa6efe0..8654a0dc0 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -172,6 +172,7 @@ const sidebars = { items: [ 'operations/reverse-proxy', 'operations/deploying-for-a-team', + 'operations/compose-stdio-sidecars', 'operations/shutdown-behavior', 'features/observability', 'logging', From 533bee840fe25346cf37b1caf80f17bf5f15a92f Mon Sep 17 00:00:00 2001 From: Algis Dumbris Date: Wed, 11 Nov 2026 20:16:59 +0200 Subject: [PATCH 2/4] fix(examples): isolate compose test project, harden secrets dir, correct health-check docs --- docs/operations/compose-stdio-sidecars.md | 17 +++++++++++++---- examples/compose-stdio-sidecars/README.md | 6 +++++- .../compose-stdio-sidecars/docker-compose.yml | 3 +++ examples/compose-stdio-sidecars/gen-secrets.sh | 6 ++++++ examples/compose-stdio-sidecars/test.sh | 12 ++++++++++-- 5 files changed, 37 insertions(+), 7 deletions(-) diff --git a/docs/operations/compose-stdio-sidecars.md b/docs/operations/compose-stdio-sidecars.md index ce8b0813f..15ce12771 100644 --- a/docs/operations/compose-stdio-sidecars.md +++ b/docs/operations/compose-stdio-sidecars.md @@ -61,9 +61,13 @@ curl -H "X-API-Key: $(cat secrets/mcpproxy_api_key)" \ http://127.0.0.1:18080/api/v1/servers/everything/tools ``` +`gen-secrets.sh` sets `secrets/` to `0700` (and refuses a symlink). The key files inside are +`0644` because the sidecar (uid 1000) and mcpproxy (root) both read them through the bind +mount; the directory is what keeps other host users out. + The demo server is `@modelcontextprotocol/server-everything`, so the example needs no -credentials. To wrap a different server, change `SERVER_PKG` in the `sidecar/Dockerfile` -build argument and the `--stdio=` command in `docker-compose.yml`, add one sidecar service +credentials. To wrap a different server, change `build.args.SERVER_PKG` in `docker-compose.yml` +(it overrides the default in `sidecar/Dockerfile`) and the `--stdio=` command beside it, add one sidecar service per server, and add a matching entry to `mcpproxy/mcp_config.json`. The mcpproxy image needs **v0.72.0 or newer**: `${file:}` references and @@ -124,8 +128,13 @@ with state needs the flag, and the example sets it on every sidecar. ## Checks the CI job runs -`examples/compose-stdio-sidecars/test.sh` builds the sidecar, starts the stack, waits for -both health checks and then checks that the proxy lists `everything:echo` with the API +`examples/compose-stdio-sidecars/test.sh` builds the sidecar, starts the stack, starts the stack +under its own Compose project name (`mcpproxy-sidecars-test`, port 18081), so the +deployment's data volume is never touched and only the test project's containers, network +and volume are removed at the end. Only the sidecar has a Compose health check, so +`up --wait` returns once the sidecar is healthy and the proxy container is running (the +image has no shell or HTTP client for a probe, and `mcpproxy status` exits 0 when the core +is down); the script then polls the proxy until it lists the tools. It checks that the proxy lists `everything:echo` with the API key; that `/mcp` without a credential and the sidecar without its key both return `401`; that the sidecar cannot reach `1.1.1.1` or `example.com`; that `/data` does not exist in the sidecar; and that no container mounts the Docker socket. diff --git a/examples/compose-stdio-sidecars/README.md b/examples/compose-stdio-sidecars/README.md index 42b18b4e7..a8981a4d4 100644 --- a/examples/compose-stdio-sidecars/README.md +++ b/examples/compose-stdio-sidecars/README.md @@ -4,5 +4,9 @@ Docker Compose example: mcpproxy plus a stdio MCP server in its own sidecar cont ```bash ./gen-secrets.sh && docker compose up --build --wait -./test.sh # optional: runs the checks CI runs, then tears the stack down +./test.sh # optional: runs the checks CI runs ``` + +`gen-secrets.sh` keeps `secrets/` at mode `0700`; the two key files inside are `0644` because the sidecar (uid 1000) and mcpproxy (root) must both read them through the bind mount, so the directory is what keeps other host users out. + +`test.sh` runs under its own Compose project (`mcpproxy-sidecars-test`, port 18081), so it can run next to a normal deployment. On exit it removes only that project's containers, network and data volume; the deployment's `mcpproxy_data` volume is not touched. It reuses `secrets/` and the built sidecar image. diff --git a/examples/compose-stdio-sidecars/docker-compose.yml b/examples/compose-stdio-sidecars/docker-compose.yml index 084306cad..dc375c4c1 100644 --- a/examples/compose-stdio-sidecars/docker-compose.yml +++ b/examples/compose-stdio-sidecars/docker-compose.yml @@ -50,6 +50,9 @@ services: # The default stop_grace_period (10 s) is shorter than mcpproxy's 60 s # graceful-shutdown bound. stop_grace_period: 60s + # No healthcheck here: the image is distroless (no shell, curl or wget) and + # `mcpproxy status` exits 0 even when the core is down, so no in-image probe + # is reliable. `up --wait` returns once the container is running. depends_on: everything: {condition: service_healthy} diff --git a/examples/compose-stdio-sidecars/gen-secrets.sh b/examples/compose-stdio-sidecars/gen-secrets.sh index 7f84f82f4..c60718f58 100755 --- a/examples/compose-stdio-sidecars/gen-secrets.sh +++ b/examples/compose-stdio-sidecars/gen-secrets.sh @@ -4,7 +4,13 @@ set -eu cd "$(dirname "$0")" umask 077 +if [ -L secrets ]; then + echo "secrets is a symlink; refusing to use it" >&2 + exit 1 +fi mkdir -p secrets +# mkdir -p keeps the mode of an existing directory, so set it explicitly. +chmod 0700 secrets for name in mcpproxy_api_key sidecar_api_key; do if [ ! -s "secrets/$name" ]; then # 256 random bits as hex. diff --git a/examples/compose-stdio-sidecars/test.sh b/examples/compose-stdio-sidecars/test.sh index 48e645b7e..380c99b85 100755 --- a/examples/compose-stdio-sidecars/test.sh +++ b/examples/compose-stdio-sidecars/test.sh @@ -1,10 +1,16 @@ #!/bin/sh -# Bring the example up, check it does what the walkthrough claims, tear it down. +# Bring the example up under a separate project name, check it does what the +# walkthrough claims, tear that test project down (including its own volume). # Needs docker compose v2 and curl. Used by .github/workflows/compose-example.yml. set -eu cd "$(dirname "$0")" -PORT="${MCPPROXY_PORT:-18080}" +# Run under its own Compose project (own containers, network and data volume) and +# its own port, so `down -v` below removes only what this test created and never +# the data volume of a deployment started with plain `docker compose up`. +# COMPOSE_PROJECT_NAME takes precedence over the file's top-level `name:`. +export COMPOSE_PROJECT_NAME="${COMPOSE_PROJECT_NAME:-mcpproxy-sidecars-test}" +PORT="${MCPPROXY_PORT:-18081}" export MCPPROXY_PORT="$PORT" fail() { echo "FAIL: $*" >&2; docker compose logs --tail=80 >&2 || true; exit 1; } cleanup() { docker compose down -v --remove-orphans >/dev/null 2>&1 || true; } @@ -13,6 +19,8 @@ trap cleanup EXIT ./gen-secrets.sh KEY="$(cat secrets/mcpproxy_api_key)" +# --wait returns once the sidecar is healthy and mcpproxy is running; the proxy +# has no health check of its own, so step 1 polls it. docker compose up --build --wait --wait-timeout 300 || fail "stack did not become healthy" # 1. The proxy lists the sidecar's tools. The tool list arrives after the first From a6da35b210bcee7b45d460a50348c4326a7bf7a7 Mon Sep 17 00:00:00 2001 From: Algis Dumbris Date: Wed, 11 Nov 2026 20:31:31 +0200 Subject: [PATCH 3/4] fix(examples): pin the test project name and fail on probes that cannot run test.sh kept an inherited COMPOSE_PROJECT_NAME, so it could still target a deployment and delete its volume. The project is now fixed and passed with -p on every call. The isolation probes print their answer, so a probe that could not run fails the test. gen-secrets.sh refuses a secret entry that is not a regular file. --- docs/operations/compose-stdio-sidecars.md | 2 +- .../compose-stdio-sidecars/gen-secrets.sh | 6 +++ examples/compose-stdio-sidecars/test.sh | 47 +++++++++++-------- 3 files changed, 34 insertions(+), 21 deletions(-) diff --git a/docs/operations/compose-stdio-sidecars.md b/docs/operations/compose-stdio-sidecars.md index 15ce12771..1f4aa8f80 100644 --- a/docs/operations/compose-stdio-sidecars.md +++ b/docs/operations/compose-stdio-sidecars.md @@ -128,7 +128,7 @@ with state needs the flag, and the example sets it on every sidecar. ## Checks the CI job runs -`examples/compose-stdio-sidecars/test.sh` builds the sidecar, starts the stack, starts the stack +`examples/compose-stdio-sidecars/test.sh` builds the sidecar, starts the stack under its own Compose project name (`mcpproxy-sidecars-test`, port 18081), so the deployment's data volume is never touched and only the test project's containers, network and volume are removed at the end. Only the sidecar has a Compose health check, so diff --git a/examples/compose-stdio-sidecars/gen-secrets.sh b/examples/compose-stdio-sidecars/gen-secrets.sh index c60718f58..024dd6c9e 100755 --- a/examples/compose-stdio-sidecars/gen-secrets.sh +++ b/examples/compose-stdio-sidecars/gen-secrets.sh @@ -12,6 +12,12 @@ mkdir -p secrets # mkdir -p keeps the mode of an existing directory, so set it explicitly. chmod 0700 secrets for name in mcpproxy_api_key sidecar_api_key; do + # -s and chmod follow symlinks, so a link here would expose (or overwrite) + # a file outside secrets/. Accept only a regular file or nothing. + if [ -L "secrets/$name" ] || { [ -e "secrets/$name" ] && [ ! -f "secrets/$name" ]; }; then + echo "secrets/$name is not a regular file; refusing to use it" >&2 + exit 1 + fi if [ ! -s "secrets/$name" ]; then # 256 random bits as hex. printf '%s' "$(od -An -N32 -tx1 /dev/urandom | tr -d ' \n')" > "secrets/$name" diff --git a/examples/compose-stdio-sidecars/test.sh b/examples/compose-stdio-sidecars/test.sh index 380c99b85..376511f92 100755 --- a/examples/compose-stdio-sidecars/test.sh +++ b/examples/compose-stdio-sidecars/test.sh @@ -8,12 +8,16 @@ cd "$(dirname "$0")" # Run under its own Compose project (own containers, network and data volume) and # its own port, so `down -v` below removes only what this test created and never # the data volume of a deployment started with plain `docker compose up`. -# COMPOSE_PROJECT_NAME takes precedence over the file's top-level `name:`. -export COMPOSE_PROJECT_NAME="${COMPOSE_PROJECT_NAME:-mcpproxy-sidecars-test}" +# The project name is fixed and passed with -p on every call: -p wins over both +# the file's top-level `name:` and an inherited COMPOSE_PROJECT_NAME, which +# could otherwise point this script (and its `down -v`) at a real deployment. +PROJECT="mcpproxy-sidecars-test" +unset COMPOSE_PROJECT_NAME +dc() { docker compose -p "$PROJECT" "$@"; } PORT="${MCPPROXY_PORT:-18081}" export MCPPROXY_PORT="$PORT" -fail() { echo "FAIL: $*" >&2; docker compose logs --tail=80 >&2 || true; exit 1; } -cleanup() { docker compose down -v --remove-orphans >/dev/null 2>&1 || true; } +fail() { echo "FAIL: $*" >&2; dc logs --tail=80 >&2 || true; exit 1; } +cleanup() { dc down -v --remove-orphans >/dev/null 2>&1 || true; } trap cleanup EXIT ./gen-secrets.sh @@ -21,7 +25,7 @@ KEY="$(cat secrets/mcpproxy_api_key)" # --wait returns once the sidecar is healthy and mcpproxy is running; the proxy # has no health check of its own, so step 1 polls it. -docker compose up --build --wait --wait-timeout 300 || fail "stack did not become healthy" +dc up --build --wait --wait-timeout 300 || fail "stack did not become healthy" # 1. The proxy lists the sidecar's tools. The tool list arrives after the first # discovery pass, so poll for it. @@ -39,32 +43,35 @@ code="$(curl -s -o /dev/null -w '%{http_code}' -X POST "http://127.0.0.1:$PORT/m echo "ok: /mcp without a credential is refused" # 3. The sidecar's own endpoint refuses a request without its key. node is the -# only tool in the sidecar image, so the probes are node one-liners. -code="$(docker compose exec -T everything node -e "fetch('http://127.0.0.1:8000/mcp',{method:'POST'}).then(r=>console.log(r.status))")" +# only tool in the sidecar image, so the probes are node one-liners. Each +# probe prints its answer and exits 0, so a probe that could not run (no +# answer, or a non-zero exit) fails the test instead of passing as "blocked". +probe() { dc exec -T everything node -e "$1" || fail "probe could not run: $1"; } + +code="$(probe "fetch('http://127.0.0.1:8000/mcp',{method:'POST'}).then(r=>console.log(r.status))")" [ "$code" = "401" ] || fail "sidecar /mcp without its key returned $code, want 401" echo "ok: sidecar refuses a request without its key" # 4. The sidecar cannot reach the internet (neither by IP nor by name) ... -if docker compose exec -T everything node -e "fetch('http://1.1.1.1',{signal:AbortSignal.timeout(5000)}).then(()=>process.exit(0),()=>process.exit(1))"; then - fail "sidecar reached 1.1.1.1" -fi -if docker compose exec -T everything node -e "fetch('https://example.com',{signal:AbortSignal.timeout(5000)}).then(()=>process.exit(0),()=>process.exit(1))"; then - fail "sidecar reached example.com" -fi +for url in http://1.1.1.1 https://example.com; do + out="$(probe "fetch('$url',{signal:AbortSignal.timeout(5000)}).then(()=>console.log('reached'),()=>console.log('blocked'))")" + [ "$out" = "blocked" ] || fail "sidecar egress probe for $url answered '$out', want 'blocked'" +done echo "ok: sidecar has no route out" # 5. ... and cannot see the proxy's data directory. -if docker compose exec -T everything test -e /data; then - fail "/data is visible in the sidecar" -fi +out="$(probe "console.log(require('fs').existsSync('/data')?'present':'absent')")" +[ "$out" = "absent" ] || fail "/data probe in the sidecar answered '$out', want 'absent'" echo "ok: /data is not visible in the sidecar" # 6. No container has the docker socket. for svc in mcpproxy everything; do - id="$(docker compose ps -q "$svc")" - if docker inspect -f '{{range .Mounts}}{{.Source}} {{end}}' "$id" | grep -q docker.sock; then - fail "$svc mounts the docker socket" - fi + id="$(dc ps -q "$svc")" || fail "could not list the $svc container" + [ -n "$id" ] || fail "no $svc container" + mounts="$(docker inspect -f '{{range .Mounts}}{{.Source}} {{end}}' "$id")" || fail "could not inspect $svc" + case "$mounts" in + *docker.sock*) fail "$svc mounts the docker socket" ;; + esac done echo "ok: no docker socket" From b1e47c8f6ac162db6204984cace2eeac31c2c134 Mon Sep 17 00:00:00 2001 From: Algis Dumbris Date: Wed, 11 Nov 2026 20:52:51 +0200 Subject: [PATCH 4/4] fix(examples): validate the generated secret before writing it --- examples/compose-stdio-sidecars/gen-secrets.sh | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/examples/compose-stdio-sidecars/gen-secrets.sh b/examples/compose-stdio-sidecars/gen-secrets.sh index 024dd6c9e..bd963d7eb 100755 --- a/examples/compose-stdio-sidecars/gen-secrets.sh +++ b/examples/compose-stdio-sidecars/gen-secrets.sh @@ -19,8 +19,16 @@ for name in mcpproxy_api_key sidecar_api_key; do exit 1 fi if [ ! -s "secrets/$name" ]; then - # 256 random bits as hex. - printf '%s' "$(od -An -N32 -tx1 /dev/urandom | tr -d ' \n')" > "secrets/$name" + # 256 random bits as hex. od's status is checked on its own (a pipeline + # reports only its last command) and the result must be exactly 64 hex + # characters, so a failed or short read never becomes a weak key. + raw="$(od -An -N32 -tx1 /dev/urandom)" || { echo "could not read /dev/urandom" >&2; exit 1; } + key="$(printf '%s' "$raw" | tr -d ' \n')" + case "$key" in + *[!0-9a-f]*) echo "unexpected output from od" >&2; exit 1 ;; + esac + [ "${#key}" -eq 64 ] || { echo "short read from /dev/urandom" >&2; exit 1; } + printf '%s' "$key" > "secrets/$name" fi # The sidecar runs as uid 1000 and mcpproxy as root, and both must read the # file through the bind mount. The directory (0700) is what keeps other host