MCP Patterns

Dokploy MCP Tool Patterns

The official @dokploy/mcp server exposes 546 tools across 50 categories (v0.29.14). Each tool is prefixed with mcp__dokploy__. This skill covers every category developers and operators use day-to-day: projects, applications, domains, compose, six database types, deployment history, the cross-cutting recovery chain, the AI router (new in v0.29), Docker introspection, settings/cleanup/health, schedules, patches, volume backups, and preview deployments. Categories not fully tabled here are listed at the end with a pointer to the matching reference file.

To reduce the exposed tool surface, set DOKPLOY_ENABLED_TAGS in .mcp.json env to a comma-separated list of categories (e.g. project,application,domain,compose,postgres,settings,deployment,docker,ai,rollback,schedule).

Project Management (9 tools)

Projects are the top-level container. Every application, database, and compose stack belongs to a project. Always create or identify a project before creating resources.

Usage notes

• project-all returns an array of project objects, each containing projectId, name, description, and nested arrays of applications, databases, and compose stacks.
• project-remove is destructive — it deletes all applications, databases, and compose stacks within the project. Confirm with the user before calling.
• project-duplicate creates a full copy including all nested resources. Use it for staging/production environment cloning.

Application Management (31 tools)

Applications are the primary deployment unit. They support multiple source types (GitHub, GitLab, Bitbucket, Gitea, generic Git, Docker image) and build types (Nixpacks, Dockerfile, Buildpacks, Docker image).

Core CRUD + Search (5 tools)

Lifecycle (5 tools)

Key distinction: deploy builds from source and deploys. redeploy re-runs the last deployment with current config. reload restarts the running container without rebuilding.

Git Provider Configuration (6 tools)

Connect an application to a Git source. Only one provider can be active at a time.

GitHub provider critical note: The repository parameter for saveGithubProvider must be the repository name only (e.g. "my-repo"), NOT the full URL. Dokploy constructs the clone URL as github.com/{owner}/{repository} — passing a full URL like https://github.com/org/repo causes a broken double-URL (github.com/org/https://github.com/org/repo). You also need the githubId — get it from gitProvider-getAll (then filter by type github). Required fields: applicationId, repository, branch, owner, githubId, enableSubmodules, triggerType (default "push"), watchPaths (array, use [] if none), buildPath (default "/").

Generic Git provider note: saveGitProvider requires ALL of: applicationId, customGitUrl (full SSH/HTTPS URL), customGitBranch, customGitBuildPath (e.g. "/"), enableSubmodules (boolean), watchPaths (array). Optionally customGitSSHKeyId for private repos. Omitting any required field causes a 400 validation error.

Build & Environment Configuration (3 tools)

Monitoring, Logs & Config (4 tools)

Deployment & Queue Management (8 tools)

Application usage notes

• application-create requires environmentId and name. The appName parameter becomes the container name and must be unique across the server.
• Resources live under a project's ENVIRONMENT (default production) — applications, databases, and compose stacks are created with an environmentId, not a projectId. Resolve it via project-one { projectId } → environments[] or environment-byProjectId { projectId }.
• application-saveEnvironment expects all of these parameters: applicationId, env (newline-separated KEY=VALUE string), buildArgs (newline-separated KEY=VALUE string for Docker build args — use empty string if none), buildSecrets (empty string if none), createEnvFile (boolean). Omitting any parameter causes a 400 validation error. Build args are critical for frameworks like Next.js where env vars (e.g. NEXT_PUBLIC_*) must be available during docker build.
• application-saveBuildType requires all of these parameters: applicationId, buildType (nixpacks, dockerfile, docker, buildpacks), dockerfile (filename, e.g. "Dockerfile"), dockerContextPath (e.g. "."), dockerBuildStage (empty string if none), herokuVersion (empty string if N/A), railpackVersion (empty string if N/A). Omitting any parameter causes a 400 validation error. When a project has a Dockerfile, default to buildType: "dockerfile" — ask the user to confirm.
• After calling application-deploy, the deployment runs asynchronously. Check deployment status via deployment-all filtered by applicationId to confirm completion. On failure, read logs with application-readLogs and iterate.
• application-markRunning is a manual override for stuck states. Use only when the container is running but Dokploy shows it as stopped.
• application-cleanQueues clears the deployment queue. Use when deployments are stuck in "queued" state. application-killBuild aborts a running build immediately.

Domain Management (9 tools)

Domains map hostnames to applications or compose services. Dokploy uses Traefik as the reverse proxy.

domain-create parameters

Domain usage notes

