--- title: "Building Production-Ready MCP Servers: The 2026 Deployment Playbook" description: "Most MCP servers die in production. Here's the deployment architecture, Docker setup, monitoring, and security patterns that keep yours alive." date: 2026-04-14 lastmod: 2026-05-18 url: https://godberrystudios.com/posts/deploy-mcp-server-production/ author: Tomas Lebedinskas categories: ["mcp"] tags: ["mcp","deployment","docker","devops"] --- Your MCP server works on your laptop. Claude connects, tools fire, results come back. Ship it, right? An early-2026 audit of 1,847 MCP servers found **52% abandoned** and only **17%** meeting a production bar — the rest lightly maintained, stale, or failing silently with 200 OK responses full of parsing errors. The gap between "works locally" and "works in production" is where MCP servers go to die. The patterns below keep yours in the 17% — drawn from shipping **Content-to-Social MCP** to the Apify Store on 2026-04-12 and running it on real customer traffic ever since. ## The STDIO trap The default transport doesn't work for production. Scaffold with the official SDK and you get STDIO — fine for Claude Desktop or Cursor spawning your server as a subprocess, useless for anything remote. No load balancer, no sharing without a repo clone. Switch to **Streamable HTTP** before you deploy. Added in the spec's 2025-03-26 revision, it deprecated the older HTTP+SSE transport (still supported for backward compatibility) and turns your server into a standard HTTP API accepting POST at a `/mcp` endpoint. Single endpoint, works with load balancers, works with any HTTP client. The code change is small — in Python with FastMCP: ```python # Local development (STDIO) mcp.run() # Production (Streamable HTTP) mcp.run(transport="streamable-http", host="0.0.0.0", port=8000) ``` In TypeScript the transport itself takes no port — it's an HTTP handler you mount on a route, and the web framework owns the port. Wire it into Express: ```typescript import express, { Request, Response } from "express"; import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"; import { randomUUID } from "node:crypto"; const app = express(); app.use(express.json()); app.post("/mcp", async (req: Request, res: Response) => { const server = getServer(); // your configured McpServer instance const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID(), }); await server.connect(transport); await transport.handleRequest(req, res, req.body); res.on("close", () => { transport.close(); server.close(); }); }); app.listen(8000); ``` Set `sessionIdGenerator: undefined` for stateless mode (simpler, no resumability). That's step one. The real work is everything that comes after. ## Production architecture The shape that survives real traffic: ``` ┌─────────────────────────────────────┐ │ AI Client (Claude, etc.) │ └──────────────┬──────────────────────┘ │ HTTPS ▼ ┌─────────────────────────────────────┐ │ Reverse Proxy (Nginx) │ │ TLS termination, rate limiting │ └──────────────┬──────────────────────┘ │ HTTP ▼ ┌─────────────────────────────────────┐ │ MCP Server Container │ │ Streamable HTTP on port 8000 │ │ Non-root user, health checks │ └──────────────┬──────────────────────┘ │ ▼ ┌─────────────────────────────────────┐ │ External APIs / Databases │ │ (The actual data sources) │ └─────────────────────────────────────┘ ``` Three layers, each with its own failure modes. Running 3+ MCP servers? Add a **gateway layer** between the proxy and the individual servers. Gateways like Docker's MCP Gateway (open-sourced by Docker in mid-2025) aggregate multiple servers behind a single endpoint, centralize auth, prevent tool-name collisions, and give you unified logging. Without one you end up with separate auth flows, monitoring, and secrets management per server — and operational complexity grows faster than you expect. ## Dockerizing your MCP server Containers aren't optional. A production Dockerfile for a Python MCP server: ```dockerfile FROM python:3.12-slim # Don't run as root RUN useradd --create-home --shell /bin/bash mcpuser WORKDIR /app # Install dependencies first (better layer caching) COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt # Copy application code COPY . . # Switch to non-root user USER mcpuser EXPOSE 8000 HEALTHCHECK --interval=30s --timeout=10s --retries=3 \ CMD curl -f http://localhost:8000/health || exit 1 CMD ["python", "-m", "server", "--transport", "streamable-http"] ``` Decisions: **slim, not Alpine** — musl breaks Python packages touching async I/O; slim is 40MB larger and saves hours of debugging. **Non-root** — compromise shouldn't equal root, and a shocking number of public MCP Dockerfiles skip it. **HEALTHCHECK in the Dockerfile** so Docker and any orchestrator above it know whether the server is actually working. **Pin dependencies** to an exact current version (`mcp==1.27.1`, not `mcp>=1.27`) — the SDK is still evolving fast, so pin whatever is current the day you build. `docker-compose.yml` for local production testing: ```yaml services: mcp-server: build: . ports: - "8000:8000" environment: - API_KEY=${API_KEY} - LOG_LEVEL=info restart: unless-stopped deploy: resources: limits: memory: 512M cpus: "0.5" ``` Never bake secrets into the image. `${VAR}` substitution, values in `.env`, `.env` in `.gitignore`; in production, Docker secrets or your platform's secret manager (AWS Secrets Manager, Vault, Apify's env-var store). The Apify-flavored version — same transport + billing wiring I run in production — is open-sourced at [mcp-server-apify-starter](https://github.com/godberrystudios/mcp-server-apify-starter) (MIT). If Apify is your target, start there and skip the Dockerfile entirely. ## Health checks that actually work This is where most production MCP servers fail — and not by failing the check. They pass it while completely broken. The naive approach: ```python @app.get("/health") async def health(): return {"status": "ok"} ``` This tells you the HTTP process is running — the least interesting thing about your server. If your MCP server wraps a Google Maps API and that key expired yesterday, this still returns 200 OK while every tool call fails. A real health check verifies the full dependency chain: ```python @app.get("/health") async def health(): checks = {} # Check upstream API connectivity try: response = await http_client.get( "https://maps.googleapis.com/maps/api/place/details/json", params={"place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "key": API_KEY}, timeout=5 ) checks["google_maps_api"] = response.status_code == 200 except Exception: checks["google_maps_api"] = False # Check database if applicable try: await db.execute("SELECT 1") checks["database"] = True except Exception: checks["database"] = False all_healthy = all(checks.values()) return JSONResponse( status_code=200 if all_healthy else 503, content={"status": "healthy" if all_healthy else "degraded", "checks": checks} ) ``` Run this on a 30-second interval, restart the container after 3 consecutive failures, log every failure. Health check failures are your early warning system. ## The silent killer: schema drift A failure mode that won't show up in any health check. The upstream API changes its response format — a field renamed, a nested object becomes an array, a field that was always present stops appearing for certain queries. Your server still gets 200 OK, parses what it can, returns half-broken results, and the LLM downstream tries to make sense of garbage. The April 2026 endpoint analysis flagged **schema drift** as one of the hardest production bugs to catch. The defense is response validation: ```python from pydantic import BaseModel, ValidationError class PlaceDetails(BaseModel): name: str formatted_address: str rating: float | None = None user_ratings_total: int | None = None @mcp.tool() async def get_place_details(place_id: str) -> str: response = await fetch_from_google(place_id) try: validated = PlaceDetails(**response) except ValidationError as e: logger.error(f"Schema drift detected: {e}") raise McpError( ErrorCode.InternalError, "Upstream API response format has changed. This tool needs maintenance." ) return validated.model_dump_json() ``` Pydantic (or Zod in TypeScript) catches format changes immediately instead of silently passing bad data through. Pin the upstream API version when supported, and alert on validation-error spikes. Not theoretical — Google migrated reviewer anchors from `` to `