dev-mcps/MCP-STACK.md

Secure MCP stack

This workspace contains four independent Streamable HTTP MCP servers:

• coding-agent-mcp: scoped workspace editing. Task execution is disabled in this stack.
• dev-server-mcp: authenticated facade for a private, allowlisted development-server worker. One instance per execution, each in a throwaway copy of that execution’s tree and on its own port.
• egress-proxy: the development worker’s only route to package registries; it allows their CONNECT requests and refuses everything else.
• browser-mcp: Playwright automation restricted to exact allowed origins.
• minio-mcp: bounded list/read/stat/write access to object storage, with no delete tool. In internal mode (catalog entry minio-mcp-internal, header x-minio-scope) it uses the platform’s MinIO whose endpoint and keys the catalog entry sends as headers, and one bucket per execution, <MINIO_MCP_INTERNAL_BUCKET_PREFIX><execution id>, created when the session opens; in external mode the model opens session-scoped connections to MinIO deployments itself.

The MCP client orchestrates them; servers do not share MCP sessions or credentials.

Start

1. Copy mcp-stack.env.example to .env and replace every token with an independent random value.
2. Set MCP_WORKSPACE_HOST_PATH to one dedicated project directory.
3. Copy and edit dev-server-mcp/services.example.json. It ships four worked service definitions: a shared Vite tree, and per-execution ones for Node, Java (through the project’s own ./mvnw) and Python. Keep BROWSER_MCP_ALLOWED_ORIGINS aligned with DEV_SERVER_PORT_RANGE: the browser reaches a preview only on a port that range covers.
4. Optionally set MINIO_MCP_ALLOWED_ENDPOINTS to the comma-separated MinIO S3 origins clients may use.
5. Run docker compose --env-file .env -f mcp-stack.compose.yml up --build.

Local MCP endpoints:

• http://127.0.0.1:3101/mcp — coding agent
• http://127.0.0.1:3102/mcp — development server
• http://127.0.0.1:3103/mcp — browser
• http://127.0.0.1:3104/mcp — MinIO

The same endpoints are also available through the unified gateway at /coding-agent/mcp, /dev-server/mcp, /browser/mcp and /minio/mcp on port 3100 (or the configured HTTPS host on the VM deployment).

Example Codex client configuration (.codex/config.toml in a trusted project):

[mcp_servers.coding_agent]
url = "http://127.0.0.1:3101/mcp"
bearer_token_env_var = "CODING_AGENT_MCP_TOKEN"

[mcp_servers.dev_server]
url = "http://127.0.0.1:3102/mcp"
bearer_token_env_var = "DEV_SERVER_MCP_TOKEN"

[mcp_servers.browser]
url = "http://127.0.0.1:3103/mcp"
bearer_token_env_var = "BROWSER_MCP_TOKEN"

[mcp_servers.minio]
url = "http://127.0.0.1:3104/mcp"
bearer_token_env_var = "MINIO_MCP_TOKEN"

Set those four variables in the MCP client’s environment to the token portions configured for the corresponding servers. Do not reuse a token between servers.

Only the minimal Caddy gateway publishes loopback ports. The coding, development and browser services stay exclusively on internal networks. minio-mcp has outbound connectivity because each MCP session can open connections to remote S3 endpoints. Set MINIO_MCP_ALLOWED_ENDPOINTS whenever those endpoints are known; leaving it empty gives authenticated MCP clients an intentional network-request capability. For remote use, use the included VM overlay so Caddy terminates TLS, and add rate limiting at the network edge when appropriate.

The worker and browser networks are marked internal, no service uses host networking or the Docker socket, and the development-server workspace mount is read-only. Container isolation reduces the blast radius but is not a substitute for an ephemeral VM/microVM when executing hostile multi-tenant code.

Installing dependencies means fetching and running other people’s code, so three things stand between it and the rest of the stack: the tree runs in a copy of itself and never in the workspace mount, the install runs with package scripts disabled, and the only way out of the worker is a proxy that allows the registries and nothing else. Each execution also gets a HOME of its own, which is what keeps Maven’s ~/.m2 from becoming a channel between executions — npm’s shared cache is safe because npm ci verifies every package against the lockfile, and Maven has no lockfile to verify against.

coding-agent-mcp intentionally retains write access to the selected project because editing is its purpose. Point MCP_WORKSPACE_HOST_PATH only at a dedicated, backed-up directory on storage with a disk quota; never point it at a home directory, repository collection, or filesystem root.