Transport modes

The Dokploy MCP Server supports multiple transport modes to accommodate different deployment scenarios and client requirements. Each mode has its own use cases and configuration.

Available Transport Modes

Stdio Mode (Default)

Stdio (standard input/output) mode is the default transport for the MCP server. It uses process communication for direct interaction between the server and client. When to use:

Desktop MCP clients (Cursor, VS Code, Claude Desktop, Windsurf, Zed)
Command-line applications
Local development and testing
Single-user scenarios

Advantages:

Simple setup with no network configuration
Low latency for local communication
No additional port management
Secure by default (no network exposure)

How it works: The server communicates through stdin/stdout streams. When you run the MCP server, it starts as a child process and exchanges JSON-RPC messages with the parent process.

Cursor/Claude Desktop
VS Code
Command Line
Docker

{
  "mcpServers": {
    "dokploy-mcp": {
      "command": "npx",
      "args": ["-y", "@ahdev/dokploy-mcp"],
      "env": {
        "DOKPLOY_URL": "https://your-dokploy-server.com/api",
        "DOKPLOY_API_KEY": "your-dokploy-api-token"
      }
    }
  }
}

{
  "servers": {
    "dokploy-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ahdev/dokploy-mcp"],
      "env": {
        "DOKPLOY_URL": "https://your-dokploy-server.com/api",
        "DOKPLOY_API_KEY": "your-dokploy-api-token"
      }
    }
  }
}

# Run directly with npx
npx -y @ahdev/dokploy-mcp

# Or after building from source
npm run start:stdio

docker run -it --rm \
  -e DOKPLOY_URL=https://your-dokploy-server.com/api \
  -e DOKPLOY_API_KEY=your_token_here \
  dokploy-mcp

HTTP Mode (Streamable HTTP + Legacy SSE)

HTTP mode exposes the MCP server via HTTP/HTTPS, supporting both modern Streamable HTTP (MCP 2025-03-26) and legacy SSE (MCP 2024-11-05) protocols for maximum compatibility. When to use:

Web applications and browser-based clients
Multi-user scenarios
Remote access requirements
Microservices architecture
Load-balanced deployments

Advantages:

Network-accessible for remote clients
Supports multiple simultaneous connections
Compatible with web browsers and HTTP clients
Dual protocol support (modern + legacy)
Session management with automatic cleanup

How it works: The server starts an Express.js HTTP server on port 3000 (internally) and provides multiple endpoints for different transport protocols.

Modern Streamable HTTP Endpoints (MCP 2025-03-26)

POST /mcp

endpoint

Client-to-server requestsUsed for:

Initialization requests (initialize)
Tool calls and resource requests
Session management

Headers:

mcp-session-id: Session identifier (required for existing sessions)
Content-Type: application/json

Example:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "my-client", "version": "1.0.0"}
    },
    "id": 1
  }'

GET /mcp

endpoint

Server-to-client notificationsLong-lived connection for receiving server-initiated messages and notifications via Server-Sent Events (SSE).Headers:

mcp-session-id: Session identifier (required)

Example:

curl -N -H "mcp-session-id: your-session-id" \
  http://localhost:3000/mcp

DELETE /mcp

endpoint

Session terminationCleanly closes a session and releases resources.Headers:

mcp-session-id: Session identifier (required)

Example:

curl -X DELETE http://localhost:3000/mcp \
  -H "mcp-session-id: your-session-id"

GET /health

endpoint

Health check endpointReturns server status and timestamp. Useful for monitoring and load balancer health checks.Example:

curl http://localhost:3000/health

Response:

{
  "status": "ok",
  "timestamp": "2026-03-04T12:00:00.000Z"
}

Legacy SSE Endpoints (MCP 2024-11-05)

For backwards compatibility with older MCP clients:

GET /sse

endpoint

SSE stream initializationEstablishes a Server-Sent Events connection for older clients that don’t support Streamable HTTP.Example:

curl -N http://localhost:3000/sse

POST /messages

endpoint

Client message postingSend messages from legacy clients to the server.Query Parameters:

sessionId: Session identifier (required)

Example:

curl -X POST "http://localhost:3000/messages?sessionId=your-session-id" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

Configuration

NPX/Node.js
Docker
Docker Compose
.env Configuration

# Using environment variable
MCP_TRANSPORT=http npx -y @ahdev/dokploy-mcp

# Or using command-line flag
npx -y @ahdev/dokploy-mcp --http

# After building from source
npm run start:http

# Run with HTTP mode
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

The container always uses port 3000 internally. Map it to your desired external port with -p <external>:3000.

version: '3.8'
services:
  dokploy-mcp-http:
    image: dokploy-mcp
    ports:
      - "${EXTERNAL_PORT:-3000}:3000"
    environment:
      - MCP_TRANSPORT=http
      - DOKPLOY_URL=${DOKPLOY_URL}
      - DOKPLOY_API_KEY=${DOKPLOY_API_KEY}
    restart: unless-stopped

