[Feature Request]: Connect to Dockerized MCP Servers via STDIO

[qdrddr]

As a container user that runs MCP servers in Docker Desktop, I want to attach those to context-forge via STDIO so the context forge can expose those via /sse.

Current issue: running MCP servers that support only STDIO is cumbersome, not user-friendly, and can break dependencies if not containerized. Also something needs to start those servers. Docker Desktop offers an easy solution to run those servers via STDIO. We need conext-forge to be able to consume Conteinerized MCP Servers via STDIO.

🧭 Type of Feature

Please select the most appropriate category:

• [ X ] Enhancement to existing functionality
• New feature or capability
• [ X ] New MCP-compliant server
• New component or integration
• Developer tooling or test improvement
• Packaging, automation, and deployment (ex: pypi, docker, quay.io, kubernetes, terraform)
• Other (please describe below)

🧭 Epic

Title: Backend containerized MCP servers with STDIO
Goal: Docker Desktop offers a simple way to install MCP servers, most support only STDIO, i want context-forge to expose those via HTTP with Auth.
Why now: Simple to adopt for beginners. Backward compatibility.

---

🙋‍♂️ User Story 1

As a: container user running MCP servers in Docker Desktop
I want: to attach those STDIO-based servers to context-forge
So that: context-forge can expose them via /sse with authentication and can be reused with my MCP clients.

✅ Acceptance Criteria

Scenario: Connect STDIO-based MCP server running in a container
  Given a containerized MCP server running with STDIO only
  When context-forge is configured to connect via STDIO
  Then the server is exposed via /sse endpoint with auth

Scenario: Auto-start STDIO-based MCP container
  Given no active MCP server container
  When context-forge is initialized
  Then it starts the defined STDIO-based container automatically

---

🙋‍♂️ User Story 2

As a: beginner developer or non-infrastructure user
I want: to run STDIO-only MCP servers using Docker without manual networking setups
So that: I can develop and test without needing deep server configuration knowledge

✅ Acceptance Criteria

Scenario: Beginner sets up context-forge and Dockerized MCP servers
  Given Docker Desktop is installed
  When user launches context-forge with MCP server config
  Then the container starts and is integrated via STDIO seamlessly

---

📐 Design Sketch (optional)

Include a diagram, sketch, or flow (use Mermaid if desired):

flowchart TD
    A[Client] -->|POST /completions| B(Context Forge)
    B -->|STDIO| C[Dockerized MCP Server]

Loading

---

🔗 MCP Standards Check

• [ X ] Change adheres to current MCP specifications
• [ X ] No breaking changes to existing MCP-compliant integrations
• [ X ] If deviations exist, please describe them below:

---

🔄 Alternatives Considered

• Manually connecting MCP servers over TCP or HTTP
• Custom scripts to proxy STDIO to HTTP
• Running standalone MCP servers outside container scope

All alternatives require more setup or break consistency with containerized workflows.

---

📓 Additional Context

Running non-communicable containerized MCP servers that support only STDIO is currently cumbersome and often breaks dependencies. Docker Desktop provides a convenient and reliable environment for such workloads. By allowing context-forge to connect to these via STDIO and expose them over /sse, users benefit from an easy, portable, and scalable local development setup.

[crivetimihai]

Thank you for the detailed requirement. Currently we have two ways to consume STDIO-only MCP servers:

1. Use npx -y supergateway (requires Node.js) to wrap the server and expose /sse directly
2. Run them with python3 -m mcpgateway.translate to convert STDIO → SSE and register as a normal gateway

Both work in Docker today, even if the flags are a bit finicky. Here are copy-paste examples:

Option 1 docker + supergateway

# supergateway launches the container for you and serves /sse on 8003
npx -y supergateway \
  --stdio "docker run -i --rm mcp/time --local-timezone=Europe/Dublin" \
  --port 8003
# SSE now available at http://localhost:8003/sse

Option 2 docker + translate bridge (UNDER DEVELOPMENT)

This is still under development: #94

# start the server, pipe it through translate on port 9000
docker run -i --rm mcp/time --local-timezone=Europe/Dublin \
| python3 -m mcpgateway.translate --stdio - --port 9000
# SSE now available at http://localhost:9000/sse

Option 3 supergateway inside Docker (via docker.sock) - NEEDS CUSTOM IMAGE

This uses /var/run/docker.sock so no Node or Python is needed on the host, but the current image does not embed a working Docker client.

docker run --rm \
  -p 8004:8004 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  michlyn/supergateway:latest \
  --stdio "docker run -i --rm mcp/time --local-timezone=Europe/Dublin" \
  --port 8004
# would expose SSE at http://localhost:8004/sse if the image fully supported docker-in-docker

Roadmap: a connector that spins up Docker / Podman / K8s containers and wires STDIO automatically is in progress. We're also considering a JSON configuration similar to Claude where the gateway can spin up new MCP Servers via STDIO. Until then, the two working snippets above provide a container-first path.

If you found this useful, let us know - and feel free to submit a PR against the documentation to help others trying to use this with Docker. Thank you!

[qdrddr]

Option 1 requires supergateway to run on the host.
Also my proposal was to be able to consume Docker Desktop’s MCP Toolkit (which operates via STDIO) like this:

docker run -i --rm alpine/socat STDIO TCP:host.docker.internal:8811

[manavgup]

Hmm the way I think about this is that we should simplify MCP Context Forge by focusing exclusively on connecting to externally managed MCP servers, rather than managing container lifecycles or requiring Docker on the host. So basically:

• Eliminate the complexity and dependencies associated with container lifecycle management inside MCP Context Forge.
• Enable seamless integration with MCP servers running in diverse environments, including Docker Desktop MCP Toolkit setups, by connecting over standard TCP/SSE endpoints.
• Support existing bridging solutions like supergateway and socat that expose STDIO-only MCP servers as TCP/SSE services.
• Provide a (hopefully?) lightweight, and user-friendly gateway that can be easily deployed without Docker or container orchestration knowledge.
• Maintain full support for authentication, federation, and SSE exposure to MCP clients.

Does this align with the roadmap @crivetimihai which anticipates external bridging solutions until a more integrated container orchestration feature is developed?

[manavgup]

actually scratch everything i said above. Just noticed #94 which should address the above.