Setup

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:

• 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

1. Log in to the Dokploy dashboard.
2. Navigate to Settings > API/Tokens.
3. Click Generate Token.
4. 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:

1. MCP server not running — The .mcp.json file must point to a running Dokploy MCP server. Verify the command and args fields are correct.
2. 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.
3. npx resolution failure — If the MCP server is launched via npx, ensure @dokploy/mcp is available. Run:

   npx @dokploy/mcp --version
   

4. 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        # versions in lockstep with Dokploy, e.g. 0.29.14
dokploy project all      # real API call — succeeds only when auth works

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:

1. 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.
2. Expired token — Generate a new token from the Dokploy dashboard.
3. 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

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:

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

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.