# Start the service
docker-compose up -d dokploy-mcp-http

# View logs
docker-compose logs -f dokploy-mcp-http

# .env file
DOKPLOY_URL=https://your-dokploy-server.com/api
DOKPLOY_API_KEY=your-dokploy-api-token
MCP_TRANSPORT=http
EXTERNAL_PORT=3000

Choosing the Right Transport Mode

Use Stdio for

Desktop MCP clients
Local development
Single-user setups
Maximum security (no network exposure)

Use HTTP for

Web applications
Remote access
Multi-user scenarios
Microservices architecture

Client Compatibility

Stdio Mode Clients

Cursor - Full support
VS Code - Full support
Claude Desktop - Full support
Windsurf - Full support
Zed - Full support
BoltAI - Full support

HTTP Mode Clients

Modern clients (MCP 2025-03-26+) - Use /mcp endpoints automatically
Legacy clients (MCP 2024-11-05) - Use /sse and /messages endpoints
Custom integrations - Choose the appropriate protocol

The server automatically detects which protocol the client is using and routes requests accordingly. You don’t need to configure protocol selection manually.

Session Management

In HTTP mode, the server implements automatic session management:

Session Creation: Automatically created on initialization
Session ID: Generated using UUID v4
Session Tracking: Separate tracking for Streamable HTTP and SSE sessions
Automatic Cleanup: Sessions are cleaned up when:
- Client sends DELETE request
- Connection is closed
- Client disconnects

Session tracking in code:

// From src/http-server.ts:21-24
const transports = {
  streamable: {} as Record<string, StreamableHTTPServerTransport>,
  sse: {} as Record<string, SSEServerTransport>,
};

Port Configuration

The internal port is always 3000 and cannot be changed. Use EXTERNAL_PORT or Docker port mapping to expose it on a different port.

Port mapping examples:

# Docker: Map internal port 3000 to external port 8080
docker run -p 8080:3000 dokploy-mcp

# Access the server
curl http://localhost:8080/health

From source code:

// src/http-server.ts:11-12
// Container always uses port 3000 internally
const PORT = 3000;

Troubleshooting

Stdio Mode Issues

Server not starting

Check Node.js version (v18+ required)
Verify npx is available: npx --version
Check MCP client logs for error messages
Try running manually: npx -y @ahdev/dokploy-mcp

No tools showing up

Verify environment variables are set correctly
Check DOKPLOY_URL includes /api suffix
Verify API token is valid
Restart your MCP client

HTTP Mode Issues

Port already in use

If port 3000 is already in use:

# Find process using port 3000
lsof -i :3000

# Kill the process or use Docker port mapping
docker run -p 8080:3000 dokploy-mcp

Connection refused

Verify the server is running: curl http://localhost:3000/health
Check firewall rules aren’t blocking the port
Ensure MCP_TRANSPORT=http is set
Check server logs for errors

Session errors

If you receive “Invalid or missing session ID” errors:

Make sure you’re sending initialization request first
Store and reuse the session ID from initialization
Check that session hasn’t expired or been terminated
Verify mcp-session-id header is included in requests

Get Started

Configuration

Guides

Available Transport Modes

Stdio Mode (Default)

HTTP Mode (Streamable HTTP + Legacy SSE)

Modern Streamable HTTP Endpoints (MCP 2025-03-26)

Legacy SSE Endpoints (MCP 2024-11-05)

Configuration

Choosing the Right Transport Mode

Use Stdio for

Use HTTP for

Client Compatibility

Stdio Mode Clients

HTTP Mode Clients

Session Management

Port Configuration

Troubleshooting

Stdio Mode Issues

HTTP Mode Issues

See Also

Build docs developers (and LLMs) love

Get Started

Configuration

Guides

​Available Transport Modes

​Stdio Mode (Default)

​HTTP Mode (Streamable HTTP + Legacy SSE)

​Modern Streamable HTTP Endpoints (MCP 2025-03-26)

​Legacy SSE Endpoints (MCP 2024-11-05)

​Configuration

​Choosing the Right Transport Mode

Use Stdio for

Use HTTP for

​Client Compatibility

​Stdio Mode Clients

​HTTP Mode Clients

​Session Management

​Port Configuration

​Troubleshooting

​Stdio Mode Issues

​HTTP Mode Issues

​See Also

Build docs developers (and LLMs) love

Available Transport Modes

Stdio Mode (Default)

HTTP Mode (Streamable HTTP + Legacy SSE)

Modern Streamable HTTP Endpoints (MCP 2025-03-26)

Legacy SSE Endpoints (MCP 2024-11-05)

Configuration

Choosing the Right Transport Mode

Client Compatibility

Stdio Mode Clients

HTTP Mode Clients

Session Management

Port Configuration

Troubleshooting

Stdio Mode Issues

HTTP Mode Issues

See Also