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..1f4aa8f80 --- /dev/null +++ b/docs/operations/compose-stdio-sidecars.md @@ -0,0 +1,140 @@ +--- +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 +``` + +`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 `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 +`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 +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/.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..a8981a4d4 --- /dev/null +++ b/examples/compose-stdio-sidecars/README.md @@ -0,0 +1,12 @@ +# 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 +``` + +`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 new file mode 100644 index 000000000..dc375c4c1 --- /dev/null +++ b/examples/compose-stdio-sidecars/docker-compose.yml @@ -0,0 +1,86 @@ +# 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 + # 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} + + 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..bd963d7eb --- /dev/null +++ b/examples/compose-stdio-sidecars/gen-secrets.sh @@ -0,0 +1,38 @@ +#!/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 +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 + # -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. 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 + # 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..376511f92 --- /dev/null +++ b/examples/compose-stdio-sidecars/test.sh @@ -0,0 +1,78 @@ +#!/bin/sh +# 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")" + +# 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`. +# 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; 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 +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. +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. +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. 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) ... +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. +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="$(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" + +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',