@sattva/dokploy-mcp

MCP server for Dokploy — full API coverage generated from your instance's OpenAPI spec, either as one tool per endpoint (500+) or through 4 gateway tools that cost ~1% of the context. Deploy, manage, and monitor your self-hosted infrastructure through AI assistants.

Why This Package?

Feature	@sattva/dokploy-mcp	Community alternatives
Auth method	x-api-key header (correct)	Often missing or incorrect
API coverage	Every endpoint in the spec (546 on Dokploy v0.29.8)	Manual subset (~30-50 tools)
Context cost	2.7 KB in gateway mode — full API, ~1% of the payload	Whatever the tool list weighs
Dependencies	2 (@modelcontextprotocol/sdk, zod)	Often pulls in OpenAI SDK, axios, etc.
Update strategy	Auto-generates from live spec	Manual maintenance required
Safety annotations	readOnlyHint / destructiveHint	Usually missing
Package size	~25 KB (dist only)	Varies

Key Features

• Dynamic OpenAPI discovery — fetches the spec from your Dokploy instance at startup, so new API endpoints are available immediately after a Dokploy upgrade
• Complete coverage — every endpoint in your instance's spec becomes callable (546 on Dokploy v0.29.8)
• Correct x-api-key authentication — uses the proper header that Dokploy expects
• Zod input validation — OpenAPI schemas are converted to Zod for runtime type checking
• Safety annotations — read-only operations are marked with readOnlyHint, destructive ones with destructiveHint
• Gateway mode — DOKPLOY_MODE=gateway exposes the entire API through 4 tools instead of 500+, cutting the tools/list payload by ~99% (239 KB → 2.7 KB) with no loss of coverage
• Tool filtering — DOKPLOY_TOOLS patterns and DOKPLOY_READONLY=1 trim 500+ tools down to the profile you actually use (much smaller context for the AI)
• Curated descriptions — 130+ most-used tools ship hand-written descriptions instead of bare METHOD /path
• Resilient startup — the OpenAPI spec is cached on disk, so a temporarily unreachable Dokploy doesn't take the MCP server down
• Bounded responses — compact JSON, oversized responses truncated with an explicit marker; 30s request timeout, GET retried on 5xx/429
• Zero-config updates — upgrade Dokploy, restart the MCP server, get new tools
• Minimal dependencies — only @modelcontextprotocol/sdk and zod

Quick Start

Claude Code (CLI)

claude mcp add --transport stdio \
  --env DOKPLOY_URL=https://dokploy.example.com \
  --env DOKPLOY_API_KEY=your-api-key-here \
  dokploy -- npx -y @sattva/dokploy-mcp@latest

Manual configuration

Add the following to your MCP client config file:

