mcp-docker-deployment

MCP Docker Deployment

Containerize Python MCP servers (FastMCP or low-level SDK) for remote deployment with streamable-http transport (preferred) or legacy SSE, nginx reverse proxy with HTTPS, and GHCR publishing.

Transport choice — default to streamable-http

Always pick streamable-http with stateless_http=True unless you have a specific reason to use SSE. SSE has a wedge bug class with Claude Code as the client: when the long-lived SSE GET dies (container restart, network blip, idle close), Claude Code's MCP client auto-reconnects but does NOT re-run the initialize handshake. The new server-side session sees tools/call before initialize, raises RuntimeError("Received request before initialization was complete"), and the SDK's catch-all converts it to a generic -32602 "Invalid request parameters". Claude Code treats -32602 as unrecoverable; every subsequent call returns the same error until the user manually /mcp reloads.

Streamable-http with stateless_http=True has no per-session state to lose — every POST stands alone. The bug class is structurally impossible on this transport.

References: anthropics/claude-code#60061 (open upstream issue tracking the wedge on the SSE side; multiple independent reporters, same diagnosis, same workaround).

Pick sse ONLY if you have a non-Claude-Code MCP client that explicitly requires it (rare).

Step 1: Gather Project Information

Ask the user:

1. "What is your MCP server entry point file?" (e.g., my_mcp_server.py)
2. "Does your server use FastMCP (mcp.server.fastmcp.FastMCP) or the low-level SDK (mcp.server.Server)?"
3. "Confirm transport: streamable-http (recommended, default) or sse (legacy)?" — default to streamable-http. Only use sse if a non-Claude-Code client explicitly requires it. See the "Transport choice" section above for why. (Note: the two are NOT interchangeable — different endpoints, different SDK classes.)
4. "What Python files/directories need to be copied into the container?" (e.g., tools/, models/, formatting.py)
5. "What container registry URL?" (e.g., ghcr.io/{org}/{project})
6. "Does the MCP server need any environment variables?" (list them for docker-compose and example.env)
7. "Will this be behind an nginx reverse proxy with HTTPS?" (yes/no - if yes, include nginx config)
8. "Does it have private pip dependencies?" (yes/no - if yes, needs CR_PAT build arg)

Step 2: Create Dockerfile

FROM python:3.13-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code - adjust to match project structure
COPY {entry_point} .
# COPY additional files/directories as needed

# Non-root user
RUN useradd --create-home appuser && chown -R appuser:appuser /app
USER appuser

EXPOSE 8000

# Transport for Docker, bind to all interfaces
ENV MCP_TRANSPORT=streamable-http
ENV MCP_HOST=0.0.0.0
ENV MCP_PORT=8000

CMD ["python", "{entry_point}"]

FastMCP note: If the server uses FastMCP, also set FASTMCP_HOST and FASTMCP_PORT in the Dockerfile since FastMCP reads those specific env vars:

ENV FASTMCP_HOST=0.0.0.0
ENV FASTMCP_PORT=8000

If private pip dependencies, add before pip install:

ARG CR_PAT
RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/* \
    && git config --global url."https://${CR_PAT}@github.com/".insteadOf "https://github.com/" \
    && pip install --no-cache-dir -r requirements.txt \
    && git config --global --unset url."https://${CR_PAT}@github.com/".insteadOf

Step 3: Configure Transport in MCP Server

Path A: FastMCP (mcp.server.fastmcp.FastMCP)

FastMCP's constructor defaults override env vars, so host/port must be passed explicitly:

import os
from mcp.server.fastmcp import FastMCP

mcp = FastMCP(
    "my_mcp_server",
    host=os.getenv("FASTMCP_HOST", "127.0.0.1"),
    port=int(os.getenv("FASTMCP_PORT", "8000")),
    stateless_http=True,
)

# ... register tools ...

if __name__ == "__main__":
    transport = os.getenv("MCP_TRANSPORT", "stdio")
    mcp.run(transport=transport)

CRITICAL: Without explicit host/port args, the container binds to 127.0.0.1 and is unreachable despite FASTMCP_HOST=0.0.0.0 being set. This is because FastMCP's pydantic-settings defaults take precedence over env vars when constructor args are provided.

CRITICAL: stateless_http=True is required for streamable-http to actually be stateless (it has no effect on sse, which has its own per-connection state). Without it, the server tracks sessions via Mcp-Session-Id headers; if the proxy drops that header or the connection breaks, clients get "Session not found" errors. The combination of streamable-http AND stateless_http=True is what makes the SSE wedge bug class (see "Transport choice" above) structurally impossible — every POST stands alone, with no per-session handshake state to lose.

Supported transports:

• stdio — Local development (Claude Code local MCP servers)
• streamable-http — Recommended. Single /mcp endpoint, supports stateless_http=True, avoids the SSE wedge bug class.
• sse — Legacy. Two-endpoint protocol (/sse + /messages/). Wedge-prone with Claude Code; use only if forced by client compatibility.

Path B: Low-level SDK (mcp.server.Server)

The low-level SDK requires manual transport wiring with Starlette and uvicorn. Each transport type uses different SDK classes and different endpoints.

Required imports

import asyncio
import contextlib
import os
from collections.abc import AsyncIterator
from typing import Any

import uvicorn
from mcp.server import Server
from mcp.server.sse import SseServerTransport
from mcp.server.stdio import stdio_server
from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
from starlette.applications import Starlette
from starlette.responses import Response
from starlette.routing import Mount, Route

Server instance

app = Server("my_mcp_server")

# ... register tools with @app.list_tools(), @app.call_tool(), etc. ...

stdio transport (local development)

async def main_stdio() -> None:
    """Run the MCP server over stdio transport (local development)."""
    async with stdio_server() as (read_stream, write_stream):
        await app.run(
            read_stream,
            write_stream,
            app.create_initialization_options()
        )

SSE transport

def main_sse() -> None:
    """Run the MCP server over SSE transport (Docker/remote deployment)."""
    host: str = os.environ.get("MCP_HOST", "0.0.0.0")
    port: int = int(os.environ.get("MCP_PORT", "8000"))

    sse_transport = SseServerTransport("/messages/")

    async def handle_sse(request: Any) -> Response:
        async with sse_transport.connect_sse(
            request.scope, request.receive, request._send
        ) as streams:
            await app.run(
                streams[0],
                streams[1],
                app.create_initialization_options(),
            )
        return Response()

    starlette_app = Starlette(
        routes=[
            Route("/sse", endpoint=handle_sse),
            Mount("/messages/", app=sse_transport.handle_post_message),
        ],
    )

    uvicorn.run(starlette_app, host=host, port=port)

streamable-http transport

def main_streamable_http() -> None:
    """Run the MCP server over streamable-http transport."""
    host: str = os.environ.get("MCP_HOST", "0.0.0.0")
    port: int = int(os.environ.get("MCP_PORT", "8000"))

    session_manager = StreamableHTTPSessionManager(
        app=app,
        json_response=False,
        stateless=True,
    )

    @contextlib.asynccontextmanager
    async def lifespan(starlette_app: Starlette) -> AsyncIterator[None]:
        async with session_manager.run():
            yield

    starlette_app = Starlette(
        routes=[
            Mount("/mcp", app=session_manager.handle_request),
        ],
        lifespan=lifespan,
    )

    uvicorn.run(starlette_app, host=host, port=port)

Transport selection

if __name__ == "__main__":
    transport: str = os.environ.get("MCP_TRANSPORT", "stdio")
    if transport == "stdio":
        asyncio.run(main_stdio())
    elif transport == "sse":
        main_sse()
    elif transport == "streamable-http":
        main_streamable_http()
    else:
        raise SystemExit(f"Unknown MCP_TRANSPORT: {transport} (expected: stdio, sse, streamable-http)")

Step 4: Create build-publish.sh

#!/bin/sh
# Build and publish MCP Docker image
# Usage: ./build-publish.sh [--no-cache]

REGISTRY="{registry_url}"

NO_CACHE=""
if [ "$1" = "--no-cache" ]; then
    NO_CACHE="--no-cache"
fi

if [ ! -f VERSION ]; then
    echo "1" > VERSION
fi

CURRENT_VERSION=$(cat VERSION)

case "$CURRENT_VERSION" in
    ''|*[!0-9]*)
        echo "ERROR: VERSION file contains non-numeric value: $CURRENT_VERSION"
        exit 1
        ;;
esac

NEXT_VERSION=$((CURRENT_VERSION + 1))

echo "Building ${REGISTRY}:${NEXT_VERSION}..."

docker build \
    --platform linux/amd64 \
    $NO_CACHE \
    -t "${REGISTRY}:${NEXT_VERSION}" \
    .

if [ $? -ne 0 ]; then
    echo "ERROR: Docker build failed"
    exit 1
fi

docker tag "${REGISTRY}:${NEXT_VERSION}" "${REGISTRY}:latest"

echo "Pushing ${REGISTRY}:${NEXT_VERSION}..."
docker push "${REGISTRY}:${NEXT_VERSION}"
if [ $? -ne 0 ]; then
    echo "ERROR: Push failed"
    exit 1
fi

echo "Pushing ${REGISTRY}:latest..."
docker push "${REGISTRY}:latest"
if [ $? -ne 0 ]; then
    echo "ERROR: Push failed"
    exit 1
fi

echo "$NEXT_VERSION" > VERSION
echo "Published ${REGISTRY}:${NEXT_VERSION} and :latest"

If private dependencies, add --build-arg CR_PAT=$CR_PAT to docker build.

Make executable: chmod +x build-publish.sh

Step 5: Create .dockerignore

bin/
lib/
lib64/
include/
pyvenv.cfg
.Python
__pycache__/
*.py[cod]
*$py.class
*.egg-info/
tests/
.pytest_cache/
.coverage
htmlcov/
.git/
.gitignore
.env
VERSION
*.md
.vscode/
.idea/
*.swp
*.swo
*~
.DS_Store

Step 6: Create docker-compose.yaml

services:
  {service_name}:
    image: {registry_url}:latest
    container_name: {container_name}
    restart: unless-stopped
    ports:
      - "8000:8000"
    environment:
      MCP_TRANSPORT: streamable-http
      MCP_HOST: 0.0.0.0
      MCP_PORT: 8000
      # Add all app-specific env vars from example.env
    # volumes:
    #   - /path/to/cert.pem:/app/ca.pem:ro

FastMCP note: If using FastMCP, also add FASTMCP_HOST: 0.0.0.0 and FASTMCP_PORT: 8000 to the environment section.

Include all environment variables from the project's example.env.

Step 7: Create example.env

# MCP transport: "stdio" for local dev; "streamable-http" (recommended) or "sse" (legacy) for Docker/remote
MCP_TRANSPORT=streamable-http

# MCP network settings (used with streamable-http or sse transport)
# MCP_HOST=0.0.0.0
# MCP_PORT=8000

# FastMCP only: FastMCP reads these specific env vars for host/port binding.
# Not needed for low-level SDK servers.
# FASTMCP_HOST=0.0.0.0
# FASTMCP_PORT=8000

# App-specific variables below

Step 8: Update .gitignore

Add VERSION and .env entries.

Step 9: Nginx Reverse Proxy (if applicable)

If the MCP server will be behind nginx with HTTPS, see references/nginx-sse.md for the config snippet. The same location block works cleanly for both transports — proxy_buffering off plus long proxy_read_timeout are still useful for streamable-http's optional server→client streaming responses.

MCP Endpoints

Streamable-http (recommended) exposes:

• /mcp - Single endpoint (POST for requests, optional GET for server→client streams)

SSE (legacy) exposes:

• /sse - SSE connection endpoint
• /messages/ - Message posting endpoint

Claude Code Client Configuration

Connect to a remote MCP server in .mcp.json:

{
  "mcpServers": {
    "my-mcp": {
      "type": "http",
      "url": "https://server.example.com/my-mcp/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Auth is handled at the nginx layer via Bearer token headers. The MCP server does not need to know about authentication.

Troubleshooting

Container binds to 127.0.0.1 instead of 0.0.0.0 (FastMCP) - FastMCP constructor defaults override env vars. Pass host/port explicitly in the FastMCP constructor (see Step 3, Path A).

SSE connection stale / wedged after container restart or network blip - When Claude Code's SSE GET dies, it auto-reconnects but does NOT re-run the initialize handshake; the new server-side session sees tools/call before initialize, the SDK raises RuntimeError("Received request before initialization was complete"), and the wire-level error becomes a generic -32602 "Invalid request parameters". Claude Code treats -32602 as unrecoverable and stays wedged on every subsequent call. Workaround: /mcp reload in Claude Code to force a fresh handshake. Real fix: migrate to streamable-http with stateless_http=True — that's exactly what this bug class needs (see "Transport choice" near the top). Upstream issue: anthropics/claude-code#60061.

PyPI package version stale in Docker image - Publish the new version to PyPI before running build-publish.sh. Verify with docker exec {container} pip show {package}.

Missing uvicorn or starlette (low-level SDK) - Low-level SDK servers need uvicorn and starlette in requirements.txt. FastMCP bundles these, but the low-level SDK does not.

Wrong transport route (low-level SDK) - SSE uses /sse and /messages/, streamable-http uses /mcp. These are NOT interchangeable. Make sure the client URL matches the transport configured on the server.

"Session not found" errors behind nginx - The MCP SDK's streamable-http transport is stateful by default. During initialization, the server assigns a session ID and expects the client to send it back via the Mcp-Session-Id header on every request. Behind a reverse proxy, this header can be dropped or the SSE connection that maintains the session can be interrupted, causing "Session not found" errors. Fix: set stateless_http=True (FastMCP) or stateless=True (low-level SDK StreamableHTTPSessionManager). This disables session tracking so each request is handled independently. See the "Transport choice" section near the top — streamable-http + stateless is the recommended default for exactly this reason.