Environment variables

The Dokploy MCP Server is configured using environment variables. These variables control authentication, server connection, and transport settings.

Required Variables

These environment variables must be set for the server to function properly.

DOKPLOY_URL

string

required

Your Dokploy server API URL. This should include the full URL path to your Dokploy API endpoint.Example:

DOKPLOY_URL=https://your-dokploy-server.com/api

Make sure to include /api at the end of your Dokploy URL. This is the base path for all API endpoints.

DOKPLOY_API_KEY

string

required

Your Dokploy API authentication token. This token is used to authenticate all API requests to your Dokploy server.Example:

DOKPLOY_API_KEY=your-dokploy-api-token

How to Generate an API Token

Log in to your Dokploy dashboard
Navigate to Settings → API Tokens
Click Create Token or Generate New Token
Give your token a descriptive name (e.g., “MCP Server”)
Copy the generated token immediately (it will only be shown once)
Use this token as your DOKPLOY_API_KEY

Store your API token securely. Never commit it to version control or share it publicly.

Optional Variables

These variables are optional and provide additional configuration options.

MCP_TRANSPORT

string

default:"stdio"

The transport mode for the MCP server. Determines how the server communicates with clients.Possible values:

stdio - Standard input/output (default, for desktop clients)
http - HTTP/HTTPS with Streamable HTTP and legacy SSE support
sse - Same as http, enables both modern and legacy protocols

Example:

MCP_TRANSPORT=http

See Transport Modes for detailed information about each mode.

EXTERNAL_PORT

number

default:"3000"

The external port for HTTP/SSE mode. The container always uses port 3000 internally, but you can map it to a different external port.Example:

EXTERNAL_PORT=8080

This variable is only used when running in Docker. The internal port is fixed at 3000.

Configuration Examples

Basic Configuration (Stdio Mode)

For desktop MCP clients like Cursor, VS Code, or Claude Desktop:

{
  "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"
      }
    }
  }
}

HTTP Mode Configuration

For web applications or custom integrations:

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

Docker Configuration

When running with Docker:

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

Security Best Practices

Never commit credentials to version control

Always use environment variables or secure secret management systems. Never hardcode API keys in your code or configuration files that are committed to Git.Use .env files locally:

# .env (add to .gitignore)
DOKPLOY_URL=https://your-dokploy-server.com/api
DOKPLOY_API_KEY=your-secret-token

Make sure .env is in your .gitignore:

.env
.env.local
.env.*.local

Use environment-specific tokens

Create separate API tokens for development, staging, and production environments. This allows you to:

Rotate tokens without affecting other environments
Track usage by environment
Revoke access to specific environments independently

Rotate tokens regularly

Periodically generate new API tokens and update your configuration. This reduces the risk of compromised credentials.

Generate a new token in Dokploy
Update your environment variables
Test the new configuration
Revoke the old token

Use HTTPS for Dokploy URLs

Always use HTTPS URLs for your DOKPLOY_URL to ensure encrypted communication:

# Good
DOKPLOY_URL=https://your-dokploy-server.com/api

# Bad - unencrypted
DOKPLOY_URL=http://your-dokploy-server.com/api

Limit token permissions

When creating API tokens in Dokploy, grant only the minimum permissions required for the MCP server to function. This follows the principle of least privilege.

Troubleshooting

Authentication Errors

If you receive authentication errors:

Verify your DOKPLOY_API_KEY is correct
Check that the token hasn’t expired or been revoked
Ensure you’re using the correct Dokploy server URL
Verify the token has the necessary permissions

Connection Errors

If you can’t connect to your Dokploy server:

Verify the DOKPLOY_URL is correct and includes /api
Check that your Dokploy server is accessible from your network
Ensure there are no firewall rules blocking the connection

Test the URL in your browser or with curl:

curl -H "Authorization: Bearer YOUR_TOKEN" https://your-dokploy-server.com/api/health