Troubleshooting

This guide covers common issues you might encounter when using Dokploy MCP Server and their solutions.

Installation Issues

npx command fails or package not found

Problem: Running npx -y @ahdev/dokploy-mcp fails with package errors.Solution: Try adding @latest to ensure you’re getting the most recent version:

npx -y @ahdev/dokploy-mcp@latest

Update your MCP client configuration:

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

Node.js version errors

Problem: Errors about missing fetch or other modern Node.js features.Solution: Dokploy MCP Server requires Node.js v18 or higher for native fetch support.Verify your Node.js version:

node --version

Install Node.js v18 or higher:

Using nvm (recommended):
```
nvm install 18
nvm use 18
```
Download from nodejs.org: https://nodejs.org/

Alternative: Use Docker to avoid Node.js version issues entirely.

Windows: Command not found or execution errors

Problem: MCP client can’t execute npx on Windows.Solution: Use cmd as the command wrapper:

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

Connection Issues

DOKPLOY_URL not set or invalid

Problem: Server fails to start with “DOKPLOY_URL is required” or connection errors.Solution: Verify your DOKPLOY_URL environment variable:

Check the URL format: Must include /api endpoint

✓ Correct: https://your-dokploy-server.com/api
✗ Wrong:   https://your-dokploy-server.com

Verify URL is accessible:

curl https://your-dokploy-server.com/api

Check for typos in your MCP client configuration

Use environment variables for easier management:

export DOKPLOY_URL="https://your-dokploy-server.com/api"
export DOKPLOY_API_KEY="your_token_here"
npx -y @ahdev/dokploy-mcp

DOKPLOY_API_KEY authentication failures

Problem: API requests fail with 401 Unauthorized or 403 Forbidden errors.Solution:

Verify your API key is correct and active in your Dokploy server
Generate a new API token from your Dokploy dashboard
Check environment variable is set correctly:
```
# In your shell
echo $DOKPLOY_API_KEY
```

Update MCP client config with the correct key:

{
  "mcpServers": {
    "dokploy-mcp": {
      "env": {
        "DOKPLOY_API_KEY": "your-valid-api-token"
      }
    }
  }
}

Check for special characters that might need escaping in JSON

Network timeout or connection refused

Problem: Unable to reach Dokploy server, timeout errors.Solution:

Verify Dokploy server is running:

curl -v https://your-dokploy-server.com/api

Check firewall rules allow outbound HTTPS connections
Test from same network to rule out VPN or network issues
Verify DNS resolution:
```
nslookup your-dokploy-server.com
```
Check for proxy settings that might interfere with connections

Transport Mode Issues

Stdio mode not working with MCP client

Problem: MCP client shows connection errors or server not responding.Solution:

Verify stdio is the default mode (no --http flag)
Check MCP client logs for detailed error messages

Test with MCP Inspector to isolate the issue:

npx @modelcontextprotocol/inspector npx -y @ahdev/dokploy-mcp

Ensure no output to stdout in custom builds (use stderr for logging)

Try Docker stdio mode if local setup fails:

{
  "mcpServers": {
    "dokploy-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "DOKPLOY_URL=https://your-server.com/api",
        "-e", "DOKPLOY_API_KEY=your_token",
        "dokploy-mcp"
      ]
    }
  }
}

HTTP mode not accessible

Problem: HTTP server starts but can’t access endpoints.Solution:

Verify HTTP mode is enabled:

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

# Using flag
npx -y @ahdev/dokploy-mcp --http

Check port 3000 is not in use:

# Linux/Mac
lsof -i :3000

# Windows
netstat -ano | findstr :3000

Test health endpoint:
```
curl http://localhost:3000/health
```
Check firewall allows port 3000

For Docker, verify port mapping:

docker run -p 8080:3000 -e MCP_TRANSPORT=http ...
curl http://localhost:8080/health

Legacy SSE client compatibility

Problem: Older MCP clients can’t connect to HTTP mode.Solution: The server supports both modern Streamable HTTP and legacy SSE protocols simultaneously.Legacy SSE endpoints are available at:

GET /sse - SSE stream initialization
POST /messages - Client message posting

Modern endpoints (default for new clients):

POST /mcp - Client requests
GET /mcp - Server notifications
DELETE /mcp - Session termination

Both protocols work simultaneously, so no configuration change is needed.

MCP Client Errors

Tools not appearing in MCP client

Problem: Dokploy MCP tools don’t show up in Claude Desktop, VS Code, or other clients.Solution:

Restart the MCP client after configuration changes
Check configuration file path is correct:
- Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (Mac)
- VS Code: Check VS Code MCP settings
- Cursor: ~/.cursor/mcp.json

Validate JSON syntax:

# Use a JSON validator
cat ~/.cursor/mcp.json | jq .

