mcp-patterns

# Dokploy MCP Tool Patterns The official `@dokploy/mcp` server exposes **604 tools across 57 categories (Dokploy v0.30.7, `@dokploy/mcp` 0.30.7)**. Each tool is prefixed with `mcp__plugin_dokploy-dev_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, Docker introspection and host diagnostics, networks, vault and DNS providers, settings/cleanup/health, schedules, patches, volume backups, and preview deployments. **Responses are redacted by default (`DOKPLOY_REDACT_ENV=true` since `@dokploy/mcp` 0.30.0) — read "Redaction" below before diagnosing env or credential problems.** 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 these in the `.mcp.json` `env` block (a category is the operation prefix, matched case-insensitively — `previewDeployment`, `volumeBackups`, `dockerVolume` …): - `DOKPLOY_TOOL_PRESET` (≥ 0.30.0): `all` (default), `minimal` = project + application, `core` = project + server + application, `deploy` = project + environment + server + application + compose + domain + deployment, `databases` = the six database categories, `git` = github + gitlab + bitbucket + gitea + gitProvider + registry + sshKey. - `DOKPLOY_ENABLED_TAGS`: explicit comma-separated list (e.g. `project,application,domain,compose,postgres,settings,deployment,docker,ai,rollback,schedule`); wins over the preset. - `DOKPLOY_DISABLED_TAGS` (≥ 0.30.0): categories to drop afterwards, applied last. No preset contains `docker`, `ai`, `settings`, `rollback` or `schedule`, which `/dokploy-dev:debug` uses — list them in `DOKPLOY_ENABLED_TAGS` when you trim the toolset. --- ## Redaction (`DOKPLOY_REDACT_ENV`, on by default since 0.30.0) The MCP server rewrites every response (and its own log lines) before the model sees it: a field whose name **ends with** an entry of the redaction list becomes the string `[REDACTED]`. Matching is case-insensitive, at any depth, on the key only. The default list: `env`, `buildArgs`, `buildSecrets`, `previewBuildSecrets`, `composeFile`, `dockerCompose`, `environment`, `password` and the `*Password` fields, `token` and the `*Token` fields, `secret`, `clientSecret`, `apiKey`, `secretAccessKey`, `accessKey`, `licenseKey`, `privateKey`, `sshKey`, `customGitSSHKey`, `dockerAuth`. | You call | You get | |---|---| | `application-one`, `compose-one`, `{db}-one` | `env`, `buildArgs`, `composeFile`, passwords = `[REDACTED]` — not even the variable **names**. A `null` stays `null` (`env: null` = never set); `[REDACTED]` means *a string, possibly empty* | | `docker-getConfig` | the container's `Env` = `[REDACTED]` | | `settings-getOpenApiDocument` | 27 operations (every `*-saveEnvironment`, `*-changePassword`, `*-refreshToken`, `user-createApiKey`, …) come back as bare `[REDACTED]`, and secret-named request fields lose their schema in 73 more — regenerate API indexes over REST, never through MCP | | any create/update tool | **arguments are not redacted** — writes work normally; only the response echo is redacted | | `docker-readContainerFile`, `dockerVolume-readVolumeFile` | the file body is an opaque string, so it is **not** redacted — do not read `.env`-style files through these tools unless you want the values in context | Rules that follow: 1. **Diagnose from names and logs first.** A stack trace or `getaddrinfo ENOTFOUND db` shows the failing host without exposing a secret; `docker-getContainersByAppLabel`, `application-readLogs` and `deployment-readLogs` are unaffected. 2. **Never write `[REDACTED]` back.** `application-saveEnvironment` / `compose-saveEnvironment` replace the *whole* `env` string (and, for applications, `buildArgs`/`buildSecrets`), so a read-modify-write through MCP would overwrite every variable with the placeholder. Change one variable with the REST recipe below, or supply the complete new value yourself. 3. **Reading values on purpose** = set `DOKPLOY_REDACT_ENV=false` in `.mcp.json` and reconnect the `dokploy` server, or call REST/CLI (never redacted). Anything printed lands in the model context, so prefer pipes that do not print values: ```bash # variable NAMES only (values never printed) curl -s -G "$DOKPLOY_URL/api/application.one" -H "x-api-key: $DOKPLOY_API_KEY" \ --data-urlencode "applicationId=<id>" \ | jq -r '(.env // "") | split("\n")[] | select(test("^[A-Za-z_][A-Za-z0-9_]*=")) | split("=")[0]' # change ONE variable, keep the rest (env + companion fields are sent as a unit) NEW='<new-value>' curl -s -G "$DOKPLOY_URL/api/application.one" -H "x-api-key: $DOKPLOY_API_KEY" \ --data-urlencode "applicationId=<id>" \ | jq --arg v "DATABASE_URL=$NEW" '{applicationId, buildArgs, buildSecrets, createEnvFile, env: ((.env // "") | sub("(?m)^DATABASE_URL=.*"; $v))}' \ | curl -s -X POST "$DOKPLOY_URL/api/application.saveEnvironment" \ -H "x-api-key: $DOKPLOY_API_KEY" -H "Content-Type: application/json" -d @- ``` `DOKPLOY_REDACT_FIELDS` **replaces** the default list (it is not additive) — set it only to narrow or widen on purpose. For secrets that should never be pasted at all, v0.30 can resolve them at deploy time from an external manager — see "Vault providers" below. --- ## Project Management (11 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. | Tool | Description | Parameters | |---|---|---| | `mcp__plugin_dokploy-dev_dokploy__project-all` | List all projects | None | | `mcp__plugin_dokploy-dev_dokploy__project-allForPermissions` | List projects the current token can access | None | | `mcp__plugin_dokploy-dev_dokploy__project-one` | Get a single project by ID | `projectId` (string, required) | | `mcp__plugin_dokploy-dev_dokploy__project-create` | Create a new project | `name` (string, required), `description` (string, optional) | | `mcp__plugin_dokploy-dev_dokploy__project-update` | Update project metadata | `projectId` (string, required), `name` (string), `description` (string) | | `mcp__plugin_dokploy-dev_dokploy__project-duplicate` | Duplicate an environment's resources | `sourceEnvironmentId` (required), `name` (required), `description`, `includeServices`, `selectedServices`, `duplicateInSameProject` | | `mcp__plugin_dokploy-dev_dokploy__project-remove` | Delete a project and all its resources | `projectId` (string, required) | | `mcp__plugin_dokploy-dev_dokploy__project-search` | Search projects (free-text key is `q`; default `limit` 20) | `q`, `name`, `description`, `limit`, `offset` | | `mcp__plugin_dokploy-dev_dokploy__project-homeStats` | Aggregate dashboard/home stats across projects (counts and running/error/idle status) | None | | `mcp__plugin_dokploy-dev_dokploy__project-onboardingStatus` | Dokploy Cloud onboarding-wizard state (trial, plan, project count) | None | | `mcp__plugin_dokploy-dev_dokploy__project-completeOnboarding` | Mark the onboarding wizard as done | None | ### 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. --- ## Overview Dashboard (3 tools + `server-getServices`, v0.30.0+) The project Overview page (Services, Backups, Domains at a glance) is available as three parameter-less reads; use them for `/dokploy-dev:status`-style summaries instead of walking `project-all` → `project-one`. | Tool | Description | Parameters | |---|---|---| | `mcp__plugin_dokploy-dev_dokploy__overview-services` | Services (applications, compose stacks, databases) with their status | None | | `mcp__plugin_dokploy-dev_dokploy__overview-backups` | Configured backups and their state | None | | `mcp__plugin_dokploy-dev_dokploy__overview-domains` | Domains across projects | None | | `mcp__plugin_dokploy-dev_dokploy__server-getServices` | Services deployed on one remote server | `serverId` (required) | --- ## Application Management (32 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) | Tool | Description | Key Parameters | |---|---|---| | `mcp__plugin_dokploy-dev_dokploy__application-one` | Get application details | `applicationId` | | `mcp__plugin_dokploy-dev_dokploy__application-create` | Create a new application | `environmentId` (required), `name` (required), `appName` (unique slug), `serverId`, `sourceType` (`github` \| `docker` \| `git` \| `gitlab` \| `bitbucket` \| `gitea` \| `drop`) | | `mcp__plugin_dokploy-dev_dokploy__application-update` | Update application settings (also per-service networks: `networkIds`, `detachDokployNetwork`, `networkSwarm` — see "Docker Networks") | `applicationId`, plus any updatable fields | | `mcp__plugin_dokploy-dev_dokploy__application-delete` | Delete an application | `applicationId` | | `mcp__plugin_dokploy-dev_dokploy__application-search` | Search applications (all filters optional, AND-combined). **The free-text key is `q`; an unknown key such as `query` is silently stripped and the call returns unfiltered rows** (default `limit` 20, max 100) | `q`, `name`, `appName`, `description`, `repository`, `owner`, `dockerImage`, `projectId`, `environmentId`, `limit`, `offset` | ### Lifecycle (5 tools) | Tool | Description | Parameters | |---|---|---| | `mcp__plugin_dokploy-dev_dokploy__application-deploy` | Trigger a new deployment | `applicationId` | | `mcp__plugin_dokploy-dev_dokploy__application-redeploy` | Redeploy with latest config | `applicationId` | | `mcp__plugin_dokploy-dev_dokploy__application-start` | Start a stopped application | `applicationId` | | `mcp__plugin_dokploy-dev_dokploy__application-stop` | Stop a running application | `applicationId` | | `mcp__plugin_dokploy-dev_dokploy__application-reload` | Reload application (zero-downtime) | `applicationId`, `appName` (both required) | **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. | Tool | Description | Key Parameters | |---|---|---| | `mcp__plugin_dokploy-dev_dokploy__application-saveGithubProvider` | Connect to GitHub | `applicationId`, `repository` (repo name only — NOT full URL), `branch`, `owner`, `githubId`, `enableSubmodules` | | `mcp__plugin_dokploy-dev_dokploy__application-saveGitlabProvider` | Connect to GitLab | `applicationId`, `repository`, `branch`, `gitlabProjectId` | | `mcp__plugin_dokploy-dev_dokploy__application-saveBitbucketProvider` | Connect to Bitbucket | `applicationId`, `repository`, `branch`, `owner` | | `mcp__plugin_dokploy-dev_dokploy__application-saveGiteaProvider` | Connect to Gitea | `applicationId`, `repository`, `branch`, `owner` | | `mcp__plugin_dokploy-dev_dokploy__application-saveGitProvider` | Connect to any Git URL | `applicationId`, `customGitUrl`, `customGitBranch`, `customGitBuildPath`, `enableSubmodules`, `watchPaths` | | `mcp__plugin_dokploy-dev_dokploy__application-disconnectGitProvider` | Remove Git connection | `applicationId` | **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)