Skip to content

docs(docker): compose example with stdio servers in sidecars (#1707) - #1885

Merged
Dumbris merged 4 commits into
mainfrom
docs/compose-stdio-sidecars-1707
Nov 11, 2026
Merged

Dumbris merged 4 commits into
mainfrom
docs/compose-stdio-sidecars-1707

Conversation

@Dumbris

@Dumbris Dumbris commented Nov 11, 2026

Copy link
Copy Markdown
Member

Summary

Adds the layout from #1707 as a ready-to-copy, CI-tested example: mcpproxy with each stdio MCP server in its own sidecar container on an internal: true network.

  • examples/compose-stdio-sidecars/: compose file, sidecar Dockerfile (supergateway 4.2.0, --stateful, --apiKeyFile, /healthz healthcheck), minimal mcp_config.json, gen-secrets.sh, test.sh.
  • docs/operations/compose-stdio-sidecars.md: what the layout protects (a compromised stdio package cannot read /data, the API key or the OAuth token database), the supergateway stateless-default pitfall, and the known limits.
  • .github/workflows/compose-example.yml: path-filtered job that validates the compose file and runs the stack end to end.

Images are pinned by digest (mcpproxy-server v0.73.0, node:24-bookworm-slim). Keys are file secrets via MCPPROXY_API_KEY_FILE and ${file:}. /data is mounted only in the proxy, no container gets a docker socket, stop_grace_period: 60s.

Verification

  • docker compose config -q passes.
  • ./test.sh passed locally (Docker 29.4.0, Compose 5.1.2): tools listed through the proxy with the API key, /mcp without a credential returns 401, the sidecar without its key returns 401, the sidecar has no egress, no /data and no docker socket.
  • actionlint clean; docs site builds.
  • Not run: Podman, arm64, real servers beyond server-everything.

Notes

  • Uses the server image; the Spec 111 personal image (FR-038) does not exist yet.
  • TLS in front of the proxy is linked to the reverse-proxy doc, not exemplified here.

Closes #1707

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

Deploying mcpproxy-docs with  Cloudflare Pages  Cloudflare Pages

Latest commit: b1e47c8
Status: ✅  Deploy successful!
Preview URL: https://9eaed562.mcpproxy-docs.pages.dev
Branch Preview URL: https://docs-compose-stdio-sidecars.mcpproxy-docs.pages.dev

View logs

@codecov-commenter

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

📦 Build Artifacts

Workflow Run: View Run
Branch: docs/compose-stdio-sidecars-1707

Available Artifacts

  • archive-darwin-amd64 (32 MB)
  • archive-darwin-arm64 (29 MB)
  • archive-linux-amd64 (20 MB)
  • archive-linux-arm64 (18 MB)
  • archive-windows-amd64 (32 MB)
  • archive-windows-arm64 (28 MB)
  • frontend-dist-pr (0 MB)
  • installer-dmg-darwin-amd64 (28 MB)
  • installer-dmg-darwin-arm64 (25 MB)
  • smart-mcp-proxymcpproxy-go38UEGD.dockerbuild (0 MB)

How to Download

Option 1: GitHub Web UI (easiest)

  1. Go to the workflow run page linked above
  2. Scroll to the bottom "Artifacts" section
  3. Click on the artifact you want to download

Option 2: GitHub CLI

gh run download 43081990498 --repo smart-mcp-proxy/mcpproxy-go

Note: Artifacts expire in 14 days.

…ot 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.
@Dumbris
Dumbris enabled auto-merge (squash) November 11, 2026 18:58
@Dumbris
Dumbris merged commit df0aa1a into main Nov 11, 2026
77 of 82 checks passed
Dumbris added a commit that referenced this pull request Nov 16, 2026
…n macOS runners (#1890)

## Summary

Two `internal/server` tests failed on macOS runners on unrelated PRs
(#1885, #1887). Both are races in the tests, not in production code.
This PR fixes them. Test-only.

## Causes and fixes

**`TestSearchTools_WithholdsApprovalLockedHits`** returned only
`cedar:pending_item` when `orchid:read_item` was also expected.

- After `PhaseReady` the runtime starts background tool indexing, whose
first step deletes index entries for servers the upstream manager does
not know.
- The test seeds two hand-made servers into the index right after
`PhaseReady`, so the cleanup could delete a seeded document mid-seeding.
- Reproduced locally with `GOMAXPROCS=1 go test -race -count=40`: failed
within the first two runs.
- Fix: a `newSettledConsistencyServer` fixture waits for `PhaseReady`
and for the cleanup's completion log line before the test seeds
anything. `TestSearchTools_AnnotationsSurviveToTier` seeds the same way
and now uses it too.

**`TestTPAFetchLifecycle_ActivatesReprotectsAndRefusesBadReleases`**
failed with "exactly one cycle reported activated: expected 1, actual
0".

- The test waited for the bundle source to flip, which happens inside
the fetch leg. The telemetry counter is incremented later, by the
observer that runs after the cycle is recorded.
- Reproduced deterministically by delaying that observer by 400 ms (not
part of this PR).
- Fix: poll until the counter reaches 1, then keep the exact `== 1`
assertion.

## Not fixed here

The `test timed out after 40m0s` failure on #1886 was not a hang. The
whole `internal/server` package ran 40 minutes on a slow runner; the
same job passed in 20 minutes on retry. A healthy macOS run already uses
about half the 40-minute budget. Raising the timeout or trimming the
fixed 12-second waits in the upstream-add tests is a separate decision.

## Testing

- `GOMAXPROCS=1 go test -race -count=100 -run
TestSearchTools_WithholdsApprovalLockedHits ./internal/server/`: pass.
- Both search tests together, `-race -count=15`: pass.
- The fetch lifecycle test, `GOMAXPROCS=1 -race`: 15 of 15 runs passed.
- `golangci-lint` v2 on `./internal/server/...`: 0 issues.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Spec 111 compose example with stdio servers in sidecar containers on an internal network

2 participants