The Dokploy MCP Server can be deployed using Docker, supporting both stdio and HTTP transport modes for different use cases.
Build the Docker Image
First, clone the repository and build the Docker image:
git clone https://github.com/Dokploy/mcp.git
cd dokploy-mcp
docker build -t dokploy-mcp .
- Build stage: Uses
node:lts-alpine to compile TypeScript
- Production stage: Creates a minimal production image with only necessary dependencies
- Health check: Automatically monitors the service when running in HTTP mode
Transport Modes
Stdio Mode (Default)
Stdio mode is ideal for MCP clients like Claude Desktop, VS Code, Cursor, and other desktop applications.
docker run -it --rm \
-e DOKPLOY_URL=https://your-dokploy-server.com/api \
-e DOKPLOY_API_KEY=your_token_here \
dokploy-mcp
- Direct process communication via stdin/stdout
- Interactive mode with
-it flag
- Automatically removed after exit with
--rm
HTTP Mode
HTTP mode exposes the server via HTTP/HTTPS, supporting both modern Streamable HTTP (MCP 2025-03-26) and legacy SSE (MCP 2024-11-05) protocols.
docker run -it --rm \
-p 8080:3000 \
-e MCP_TRANSPORT=http \
-e DOKPLOY_URL=https://your-dokploy-server.com/api \
-e DOKPLOY_API_KEY=your_token_here \
dokploy-mcp
- POST /mcp - Client-to-server requests
- GET /mcp - Server-to-client notifications
- DELETE /mcp - Session termination
- GET /health - Health check endpoint
- GET /sse - Legacy SSE stream (backwards compatibility)
- POST /messages - Legacy client messages
Port configuration:
- Internal port:
3000 (fixed)
- External port: Configurable via
-p flag (e.g., -p 8080:3000)
Docker Compose Deployment
For production deployments, use the provided docker-compose.yml:
services:
dokploy-mcp-http:
build: .
container_name: dokploy-mcp-http
ports:
- "${EXTERNAL_PORT:-3000}:3000"
environment:
- MCP_TRANSPORT=${MCP_TRANSPORT:-http}
- DOKPLOY_URL=${DOKPLOY_URL:-https://your-dokploy-server.com/api}
- DOKPLOY_AUTH_TOKEN=${DOKPLOY_AUTH_TOKEN:-your_token_here}
restart: unless-stopped
networks:
- mcp-network
dokploy-mcp-stdio:
build: .
container_name: dokploy-mcp-stdio
environment:
- DOKPLOY_URL=${DOKPLOY_URL:-https://your-dokploy-server.com/api}
- DOKPLOY_AUTH_TOKEN=${DOKPLOY_AUTH_TOKEN:-your_token_here}
restart: "no"
stdin_open: true
tty: true
networks:
- mcp-network
networks:
mcp-network:
driver: bridge
Start the HTTP Service
# Start the HTTP service
docker-compose up -d dokploy-mcp-http
# View logs
docker-compose logs -f dokploy-mcp-http
# Stop the service
docker-compose down
Environment Variables
Create a .env file in the same directory as docker-compose.yml:
EXTERNAL_PORT=3000
MCP_TRANSPORT=http
DOKPLOY_URL=https://your-dokploy-server.com/api
DOKPLOY_AUTH_TOKEN=your_token_here
MCP Client Configuration
Stdio Mode (Claude Desktop, VS Code, etc.)
Add this to your MCP client configuration (e.g., claude_desktop_config.json):
{
"mcpServers": {
"dokploy-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"DOKPLOY_URL=https://your-dokploy-server.com/api",
"-e",
"DOKPLOY_API_KEY=your_token_here",
"dokploy-mcp"
]
}
}
}
Note the -i flag (not -it) in the args array - MCP clients handle the tty, so only stdin needs to be open.
HTTP Mode (Web Applications)
First, start the HTTP server using Docker Compose or manual Docker command. Then connect your application to http://localhost:3000/mcp.
Modern MCP clients automatically use the Streamable HTTP endpoints, while legacy clients connect using the SSE endpoints at /sse and /messages.
Health Check and Monitoring
The Docker image includes a built-in health check for HTTP mode:
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD if [ "$MCP_TRANSPORT" = "http" ] || [ "$MCP_TRANSPORT" = "sse" ]; then \
wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1; \
else \
exit 0; \
fi
Check Container Health
# View health status
docker ps
# View detailed health check logs
docker inspect --format='{{json .State.Health}}' dokploy-mcp-http | jq
# Test health endpoint manually
curl http://localhost:3000/health
View Logs
# Follow logs in real-time
docker logs -f dokploy-mcp-http
# View last 100 lines
docker logs --tail 100 dokploy-mcp-http
# View logs with timestamps
docker logs -t dokploy-mcp-http
Production Best Practices
Use Docker Compose
Always use Docker Compose for production deployments:
- Manages service lifecycle
- Handles automatic restarts
- Simplifies configuration with
.env files
- Provides networking isolation
Secure Environment Variables
Never commit API keys or tokens to version control. Always use environment variables or Docker secrets.
# Use Docker secrets for sensitive data (Swarm mode)
docker secret create dokploy_api_key ./api_key.txt
Resource Limits
Add resource limits to prevent overconsumption:
services:
dokploy-mcp-http:
# ... other config
deploy:
resources:
limits:
cpus: '0.5'
memory: 512M
reservations:
cpus: '0.25'
memory: 256M
Enable Logging
Configure logging drivers for centralized log management:
services:
dokploy-mcp-http:
# ... other config
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
Network Security
For HTTP mode in production:
- Use HTTPS: Place behind a reverse proxy (nginx, Traefik)
- Firewall rules: Restrict access to authorized clients only
- API key rotation: Regularly rotate
DOKPLOY_API_KEY
Update Strategy
# Pull latest code
git pull origin main
# Rebuild image
docker-compose build
# Recreate containers
docker-compose up -d
# Verify deployment
docker-compose ps
curl http://localhost:3000/health
Next Steps