Check client logs for connection errors

Test with MCP Inspector to verify tools are available:

npx @modelcontextprotocol/inspector npx -y @ahdev/dokploy-mcp

Tool execution fails or returns errors

Problem: Tools show up but fail when executed.Solution:

Check API credentials are valid (see Connection Issues above)
Verify parameters match the tool schema
Review Dokploy server logs for API errors
Test with MCP Inspector to see detailed error messages
Check Dokploy permissions for the API key being used
Verify resource exists (e.g., project ID, application ID) in Dokploy

Performance issues or timeouts

Problem: Tools are slow or timing out.Solution:

Check Dokploy server performance and load
Verify network latency to Dokploy server:
```
ping your-dokploy-server.com
```
For Docker HTTP mode, check container resources:
```
docker stats dokploy-mcp-http
```
Increase timeout in MCP client configuration if available
Check for rate limiting on Dokploy API

Docker-Specific Issues

Docker image build failures

Problem: docker build fails during compilation.Solution:

Ensure Docker is up to date:
```
docker --version
```

Clear Docker build cache:

docker builder prune
docker build --no-cache -t dokploy-mcp .

Check disk space:
```
docker system df
```
Verify repository is cloned correctly:
```
ls -la src/
cat package.json
```

Health check failures in Docker

Problem: Container shows unhealthy status.Solution:

Check health endpoint manually:

docker exec dokploy-mcp-http wget -O- http://localhost:3000/health

View health check logs:

docker inspect --format='{{json .State.Health}}' dokploy-mcp-http | jq

Ensure HTTP mode is enabled:

docker exec dokploy-mcp-http env | grep MCP_TRANSPORT

Check container logs for startup errors:
```
docker logs dokploy-mcp-http
```
Health check only runs in HTTP mode - stdio containers always return healthy

Docker Compose environment variables not loading

Problem: Environment variables from .env file not being used.Solution:

Verify .env file location (same directory as docker-compose.yml)

Check .env file format:

DOKPLOY_URL=https://your-server.com/api
DOKPLOY_AUTH_TOKEN=your_token_here
MCP_TRANSPORT=http
EXTERNAL_PORT=3000

No quotes needed for simple values in .env

Recreate containers after .env changes:

docker-compose down
docker-compose up -d

Verify environment variables are loaded:
```
docker-compose config
```

Development Issues

TypeScript compilation errors

Problem: npm run build fails with type errors.Solution:

Run type check for detailed errors:
```
npm run type-check
```
Ensure dependencies are installed:
```
npm install
```
Check TypeScript version matches project requirements:
```
npm list typescript
```
Clean and rebuild:
```
npm run clean
npm run build
```

ESLint or formatting errors

Problem: Pre-commit checks fail with linting errors.Solution:

Auto-fix linting issues:
```
npm run lint:fix
```
Auto-format code:
```
npm run format
```
Run all pre-commit checks:
```
npm run precommit
```

Verification Commands

Use these commands to verify your setup:

# Check Node.js version
node --version

# Test Dokploy API connection
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-dokploy-server.com/api/projects

# Verify npm package
npm view @ahdev/dokploy-mcp version

# Test with MCP Inspector
npx @modelcontextprotocol/inspector npx -y @ahdev/dokploy-mcp@latest

# Check Docker image
docker images | grep dokploy-mcp

# Test HTTP health endpoint
curl http://localhost:3000/health

# Validate JSON configuration
cat ~/.cursor/mcp.json | jq .

Getting Help

Report an issue

If you encounter a bug or issue not covered here, please open an issue on GitHub with:

Detailed description of the problem
Steps to reproduce
Environment information (OS, Node.js version, MCP client)
Relevant error messages or logs

Read the documentation

Tools Reference - Complete tool documentation
TOOLS.md - Detailed tool schemas
CONTRIBUTING.md - Contributing guidelines

Next Steps

Review Installation guides for your specific MCP client
Learn about Docker deployment for production
Set up Local development environment
Explore all 67 available tools

Get Started

Configuration

Guides

Installation Issues

Connection Issues

Transport Mode Issues

MCP Client Errors

Docker-Specific Issues

Development Issues

Verification Commands

Getting Help

Report an issue

Read the documentation

Next Steps

Build docs developers (and LLMs) love

Get Started

Configuration

Guides

​Installation Issues

​Connection Issues

​Transport Mode Issues

​MCP Client Errors

​Docker-Specific Issues

​Development Issues

​Verification Commands

​Getting Help

Report an issue

Read the documentation

​Next Steps

Build docs developers (and LLMs) love

Installation Issues

Connection Issues

Transport Mode Issues

MCP Client Errors

Docker-Specific Issues

Development Issues

Verification Commands

Getting Help

Next Steps