Skip to main content
The Dokploy MCP Server provides a comprehensive set of 67 tools organized into five main categories for managing your Dokploy infrastructure through the Model Context Protocol.

​
Tool Categories

The tools are organized into functional groups that mirror the Dokploy platform structure:

Project Management

6 tools for creating, managing, and organizing projects

Application Management

26 tools for deploying and managing containerized applications

Domain Management

9 tools for configuring domains, SSL certificates, and routing

PostgreSQL Management

13 tools for PostgreSQL database lifecycle and configuration

MySQL Management

13 tools for MySQL database lifecycle and configuration

​
Category Breakdown

​
Project Management (6 tools)

Projects are the top-level organizational unit in Dokploy. These tools allow you to:
  • List and retrieve project information
  • Create new projects with custom configurations
  • Update project settings and environment variables
  • Duplicate projects with service selection
  • Remove projects and all associated resources
Key Tools: project-all, project-create, project-duplicate, project-remove

​
Application Management (26 tools)

Applications are containerized workloads deployed from various sources (Git, Docker). This category includes: Core Operations: Create, read, update, delete applications Deployment & Lifecycle: Deploy, redeploy, start, stop, reload applications Git Provider Configuration: Connect to GitHub, GitLab, Bitbucket, Gitea, or custom Git Build Configuration: Set build types (Dockerfile, Nixpacks, Buildpacks, Heroku) Environment & Networking: Manage environment variables, Traefik routing, monitoring Key Tools: application-create, application-deploy, application-saveGithubProvider, application-saveEnvironment

​
Domain Management (9 tools)

Domains handle routing, SSL/TLS certificates, and external access. These tools provide:
  • Domain association with applications and compose services
  • SSL certificate management (Let’s Encrypt, custom certificates)
  • Domain validation and DNS checking
  • Automatic domain generation and suggestions
  • Preview deployment domain configuration
Key Tools: domain-create, domain-update, domain-validateDomain, domain-generateDomain

​
PostgreSQL Management (13 tools)

Complete PostgreSQL database lifecycle management:
  • Database creation with custom configurations
  • Deployment and container management
  • Start, stop, reload, rebuild operations
  • External port exposure
  • Environment variable configuration
  • Status management
  • Project migration
Key Tools: postgres-create, postgres-deploy, postgres-saveExternalPort, postgres-saveEnvironment

​
MySQL Management (13 tools)

Identical capabilities to PostgreSQL, tailored for MySQL:
  • MySQL-specific features like root password management
  • Default image: mysql:8
  • All lifecycle and configuration operations
  • Compatible with MariaDB deployments
Key Tools: mysql-create, mysql-deploy, mysql-saveExternalPort, mysql-saveEnvironment

​
Tool Organization in Code

Tools are organized in the source code under src/mcp/tools/ with the following structure: 
src/mcp/tools/
├── index.ts                    # Exports all tools
├── toolFactory.ts              # Tool creation and validation framework
├── project/
│   ├── index.ts
│   ├── projectAll.ts
│   ├── projectCreate.ts
│   └── ...
├── application/
│   ├── index.ts
│   ├── applicationCreate.ts
│   ├── applicationDeploy.ts
│   └── ...
├── domain/
│   ├── index.ts
│   ├── domainCreate.ts
│   └── ...
├── postgres/
│   ├── index.ts
│   ├── postgresCreate.ts
│   └── ...
└── mysql/
    ├── index.ts
    ├── mysqlCreate.ts
    └── ...
Each tool is defined using the createTool factory from toolFactory.ts, which provides:
  • Zod schema validation for input parameters
  • Error handling with detailed messages
  • Semantic annotations for AI safety (see Tool Annotations)
  • Response formatting with structured output

​
General Usage Pattern

MCP clients (like Claude Desktop, Cline, or custom MCP clients) invoke tools using this pattern: 
// Tool invocation structure
{
  "tool": "tool-name",
  "input": {
    // Tool-specific parameters validated by Zod schema
  }
}

​
Example: Create and Deploy Application

// 1. Create a project
{
  "tool": "project-create",
  "input": {
    "name": "my-project",
    "description": "Production applications"
  }
}

// 2. Create an application
{
  "tool": "application-create",
  "input": {
    "name": "web-app",
    "projectId": "proj_abc123"
  }
}

// 3. Configure GitHub provider
{
  "tool": "application-saveGithubProvider",
  "input": {
    "applicationId": "app_xyz789",
    "repository": "my-app",
    "owner": "myorg",
    "branch": "main",
    "githubId": "gh_123",
    "enableSubmodules": false
  }
}

// 4. Deploy the application
{
  "tool": "application-deploy",
  "input": {
    "applicationId": "app_xyz789"
  }
}

​
Authentication Requirements

All tools require authentication to communicate with the Dokploy API:
The MCP server automatically handles authentication using environment variables. Ensure these are configured before using any tools.
Required Environment Variables: 
DOKPLOY_URL=https://your-dokploy-instance.com
DOKPLOY_API_KEY=your-api-key-here

​
How Authentication Works

  1. The apiClient utility (in src/utils/apiClient.ts) reads these environment variables
  2. Each tool request includes the API key in the Authorization header
  3. Invalid credentials return a 401 Unauthorized error with helpful messages
  4. The API key must have appropriate permissions for the requested operations
Keep your DOKPLOY_API_KEY secure. It provides full access to your Dokploy infrastructure. Use environment-specific keys and rotate them regularly.

​
Tool Response Format

All tools return responses in a consistent format: 
{
  "content": [
    {
      "type": "text",
      "text": "Success message or data in formatted string"
    }
  ],
  "isError": false  // true if operation failed
}
The ResponseFormatter utility (in src/utils/responseFormatter.ts) ensures consistent formatting:
  • Success responses include descriptive messages and data
  • Error responses provide context and troubleshooting guidance
  • Data is formatted as readable JSON when appropriate

​
Understanding Tool Annotations

Every tool includes semantic annotations that help AI systems understand tool behavior and safety characteristics:
  • readOnlyHint: Tool only reads data, makes no modifications
  • destructiveHint: Tool modifies or deletes resources irreversibly
  • idempotentHint: Tool can be safely retried with same result
  • openWorldHint: Tool interacts with external systems (Dokploy API)
Learn more about these annotations and their importance in Tool Annotations.

​
Error Handling

The tool framework provides comprehensive error handling:

​
Validation Errors

Zod schema validation catches invalid input before API calls: 
{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "Invalid input for tool: application-create\nValidation errors: name: Required, projectId: Required"
  }]
}

​
API Errors

Specific handling for common HTTP errors:
  • 401 Unauthorized: Invalid or missing API key
  • 404 Not Found: Resource doesn’t exist
  • 500 Internal Server Error: Dokploy server error
All errors include actionable guidance for resolution.

​
Next Steps

Tool Annotations

Learn about semantic annotations for AI safety

Project Tools

Explore project management tools

Application Tools

Discover application deployment tools

Getting Started

Set up the MCP server

Build docs developers (and LLMs) love

Get started for freeTalk to us