| name | setup |
| description | This skill should be used when verifying Dokploy MCP connection, CLI installation, and API access. Use when user says "set up dokploy", "verify dokploy connection", "check dokploy", "test dokploy access", or enables the dokploy-dev plugin for the first time. |
Dokploy Setup and Verification
Verify all three access methods to Dokploy: MCP tools, CLI, and REST API. Run each step in order. Report the result of each step before moving to the next.
Prerequisites
The plugin needs two values — the Dokploy base URL (no /api suffix) and an access token — wired into all three interfaces:
| Interface | How it reads credentials | What to set |
|---|
MCP (@dokploy/mcp) | .mcp.json env block expands ${DOKPLOY_URL} / ${DOKPLOY_API_KEY} from the Claude Code environment (e.g. the env block of .claude/settings.local.json, or your shell) | DOKPLOY_URL, DOKPLOY_API_KEY |
REST API (curl) | Same env vars in your shell | DOKPLOY_URL, DOKPLOY_API_KEY |
CLI (@dokploy/cli) | Reads the SAME DOKPLOY_URL/DOKPLOY_API_KEY env vars (or a CWD .env); falls back to config.json written by dokploy auth -u <url> -t <token> | DOKPLOY_URL, DOKPLOY_API_KEY (or run dokploy auth) |
DOKPLOY_URL = the server base URL without /api (e.g. https://dokploy.example.com). MCP and REST endpoints live at /api/… under it.DOKPLOY_API_KEY = an access token from Settings > API/Tokens (or Settings > Profile). The same token works for MCP, REST, and the CLI.
Before verifying, confirm DOKPLOY_URL and DOKPLOY_API_KEY resolve to real values in the session environment. If either is missing, the MCP server fails with "Invalid URL" (empty DOKPLOY_URL) or 401 (bad key).
Optional: reduce the exposed tool surface
The official @dokploy/mcp server exposes 546 tools across 50 categories. If that is more than you need, set DOKPLOY_ENABLED_TAGS in the plugin's .mcp.json env block to a comma-separated list of categories (e.g. project,application,domain,compose,postgres,settings,deployment,docker). The server will then only expose tools from those categories. (DOKPLOY_TOOL_PRESET and DOKPLOY_DISABLED_TAGS are unreleased — merged upstream 2026-08-07, not in @dokploy/mcp 0.29.14, so the published package silently ignores them; use DOKPLOY_ENABLED_TAGS until the next release.)
How to obtain an API key
- Log in to the Dokploy dashboard.
- Navigate to Settings > API/Tokens.
- Click Generate Token.
- Copy the token immediately — it is shown only once.
Step 1: Verify MCP Connection
Call the MCP tool to list all projects:
mcp__dokploy__project-all
No parameters required.
Expected result
A JSON array of project objects. Even an empty array [] confirms the MCP connection is working.
If the call succeeds
Report: "MCP connection verified. Found N project(s)."
If the call fails
Check these causes in order:
- MCP server not running — The
.mcp.json file must point to a running Dokploy MCP server. Verify the command and args fields are correct.
- Environment variables missing — The MCP server needs
DOKPLOY_URL and DOKPLOY_API_KEY passed via env in .mcp.json. Confirm they resolve to real values.
- npx resolution failure — If the MCP server is launched via
npx, ensure @dokploy/mcp is available. Run:
npx @dokploy/mcp --version
- Network unreachable — The MCP server connects to the Dokploy API. If the server is on a private network, verify the machine running Claude Code can reach it.
Report the specific error message from the MCP call to help diagnose.
Step 2: Verify CLI Installation
Check the CLI is installed, then make a real call (there is NO dokploy verify command in the 0.29.x auto-generated CLI):
dokploy --version
dokploy project all
If the commands succeed
Report: "Dokploy CLI is installed and authenticated."
If dokploy is not found
Install the CLI globally:
npm install -g @dokploy/cli
Then authenticate — non-interactive:
dokploy auth -u https://dokploy.example.com -t $DOKPLOY_API_KEY
Or simply export DOKPLOY_URL / DOKPLOY_API_KEY — the CLI reads the same env vars as MCP/REST, and env wins over config.json.
- Server URL — the Dokploy instance URL (e.g.
https://dokploy.example.com). Do NOT include /api suffix for CLI auth.
- Access token — the same token used for
DOKPLOY_API_KEY (Settings > API/Tokens). dokploy auth validates it against /api/trpc/user.get and saves it to the CLI's config.json.
After authentication, re-run:
dokploy project all
If authentication fails
Check these causes:
- Wrong URL format — The CLI expects the base URL without
/api. If dokploy_url is https://dokploy.example.com/api, use https://dokploy.example.com for CLI auth.
- Expired token — Generate a new token from the Dokploy dashboard.
- Self-signed certificate — If the server uses a self-signed cert, set:
export NODE_TLS_REJECT_UNAUTHORIZED=0
Then retry. This is acceptable for local/dev environments only.
Step 3: Verify API Access
Make a direct HTTP request to the health endpoint:
curl -s -o /dev/null -w "%{http_code}" \
"$DOKPLOY_URL/api/settings.health" \
-H "x-api-key: $DOKPLOY_API_KEY"
Replace $DOKPLOY_URL (base URL, no /api) and $DOKPLOY_API_KEY with the actual configured values.
Expected result
HTTP status code 200.
If 200 is returned
Report: "API access verified. Dokploy server is healthy."
If a non-200 status is returned
| Status Code | Cause | Fix |
|---|
401 | Invalid or expired API key | Generate a new token in Settings > API/Tokens. Also verify you used the x-api-key header (NOT Authorization: Bearer) |
403 | Token lacks required permissions | Check token scope — it must have admin access |
404 | Wrong URL path | dokploy_url must be the base URL without /api (e.g. https://dokploy.example.com). Append /api/<endpoint> in curl calls |
000 or connection refused | Server unreachable | Check URL, DNS, firewall rules, and that Dokploy is running |
502 / 503 | Server is starting or overloaded | Wait 30 seconds and retry |
Additional API verification (optional)
To confirm full read/write access, call a non-destructive endpoint:
curl -s "$DOKPLOY_URL/api/project.all" \
-H "x-api-key: $DOKPLOY_API_KEY" \
-H "Content-Type: application/json"
This should return the same project list as the MCP call in Step 1.
Verification Summary
After completing all three steps, produce a summary table:
| Check | Status | Details |
|---|
| MCP Connection | PASS/FAIL | N projects found / error message |
| CLI Installation | PASS/FAIL | Version / not installed |
| API Access | PASS/FAIL | HTTP 200 / status code |
If all three pass, report: "Dokploy setup is complete. All access methods are working."
If any step fails, provide the specific fix instructions from the relevant section above.
Common Issues
| Problem | Symptoms | Solution |
|---|
| MCP not connecting | Tool calls return "server not found" or timeout | Verify .mcp.json exists, npx @dokploy/mcp works, and env vars are set |
| MCP returns "Invalid URL" | DOKPLOY_URL empty/wrong in the running server process | Set DOKPLOY_URL (base URL, no /api, no trailing slash), then restart Claude Code or /mcp → reconnect dokploy — a stdio MCP server reads env once at spawn and won't pick up edits to settings.local.json/.env until reconnected |
| MCP returns 401 "Authentication failed" | DOKPLOY_API_KEY invalid/stale in the running process | Fix the token, then reconnect the server (as above). Confirm settings.local.json and .env hold the same key |
| CLI auth fails | dokploy auth fails (401 / invalid) | Check the base URL has no /api suffix; regenerate the token. Env vars DOKPLOY_URL/DOKPLOY_API_KEY override config.json — make sure they're not stale |
| API 401 Unauthorized | curl returns 401 | Token expired or invalid — regenerate in dashboard |
| API connection refused | curl returns 000 or "connection refused" | Wrong URL, server down, or firewall blocking the port |
| Self-signed cert errors | UNABLE_TO_VERIFY_LEAF_SIGNATURE | Set NODE_TLS_REJECT_UNAUTHORIZED=0 for dev environments |
| MCP tools exist but return errors | Tool calls return API errors | dokploy_url is the base URL without /api for MCP, REST, and CLI. MCP server and REST endpoints live at /api/… under that base |
| Wrong port | Connection refused on default port | Dokploy defaults to port 3000; verify the actual port in your deployment |
What This Skill Does NOT Cover
- Application deployment workflows — See the
mcp-patterns skill for MCP tool sequences to deploy apps, provision databases, and manage domains.
- API endpoint details — See the
api-reference skill for the REST API surface (546 endpoints across 50 routers, Dokploy v0.29.14) with parameters and response schemas.
- Reading logs / debugging deploys — See the
read-logs and debug-deploy skills (and /dokploy-dev:logs, /dokploy-dev:compose-logs, /dokploy-dev:debug).
- CLI command recipes — See the
cli-recipes skill for common CLI workflows like deploying from a local directory, managing Docker Compose stacks, and backup operations.
- Troubleshooting deployment issues — See the
troubleshoot skill for diagnosing failed deployments, container crashes, and Traefik routing problems.
