mcp-dokploy-fullapi-proxy

Dokploy Version: v0.28.8 - 473 Endpoints (last updated: 2026-03-27)

Multi-instance Dokploy API proxy MCP. 1 tool, ~200 tokens instead of 67+ tools consuming ~35,000 tokens per conversation. Supports multiple Dokploy instances via config file.

How it works

A single MCP tool dokploy(method, params?, instance?) acts as a thin proxy to Dokploy's tRPC API. All intelligence lives in skill files that Claude reads on-demand via Progressive Disclosure - only the relevant API section is loaded into context, saving 77-92% tokens per request.

Setup

npx -y mcp-dokploy-fullapi-proxy

Configuration

Multi-Instance (recommended)

Create a config file at ~/.mcp-dokploy/config.json:

{
  "instances": {
    "prod": {
      "url": "https://dokploy.example.com/api",
      "token": "your-api-token"
    },
    "staging": {
      "url": "https://staging.dokploy.dev/api",
      "token": "another-api-token"
    }
  },
  "defaultInstance": "prod"
}

The config file is searched in this order:

1. Path from DOKPLOY_CONFIG env var
2. ./config.json (current working directory)
3. ~/.mcp-dokploy/config.json (home directory)

Multi-Instance via env vars

For container/server deployments (Docker, Dokploy) where a config file is impractical, define multiple instances purely via env vars - two interchangeable styles:

A) JSON var (DOKPLOY_INSTANCES):

DOKPLOY_INSTANCES={"srv01":{"url":"https://a.example.com/api","token":"tok-a"},"hsh":{"url":"https://b.example.com/api","token":"tok-b"}}
DOKPLOY_DEFAULT_INSTANCE=srv01

B) Prefixed vars (DOKPLOY_<ID>_URL / DOKPLOY_<ID>_TOKEN):

DOKPLOY_SRV01_URL=https://a.example.com/api
DOKPLOY_SRV01_TOKEN=tok-a
DOKPLOY_HSH_URL=https://b.example.com/api
DOKPLOY_HSH_TOKEN=tok-b
DOKPLOY_DEFAULT_INSTANCE=srv01

The <ID> becomes a lowercase instance id (DOKPLOY_SRV01_URL -> srv01). Reserved names (URL, TOKEN, API, CONFIG, INSTANCES) are excluded so single-instance vars are not misparsed. DOKPLOY_DEFAULT_INSTANCE selects the default; otherwise default (if present) or the first id wins.

Require explicit instance: Set DOKPLOY_REQUIRE_INSTANCE=true to disable the silent default in multi-instance setups. Every dokploy() call must then pass instance explicitly, otherwise it errors. Prevents a fresh conversation from accidentally hitting the wrong instance. Has no effect with a single instance.

Single-Instance (env vars, backward-compatible)

For a single instance, env vars still work as before:

Variable	Required	Default	Description
DOKPLOY_URL	No	-	Dokploy API base URL (single instance, id default)
DOKPLOY_TOKEN	No	-	API authentication token
DOKPLOY_INSTANCES	No	-	JSON map of multiple instances
DOKPLOY_<ID>_URL / _TOKEN	No	-	Prefixed per-instance vars
DOKPLOY_DEFAULT_INSTANCE	No	-	Default instance id
DOKPLOY_REQUIRE_INSTANCE	No	false	Force explicit instance on every call (multi-instance only)
DOKPLOY_CONFIG	No	-	Path to config file

When using env vars without a config file, a default instance is created automatically. Env vars are also merged as fallback into config-file setups.

Get your API token from Dokploy: Settings -> Profile -> API/Token Section.

Usage with instances

// Uses default instance
dokploy("project.all")

// Target a specific instance
dokploy("project.all", {}, { instance: "staging" })

Architecture: This MCP uses a two-part setup:

1. MCP Server - gives the AI tool access to the dokploy() function
2. Skill/Instructions - teaches the AI which endpoints exist and how to call them

Without the skill, the AI has the tool but doesn't know the API. Tools that support native skill files get Progressive Disclosure (on-demand loading). Tools without skill support need the SKILL.md content injected as instructions.

---

Claude Desktop / Claude.ai

MCP: Native | Skills: Native (ZIP upload)

1. MCP Server

Add to claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

With config file (multi-instance):

{
  "mcpServers": {
    "dokploy-fullapi-proxy": {
      "command": "npx",
      "args": ["-y", "mcp-dokploy-fullapi-proxy"]
    }
  }
}

With env vars (single instance):

{
  "mcpServers": {
    "dokploy-fullapi-proxy": {
      "command": "npx",
      "args": ["-y", "mcp-dokploy-fullapi-proxy"],
      "env": {
        "DOKPLOY_URL": "https://your-dokploy-instance.com/api",
        "DOKPLOY_TOKEN": "your-api-token"
      }
    }
  }
}

2. Skill Upload

1. Download skill/dokploy-api.zip from this repo
2. Go to Claude.ai / Claude Desktop -> Customize -> Skills
3. Click + and upload dokploy-api.zip

---

Claude Code

MCP: Native | Skills: Native (.claude/skills/ directory)

1. MCP Server

claude mcp add dokploy-fullapi-proxy \
  -- npx -y mcp-dokploy-fullapi-proxy

Or with env vars for single instance:

claude mcp add dokploy-fullapi-proxy \
  -e DOKPLOY_URL=https://your-dokploy-instance.com/api \
  -e DOKPLOY_TOKEN=your-api-token \
  -- npx -y mcp-dokploy-fullapi-proxy