• Always call domain-validateDomain after creating a domain to confirm DNS is pointing to the server.
• domain-generateDomain creates a .traefik.me wildcard subdomain that resolves to the server's IP. Useful for development/testing without DNS setup.
• To enable HTTPS with Let's Encrypt, set https: true and certificateType: "letsencrypt". The domain must have valid DNS pointing to the server for certificate issuance to succeed.
• A single application can have multiple domains. Use this for aliases or www/non-www setups.
• To list domains attached to a compose stack, use domain-byComposeId (the old compose-fetchDomains tool was removed — this is its direct replacement).

Compose Management (31 tools)

Docker Compose stacks deploy multi-container applications defined by a docker-compose.yml file.

Core CRUD & Lifecycle

Source / Git Configuration

Unlike applications, compose git source is set via compose-update, not a separate saveGithubProvider call. Pass sourceType (github / gitlab / bitbucket / gitea / git), repository, branch, owner, composePath, and provider-specific IDs (githubId, gitlabProjectId, etc.) in a single update.

Templates

Build, Config & Logs

Deployment Management

Compose usage notes

• compose-create creates the stack record. After creation, set git source / compose file content via compose-update, then call compose-deploy.
• Setting a git source for compose: Use compose-update with sourceType and the matching provider fields. The old compose-saveGithubProvider / compose-saveGitlabProvider tools were consolidated into compose-update in the official MCP server.
• Listing domains for a compose stack: Use domain-byComposeId (not the removed compose-fetchDomains).
• compose-saveEnvironment works the same as the application equivalent — newline-separated KEY=VALUE string.
• compose-getConvertedCompose validates the compose file by rendering it with current env vars. Call this before compose-deploy to catch YAML errors early.
• Reading logs for a stack = read every container. compose-readLogs is per-container and requires containerId. To read all of them: compose-one { composeId } → appName/composeType; then docker-getContainersByAppNameMatch { appName, appType: "docker-compose" } (compose) or docker-getStackContainersByAppName { appName } (swarm) to list containers ({ containerId, name, state, status }); then loop compose-readLogs { composeId, containerId, tail, since, search } for each. The read-logs skill and /dokploy-dev:compose-logs automate this.

Database Management (5 types × 16 tools; LibSQL has 14)

Dokploy supports six managed database types. Five of them (postgres, mysql, mariadb, mongo, redis) have an identical set of 16 tools following the same naming pattern (the official server adds changePassword, readLogs, and search on top of the 13 core tools). LibSQL has only 14: there is no libsql-changePassword and no libsql-search, and its port tool is libsql-saveExternalPorts (plural) taking three port fields (externalPort, externalGRPCPort, externalAdminPort).

Tool pattern per database type

Replace {type} with postgres, mysql, mariadb, mongo, redis, or libsql:

Supported types

• PostgreSQL (postgres-*)
• MySQL (mysql-*)
• MariaDB (mariadb-*)
• MongoDB (mongo-*)
• Redis (redis-*)
• LibSQL (libsql-*) — new in the official server; embedded-SQL / SQLite-compatible managed service. Only 14 tools: no changePassword/search; port exposure via libsql-saveExternalPorts (externalPort, externalGRPCPort, externalAdminPort)

Database usage notes

• {type}-create requires environmentId and name, plus per-type required fields: postgres/mysql/mariadb → databaseName, databaseUser, databasePassword (mysql/mariadb also accept optional databaseRootPassword); mongo → databaseUser, databasePassword; redis → databasePassword; libsql → databaseUser, databasePassword, sqldNode, enableNamespaces (and more — see the full index).
• After {type}-create, call {type}-deploy to start the container. Creation only registers the resource.
• {type}-saveExternalPort exposes the database on the host network. Set externalPort to the desired port number. Set to null to remove external access. For LibSQL the tool is libsql-saveExternalPorts (plural) with externalPort, externalGRPCPort, and externalAdminPort.
• {type}-rebuild destroys and recreates the container. Data persists only if volumes are configured.
• {type}-changeStatus is a manual override. Use only when the actual container state differs from what Dokploy reports.
• {type}-changePassword rotates credentials without destroying data (not available for libsql). Follow up by updating connection strings in dependent applications.

Deployment History (9 tools)

deployment-all takes ONLY applicationId. For a compose stack use deployment-allByCompose { composeId }; for a server use deployment-allByServer { serverId }; deployment-allByType takes id + type.

Recovery Chain (cross-cutting)

When a deploy is misbehaving, recovery actions live across application-*, compose-*, deployment-*, docker-*, settings-*, and rollback-*. The canonical order from least-destructive to most:

See the debug-deploy skill for the diagnostic chain that produces the deploymentId/rollbackId you need to pass here.

AI Router (14 tools)

Provider-agnostic LLM integration for log analysis and recommendations. The AI router calls run on the Dokploy server, not the client.