{
  "mcpServers": {
    "dokploy": {
      "command": "npx",
      "args": ["-y", "@sattva/dokploy-mcp@latest"],
      "env": {
        "DOKPLOY_URL": "https://dokploy.example.com",
        "DOKPLOY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Client	Config file
Claude Code	~/.claude/mcp.json
Claude Desktop	claude_desktop_config.json
Cursor	.cursor/mcp.json
Windsurf	~/.windsurf/mcp.json

Run directly from the command line

DOKPLOY_URL=https://dokploy.example.com \
DOKPLOY_API_KEY=your-api-key-here \
npx @sattva/dokploy-mcp@latest

Configuration

Variable	Required	Description
DOKPLOY_URL	Yes	Base URL of your Dokploy instance (e.g. https://dokploy.example.com). Do not append /api — the server adds it automatically.
DOKPLOY_API_KEY	Yes	API key for authentication
DOKPLOY_MODE	No	tools (default) — one tool per endpoint, unchanged behaviour. gateway — 4 tools that cover the whole API. both — gateway plus the individual tools. See Gateway Mode.
DOKPLOY_TOOLS	No	Comma-separated tool name patterns with * wildcards, e.g. project_*,application_*,docker_getContainers. Only matching tools are exposed. Unset = all tools.
DOKPLOY_READONLY	No	1/true exposes only read-only (GET) tools — a safe profile for monitoring and inspection. Combines with DOKPLOY_TOOLS.
DOKPLOY_TIMEOUT_MS	No	Request timeout in milliseconds (default 30000). GET requests are retried twice on 5xx/429/network errors.
DOKPLOY_MAX_RESPONSE_CHARS	No	Truncate tool responses above this size (default 50000). Arrays are cut item-wise with a _truncated marker.

Why filter? The full tool list is ~540 tools / ~230 KB of tools/list payload (~60k tokens). A typical profile like DOKPLOY_TOOLS=project_*,application_*,compose_*,deployment_*,docker_*,domain_* cuts that by ~70%.

Spec cache: after each successful start the OpenAPI spec is saved to the OS temp dir. If Dokploy is unreachable on the next start, the server boots from the cached spec instead of dying (tool calls will still fail until Dokploy is back).

Gateway Mode

500+ tools cost ~60k tokens of context before the assistant answers a single question. Gateway mode replaces them with 4 tools that reach the same endpoints through discovery:

"env": {
  "DOKPLOY_URL": "https://dokploy.example.com",
  "DOKPLOY_API_KEY": "your-api-key-here",
  "DOKPLOY_MODE": "gateway"
}

Tool	Annotation	Purpose
dokploy_search	readOnlyHint	Find endpoints by keyword — returns names, kind, and required params
dokploy_describe	readOnlyHint	Full parameter schema for one endpoint
dokploy_call	readOnlyHint	Invoke a read-only (GET) endpoint
dokploy_mutate	destructiveHint	Invoke a writing endpoint (create/update/deploy/delete)

Typical flow: dokploy_search("deploy application") → dokploy_describe("application_deploy") → dokploy_mutate("application_deploy", {applicationId}).

Why four tools and not three? A single do-everything call tool would erase the read/write distinction — the client could no longer tell a listing from a deletion, and destructiveHint would be meaningless. Splitting them keeps the annotation honest: a client can allow dokploy_call freely and gate dokploy_mutate behind confirmation. Each tool refuses endpoints of the wrong kind before any network request, and DOKPLOY_READONLY=1 drops dokploy_mutate entirely.

Measured (Dokploy v0.29.8, 546 endpoints):

Mode	Tools	tools/list
tools (default)	546	239.3 KB (~61k tokens)
gateway	4	2.7 KB (~0.7k tokens) — 98.9% smaller
both	550	242.0 KB

A full discover-and-invoke cycle (tools/list + search + describe) costs ~0.8k tokens — less than the old tool list spent on a single letter of the alphabet.

Trade-off: gateway mode adds two round-trips before the first call, and the assistant no longer sees every operation up front — it has to search. Prefer tools mode (or a DOKPLOY_TOOLS profile) when you always work with the same handful of endpoints; prefer gateway for broad, exploratory access at minimal context cost. DOKPLOY_TOOLS and DOKPLOY_READONLY constrain both surfaces, so a filtered-out endpoint stays unreachable through the gateway too.

Getting Your API Key

1. Log in to your Dokploy dashboard
2. Go to Settings → Profile
3. Under API / Tokens, click Generate Token
4. Copy the generated key

Tool Naming Convention

OpenAPI paths are converted to tool names:

OpenAPI Path	Tool Name
/api/application.one	application_one
/api/project.all	project_all
/api/server.create	server_create
/api/docker.getContainers	docker_getContainers
/api/domain.update	domain_update

Tool Categories

The tools are organized by Dokploy's API structure:

Category	Examples	Description
Application	application_one, application_create, application_deploy	Manage applications
Project	project_all, project_create, project_one	Manage projects
Server	server_all, server_create, server_one	Manage servers
Docker	docker_getContainers, docker_getConfig	Docker operations
Domain	domain_create, domain_update, domain_all	Domain management
Deployment	deployment_all, deployment_allByApplication	Deployment history
Database	mysql_*, postgres_*, mariadb_*, mongo_*, redis_*	Database services
Compose	compose_*	Docker Compose services
Registry	registry_all, registry_create, registry_one	Container registries
Certificate	certificates_*	SSL certificates
User	user_all, user_one, user_update	User management
Settings	settings_*	Instance settings

Safety Annotations

Every tool is annotated based on its HTTP method and operation:

• readOnlyHint: true — GET requests (safe to call, no side effects)
• destructiveHint: true — operations that deploy, delete, stop, restart, or otherwise modify state

This helps AI assistants make safer decisions about which tools to call without confirmation.

Troubleshooting

DOKPLOY_URL must not end with /api

The MCP server appends /api to the base URL automatically. If you set DOKPLOY_URL=https://dokploy.example.com/api, requests will go to /api/api/... and fail.

Correct: https://dokploy.example.com Wrong: https://dokploy.example.com/api

Windows: npx does not pass environment variables

On Windows, npx launched via cmd /c may not forward env variables correctly. Use node with the full path to dist/index.js instead:

{
  "mcpServers": {
    "dokploy": {
      "command": "node",
      "args": ["C:\\Users\\<you>\\AppData\\Roaming\\npm\\node_modules\\@sattva\\dokploy-mcp\\dist\\index.js"],
      "env": {
        "DOKPLOY_URL": "https://dokploy.example.com",
        "DOKPLOY_API_KEY": "your-api-key-here"
      }
    }
  }
}

To find the path after a global install:

npm install -g @sattva/dokploy-mcp
npm root -g
# → C:\Users\<you>\AppData\Roaming\npm\node_modules

Connection refused / timeout

• Verify DOKPLOY_URL is reachable: curl https://dokploy.example.com/api/settings.getOpenApiDocument -H "x-api-key: YOUR_KEY"
• Check that port 443 (or your custom port) is open
• Ensure the API key is valid and has not been revoked

0 tools registered

If the server starts but registers 0 tools, the OpenAPI spec may be empty or in an unexpected format. Check your Dokploy version — the OpenAPI endpoint was introduced in Dokploy v0.9+.

Development

git clone https://github.com/sattva2020/dokploy-mcp.git
cd dokploy-mcp
npm install
npm run build

Test locally

# Watch mode
npm run dev

# Point your MCP client to the local build:

{
  "mcpServers": {
    "dokploy": {
      "command": "node",
      "args": ["/path/to/dokploy-mcp/dist/index.js"],
      "env": {
        "DOKPLOY_URL": "https://dokploy.example.com",
        "DOKPLOY_API_KEY": "your-api-key"
      }
    }
  }
}

Architecture

┌────────────────┐     ┌──────────────┐     ┌──────────────────┐
│  MCP Client    │────▶│  MCP Server  │────▶│  Dokploy API     │
│  (Claude, etc) │◀────│  (this pkg)  │◀────│  (your instance) │
└────────────────┘     └──────────────┘     └──────────────────┘
       stdio            At startup:
                        1. Fetch OpenAPI spec
                        2. Parse paths → tools
                        3. Build Zod schemas
                        4. Register with MCP SDK

Pipeline:

1. Startup — reads DOKPLOY_URL and DOKPLOY_API_KEY from environment
2. Spec fetch — calls GET /api/settings.getOpenApiDocument on the Dokploy instance
3. Tool generation — iterates over every path+method in the OpenAPI spec, builds Zod input schemas from parameters and request bodies
4. Registration — registers each tool with the MCP SDK, including descriptions and safety annotations
5. Runtime — when a tool is called, the server makes the corresponding HTTP request to Dokploy with x-api-key auth and returns the JSON response

License

MIT — Copyright (c) 2025-2026 Sattva