Docker Deployment

Quick start

docker compose up -d

The server listens on port 8000 with HTTP transport by default.

Environment variables

Variable	Default	Description
LOGODEV_MCP_READ_ONLY	true	Disable write tools
LOGODEV_MCP_BEARER_TOKEN	n/a	Enable bearer token auth
LOGODEV_MCP_LOG_LEVEL	INFO	Log level
LOGODEV_MCP_INSTRUCTIONS	(computed at startup)	System instructions for LLM context
LOGODEV_MCP_DEBUG_PORT	n/a	Remote-debugger TCP port (see Remote debugging; requires --build-arg DEBUG=true image)
LOGODEV_MCP_DEBUG_WAIT	false	Block startup until IDE attaches (see Remote debugging)

For OIDC auth variables, see Authentication.

Volumes

Path	Purpose
/data/service	Your service data (bind-mount or named volume)
/data/state	State files (FastMCP OIDC state, etc.)

UID/GID

Set PUID and PGID in your .env file to match the owner of bind-mounted directories (default 1000/1000).

Remote debugging

Production images ship without debugpy to keep the image lean. To attach a remote Python debugger from VS Code or PyCharm:

1. Build with the debug extra:

   docker build --build-arg DEBUG=true -t logodev-mcp:debug .
   

   This installs the [debug] optional-dependency group (which pulls debugpy transitively from fastmcp-pvl-core). Default builds (DEBUG=false) skip it.

2. Run with the debug env vars set and the port mapped:

   docker run --rm \
     -e LOGODEV_MCP_DEBUG_PORT=5678 \
     -e LOGODEV_MCP_DEBUG_WAIT=true \
     -p 127.0.0.1:5678:5678 \
     -p 8000:8000 \
     logodev-mcp:debug
   

   Env var	Effect
   LOGODEV_MCP_DEBUG_PORT	TCP port the debugger listens on (any value parsing to 0 disables; non-numeric or out-of-range values log a WARNING and the listener stays off)
   LOGODEV_MCP_DEBUG_WAIT	When truthy (1/true/yes/on), block startup until the IDE attaches. Default is non-blocking.

3. Attach from VS Code, adding a launch config:

   {
     "name": "Attach to logodev-mcp",
     "type": "debugpy",
     "request": "attach",
     "connect": { "host": "localhost", "port": 5678 }
   }
   

   PyCharm uses Run → Edit Configurations → Python Debug Server with the same host/port.

Never publish the debug port on a public network

The debug listener binds 0.0.0.0 inside the container so the IDE can reach it from the host, but debugpy's DAP protocol is unauthenticated: any peer that can reach the port has arbitrary code execution as the server process. Always bind the port mapping to localhost (-p 127.0.0.1:5678:5678) or tunnel via kubectl port-forward / SSH. Production images should be built with default DEBUG=false.

When the helper is invoked but debugpy isn't installed (say, someone sets DEBUG_PORT on a non-debug image), it logs a WARNING and continues; this is the safe failure mode.