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.

Related MCP server: mcp-compressor

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:

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

Skill files

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

Token comparison

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