Dokploy Community Edition serves its own remote MCP server from the Dokploy panel itself, at https://<your-dokploy-host>/api/mcp. An MCP client talks to it over HTTPS (Streamable HTTP), so there is no local process to run and no API key to create. Upstream Dokploy v0.30.8 has no MCP endpoint and no MCP OAuth flow. The fork adds both.
This page covers the sign-in flow, the scopes you grant, the clients it works with, and the limits. For a short answer see the FAQ.
The tool list is built from the Dokploy API routers, so a tool is named after its API procedure, for example application-deploy, compose-deploy or deployment-queueList. Each tool belongs to one scope. A connection only sees the tools its scopes allow, and the permissions of the user behind the connection still apply underneath.
Add the server with your own panel address, then sign in once in the browser.
claude mcp add --transport http --scope user dokploy https://<your-dokploy-host>/api/mcp
/mcp, pick the dokploy server and choose Authenticate.The MCP Server card on the Settings, Profile page shows the endpoint and the exact add command for your instance, and lists every client you have authorized.
The server publishes standard discovery documents, so a compatible client configures itself:
S256 only).DOKPLOY_MCP_ACCESS_TOKEN_HOURS, DOKPLOY_MCP_REFRESH_TOKEN_DAYS and DOKPLOY_MCP_REFRESH_GRACE_SECONDS change these.The consent page shows one toggle per scope. Delete and Administration are off by default.
| Scope | On by default | What it allows |
|---|---|---|
dokploy:read |
yes | List and inspect projects, services, deployments, logs and settings |
dokploy:deploy |
yes | Deploy, redeploy, start, stop, restart, rebuild, roll back, cancel builds, clean deployment history |
dokploy:services:write |
yes | Create and update applications, Compose stacks, databases, domains, ports, mounts, schedules, patches and tags |
dokploy:services:delete |
no | Delete services and their resources |
dokploy:projects:write |
yes | Create, update and duplicate projects and environments |
dokploy:projects:delete |
no | Delete projects and environments |
dokploy:backups |
yes | Backups, backup policies, volume backups and destinations |
dokploy:admin |
no | Servers, registries, git providers, notifications, certificates, users, organization settings, and reading stored credentials |
Open Settings, Profile, find the MCP Server card and revoke the client. Its tokens stop working.
A client that cannot do the browser sign-in, or an unattended agent, can send a Dokploy API key in the x-api-key header. The key acts as the member who created it and is subject to the per-key rate limit. An API-key connection is not scoped: it gets all eight scopes, including Administration and both delete scopes, and only the member’s own role limits what it can do. Use a key from a member with a restricted role, or prefer OAuth when you want to grant less.
claude mcp add --transport http --scope user dokploy https://<your-dokploy-host>/api/mcp --header "x-api-key: <key>"
Any MCP client that supports the Streamable HTTP transport and either OAuth with dynamic client registration or a custom header. Claude Code is the client this guide was written and verified against. Dynamic client registration only accepts redirect URIs that are https or http on a loopback address (localhost, 127.0.0.1 or [::1]), so any other client must use such a redirect URI. Clients that only run local stdio servers need a bridge.
BETTER_AUTH_URL. Without one the Profile card says the server is unconfigured.DOKPLOY_MCP_DISABLED=true removes the endpoint entirely.application-one, compose-one and the database *-one tools blank the environment, build args and secrets, passwords, webhook tokens and similar fields (the reply carries secretsRedacted: true). To get them back a call must pass includeEnv: true and the grant must include dokploy:admin; without that scope the flag is ignored. This is enforced on the server, not only in the tool schema. Use application-envKeys or compose-envKeys when you only need variable names: they return the keys, never the values, under the read scope.env, buildArgs, buildSecrets, password, token, secret, privateKey, apiKey and similar, matched without regard to case) are blanked to "" at any depth, and credentials in a customGitUrl are stripped, so environment-one, project-one, project lists and search results do not carry values either. An Env array (a container’s environment) keeps its names and loses the values: KEY=VALUE becomes KEY=. A top-level object that had something blanked carries secretsRedacted: true. Only an admin passing includeEnv: true on a *-one service read gets values back. Tools that exist to hand back a credential (reading stored credentials, creating an API key, generating an instance or SCIM token or an SSH key pair, the swarm join commands) are exempt and still need dokploy:admin; their results stay raw.docker-getConfig, dockerImage-getImageConfig and server-getContainerProcesses (the full command line of a container’s processes) need dokploy:admin, and the command and args strings of that process listing (and only that tool; a service’s own command is configuration and reads back unchanged) have --token, --password, -p, token=, password= and URL credentials scrubbed. cluster-addWorker and cluster-addManager return a docker swarm join --token command and need dokploy:admin too.BAD_REQUEST) so a read-modify-write loop cannot erase a stored secret. The one exception is application-saveDockerProvider with an empty password and an empty or null username when no registry credentials are stored (a public image); clearing stored credentials still needs allowEmptySecrets. saveEnvironment replaces the whole variable set, and since values read back blank, a call that would drop variables that exist now, keep a name but blank its value, or send null for a block is refused with a BAD_REQUEST that counts them and, when the grant includes dokploy:read, names them (never values). The same guard covers the env, buildArgs, buildSecrets and preview variable blocks of the update tools of applications, Compose apps, every database service, projects and environments (shared env), for exactly the blocks present in the call. Read the names with envKeys, then pass replaceAll: true to replace a block on purpose. saveEnvironment also takes mergeEnv: true: the variables you send are set or added and every other one is kept, unsetKeys removes named ones (an array for env, or an object with env, buildArgs and buildSecrets arrays), and the reply carries counts of what was added, updated and unset. The merge runs on the server against the stored values, which never leave it. The dashboard is not affected. To clear a value on purpose, repeat the call with allowEmptySecrets: true, which only takes effect with dokploy:admin. Error messages have URL credentials and --token/token= values scrubbed.application-getDeployHooks), a schedule command, a file mount’s content, the Traefik configuration reads (settings-readTraefikConfig, settings-readMiddlewareTraefikConfig, settings-readWebServerTraefikConfig, application-readTraefikConfig), deployment logs, and a secret under a field with another name. All of these still read back under the read scope. Admin credential reads stay raw by design.