apiUrl is OpenAI-compatible. Common providers: OpenAI (https://api.openai.com/v1), OpenRouter (https://openrouter.ai/api/v1), Groq (https://api.groq.com/openai/v1), Gemini (https://generativelanguage.googleapis.com/v1beta/openai), Ollama (http://host:11434/v1). See the ai-assist skill for the full setup workflow.

Docker Introspection (12 tools)

Raw Docker container operations on the Dokploy host. Essential for runtime debugging.

Choosing the discovery tool: for a standalone application use getContainersByAppLabel { appName, type: "standalone" } (most reliable — Dokploy stamps a known label). For a compose stack use getContainersByAppNameMatch { appName, appType: "docker-compose" } (or getStackContainersByAppName for swarm) — these return every service container. All return { containerId, name, state, status }; feed each containerId into compose-readLogs to read that container's logs.

Settings, Health & Cleanup (selected)

The settings-* namespace is the catch-all for server-wide operations. Highest-leverage subset for dev/debug:

For the cleanup chain run in order, use the /dokploy-dev:cleanup command — it confirms each destructive step and reports reclaimed space.

Schedule Router (6 tools)

Cron-like scheduled tasks scoped to a resource. Each schedule fires a command inside the target container.

Schedule targets:

• applicationId — runs command inside the app container at every tick
• composeId + serviceName — runs inside that specific compose service
• serverId — runs on the host (for remote servers)
• dokployServer: true — runs on the Dokploy host itself

cronExpression is a standard 5-field cron (e.g. "0 3 * * *" = daily at 03:00).

Patch Router (12 tools)

File-level overlays applied at deploy time. Useful when you can't / don't want to modify the source repo (e.g. tweaking a config file in an upstream image).

Patches apply during the deploy step, after the source is cloned but before the build. Use for per-environment config overrides without forking the upstream repo.

Volume Backups (6 tools)

Distinct from the resource-aware backup namespace — volumeBackups snapshot raw Docker volumes as-is (no DB-specific dump tooling).

Pair with the destination-* namespace to point at S3, R2, or another remote. Use for non-database persistent state (uploads, ML model files, caches).

Preview Deployments (4 tools)

Ephemeral per-PR / per-branch deploys spun up alongside the main application.

Preview deployments are typically triggered by webhook (PR opened/synced). The MCP surface above is for inspection and manual lifecycle control.

Common Workflow Patterns

1. Deploy a new application from GitHub

Execute these tools in sequence:

1. mcp__dokploy__project-create
   → { name: "my-project", description: "Production app" }
   → Returns: { projectId: "abc123" }

1b. mcp__dokploy__project-one
   → { projectId: "abc123" }
   → Returns environments[] — take environments[0].environmentId (default environment "production")

2. mcp__dokploy__application-create
   → { environmentId: "env123", name: "My App", appName: "my-app" }
   → Returns: { applicationId: "def456" }

3. mcp__dokploy__application-saveGithubProvider
   → { applicationId: "def456", repository: "my-repo", branch: "main", owner: "my-org" }

4. mcp__dokploy__application-saveBuildType
   → { applicationId: "def456", buildType: "dockerfile", dockerfile: "Dockerfile", dockerContextPath: ".", dockerBuildStage: "", herokuVersion: "", railpackVersion: "" }
   (Use "nixpacks" if no Dockerfile exists. Ask user which to use.)

5. mcp__dokploy__application-saveEnvironment
   → { applicationId: "def456", env: "DATABASE_URL=postgres://...\nNODE_ENV=production\nPORT=3000", buildArgs: "", buildSecrets: "", createEnvFile: false }

6. mcp__dokploy__domain-create
   → { applicationId: "def456", host: "app.example.com", https: true, certificateType: "letsencrypt", port: 3000 }

7. mcp__dokploy__application-deploy
   → { applicationId: "def456" }

After step 7, check the application status with application-one and deployment history with deployment-all filtered by applicationId to confirm the deployment succeeded. Stream logs with application-readLogs if it fails.

2. Provision a PostgreSQL database with external access

1. mcp__dokploy__project-create
   → { name: "databases" }
   → Returns: { projectId: "proj789" }
   (Or use project-all to find an existing project)
   Then resolve the environment: project-one { projectId } → environments[0].environmentId

2. mcp__dokploy__postgres-create
   → { environmentId: "env789", name: "Main DB", appName: "main-db", databaseName: "main", databaseUser: "postgres", databasePassword: "secure-password-here" }
   → Returns: { postgresId: "pg123" }

3. mcp__dokploy__postgres-deploy
   → { postgresId: "pg123" }

4. mcp__dokploy__postgres-saveExternalPort
   → { postgresId: "pg123", externalPort: 5432 }

The database is now accessible at server-ip:5432. Use the connection string: postgres://postgres:secure-password-here@server-ip:5432/postgres.

3. Add a domain with HTTPS to an existing application

1. mcp__dokploy__domain

…(truncated)