2. Skills

mkdir -p .claude/skills/dokploy-api
cp skill/*.md .claude/skills/dokploy-api/

---

Cursor

MCP: Native | Skills: Agent Skills (auto-discovered)

1. MCP Server

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "dokploy-fullapi-proxy": {
      "command": "npx",
      "args": ["-y", "mcp-dokploy-fullapi-proxy"]
    }
  }
}

2. Skills

mkdir -p .cursor/skills/dokploy-api
cp skill/*.md .cursor/skills/dokploy-api/

Or create a .cursor/rules/dokploy.mdc rule with SKILL.md contents.

---

Windsurf

MCP: Native | Skills: No native support (use Rules workaround)

1. MCP Server

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "dokploy-fullapi-proxy": {
      "command": "npx",
      "args": ["-y", "mcp-dokploy-fullapi-proxy"]
    }
  }
}

2. Skill Workaround

Create .windsurf/rules/dokploy.md with SKILL.md contents.

---

VS Code + GitHub Copilot

MCP: Native | Skills: No native support

1. MCP Server

Add to .vscode/mcp.json:

{
  "servers": {
    "dokploy-fullapi-proxy": {
      "command": "npx",
      "args": ["-y", "mcp-dokploy-fullapi-proxy"]
    }
  }
}

2. Skill Workaround

Paste SKILL.md contents into .github/copilot-instructions.md.

---

Cline

MCP: Native | Skills: No native support

Add MCP via Cline -> MCP Servers -> Edit. Paste SKILL.md into .clinerules.

---

Continue.dev

MCP: Native | Skills: No native support

Create .continue/mcpServers/dokploy.json with MCP config. Add SKILL.md to .continue/rules/dokploy.md.

---

OpenAI Codex CLI

MCP: Native | Skills: Native (.agents/skills/)

codex mcp add dokploy-fullapi-proxy \
  -- npx -y mcp-dokploy-fullapi-proxy

Copy skills: cp skill/*.md .agents/skills/dokploy-api/

---

Zed

MCP: Native | Skills: No native support

Add to Zed settings.json under context_servers. Use AGENTS.md for skill workaround.

---

Google Antigravity

MCP: Native | Skills: No native support

Add to ~/.gemini/settings.json. Use GEMINI.md for skill workaround.

---

Roo Code

MCP: Native | Skills: No native support

Configure via MCP settings panel. Add SKILL.md to .roo/rules/.

---

Compatibility Matrix

Tool	MCP	Native Skills	Skill Workaround	Config Location
Claude Desktop / Claude.ai	Yes	ZIP Upload	-	claude_desktop_config.json
Claude Code	Yes	.claude/skills/	-	.mcp.json
Cursor	Yes	Agent Skills	.cursor/rules/*.mdc	.cursor/mcp.json
Codex CLI	Yes	.agents/skills/	-	.codex/config.toml
Windsurf	Yes	No	.windsurf/rules/	~/.codeium/windsurf/mcp_config.json
VS Code + Copilot	Yes	No	.github/copilot-instructions.md	.vscode/mcp.json
Cline	Yes	No	.clinerules	MCP Settings JSON
Continue.dev	Yes	No	.continue/rules/	.continue/mcpServers/*.json
Zed	Yes	No	AGENTS.md	settings.json
Google Antigravity	Yes	No	GEMINI.md / Rules	~/.gemini/settings.json
Roo Code	Yes	No	.roo/rules/	MCP Settings JSON

---

Skill files

The skill/ directory contains API docs split by resource (auto-generated from Dokploy's OpenAPI spec):

File	Endpoints	Coverage
SKILL.md	-	Entry point, routing table
project.md	14	Projects & Environments
app.md	29	Applications
compose.md	28	Compose services
domain.md	9	Domains & SSL
database.md	70	PostgreSQL, MySQL, MariaDB, MongoDB, Redis
deployment.md	12	Deployments, Preview, Rollback
docker.md	7	Docker containers
server.md	23	Server, Cluster, Swarm
notification.md	38	Notifications
settings.md	73	Settings, Admin, Stripe, SSO
user.md	27	User & Organization
git.md	30	Git Providers
infra.md	85	Mounts, Redirects, Security, Ports, Backups, Certs, Registry, SSH, AI

Token comparison

	Official Dokploy MCP	mcp-dokploy-fullapi-proxy
Tools registered	67	1
Permanent context tokens	~35,000	~200
API coverage	~16% (67 of 436)	100% (473 endpoints)
On-demand tokens per request	0	~500-2,000 (1 skill file)
Typical savings	-	77-92% fewer tokens

How the skill system works

User: "Deploy my app"
  -> Claude reads SKILL.md routing table (~500 tokens)
  -> Claude reads app.md (~1,600 tokens)
  -> Claude calls: dokploy("application.deploy", { applicationId: "..." })

pick - Response Filter

The pick parameter filters large API responses to only the fields you need:

// Without pick: entire project tree (~50KB, ~10,000 tokens)
dokploy("project.all")

// With pick: only MySQL instances (~200 tokens)
dokploy("project.all", {}, { pick: ["mysqlId", "name", "appName"] })

Recursively traverses the JSON response, retains only matching field names, removes empty objects/arrays.

Building the skill ZIP

# Windows
Compress-Archive -Path skill\* -DestinationPath dokploy-api.zip -Force

# macOS / Linux
cd skill && zip -r ../dokploy-api.zip . && cd ..

Verify

Start a new conversation and ask:

Show me all Dokploy projects

With multi-instance:

Show me all projects on staging

License

MIT