How do I use coolify?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@coolify Show me all applications and their deployment statuses." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

coolify

by VBCDX

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

@vbcdx/coolify-plugin

An MCP server for the Coolify v4 API. It gives AI agents a fixed set of 27 tools for applications, deployments, environment variables, databases, services, projects and servers, with a write gate and verified results.

Runs over stdio (for a local agent harness) or Streamable HTTP (as a network service or container).
Write gate: reads only by default. Writes and destructive operations need explicit opt-in.
Per-call credentials: each call names the credential file it uses, so several agents can share one server with their own tokens.
Verified results: a write that cannot be confirmed is reported as unverified, never as success, and is never retried. deploy, start_application, restart_application, stop_application and cancel_deployment return accepted: Coolify took the request, but the tool does not wait for the result.

Coolify also ships a native MCP endpoint. This package covers a smaller, fixed set of operations and adds per-call credentials and the write gate.

The full specification is in docs/contract.md.

Requirements

Node.js 22 or later
A Coolify v4 instance and an API token for it

Related MCP server: Coolify MCP Server

Install

npm install -g @vbcdx/coolify-plugin

This installs the vbcdx-coolify command. To run it without installing:

npx -y --package=@vbcdx/coolify-plugin vbcdx-coolify --help

Usage

vbcdx-coolify mcp          Start the stdio MCP server (default)
vbcdx-coolify serve        Start the network MCP server (Streamable HTTP)
vbcdx-coolify healthcheck  Probe a running serve endpoint; exit 0 if healthy
vbcdx-coolify manifest     Print the JSON tool manifest
vbcdx-coolify --help
vbcdx-coolify --version

Register with an MCP client

Claude Code:

claude mcp add coolify --scope user \
  -e VBCDX_COOLIFY_URL=https://coolify.example.com \
  -e VBCDX_COOLIFY_WRITES=off \
  -- vbcdx-coolify mcp

Codex:

codex mcp add coolify \
  --env VBCDX_COOLIFY_URL=https://coolify.example.com \
  --env VBCDX_COOLIFY_WRITES=off \
  -- vbcdx-coolify mcp

For OpenCode, see examples/opencode.json. More detail is in examples/mcp-registration.md.

The package also ships a vbcdx.json declaration, so the vbcdx installer can register it for you:

npm install -g @vbcdx/vbcdx
vbcdx install tool @vbcdx/coolify-plugin --harness=claude

Configuration

Settings are read from the environment once, at startup. See .env.example.

Variable	Default	Description
`VBCDX_COOLIFY_URL`	none	Coolify instance URL, optionally ending in `/api/v1`. Required for any API call.
`VBCDX_COOLIFY_WRITES`	`off`	`off` (reads only), `write` (configuration and deploy writes), or `full` (also destructive tools).
`VBCDX_COOLIFY_TIMEOUT_MS`	`30000`	Total deadline per tool call, 1000 to 120000 ms.

Tools are always listed. A call made without valid configuration or credentials returns an error explaining what is missing.

Credentials (stdio mode)

Credentials are never passed on the command line or in the environment. Every tool except health takes a credential_file argument: the absolute path to a file like this:

VBCDX_AGENTS_ROLE=devops-agent
VBCDX_AGENTS_TOKEN=<coolify api token>

The file must be a regular file you own with mode 0600, in a directory with mode 0700:

install -d -m 0700 ~/.config/vbcdx/coolify
install -m 0600 /dev/null ~/.config/vbcdx/coolify/devops-agent.env

The token is sent as Authorization: Bearer <token>. What it can do is set by its Coolify permissions (read, read:sensitive, write, deploy, root); use the narrowest one that works. See examples/credential-file.env.example.

Network mode

vbcdx-coolify serve exposes the same tools over MCP Streamable HTTP:

VBCDX_COOLIFY_URL=https://coolify.example.com vbcdx-coolify serve
# MCP endpoint: POST http://127.0.0.1:8080/mcp
# Liveness:     GET  http://127.0.0.1:8080/healthz

In this mode there is no credential file. Each request carries its Coolify API token in the Authorization header (Bearer <token> or token <token>), which is used for that request only.

Variable	Default	Description
`VBCDX_COOLIFY_HTTP_PORT`	`8080`	Listen port.
`VBCDX_COOLIFY_HTTP_HOST`	`127.0.0.1`	Bind address.
`VBCDX_COOLIFY_TLS_CERT`	none	PEM certificate path. Set together with the key to serve HTTPS.
`VBCDX_COOLIFY_TLS_KEY`	none	PEM private key path.
`VBCDX_COOLIFY_HTTP_ALLOWED_ORIGINS`	none	Comma-separated browser origins allowed to call the server. Requests with any other `Origin` header get `403`.

Without TLS settings the server speaks plain HTTP; run it behind a TLS-terminating reverse proxy or on a trusted network. Outbound connections to Coolify always verify TLS. Request bodies over 1 MiB are refused with 413.

Docker

docker build -t vbcdx-coolify .
docker run --rm -p 8080:8080 \
  -e VBCDX_COOLIFY_URL=https://coolify.example.com \
  vbcdx-coolify

The image runs serve as a non-root user, listens on all interfaces and includes a health check. No credentials are stored in the image.

Tools

Run vbcdx-coolify manifest for every tool's input and output schema and required token permissions.

Effect	Tools
Read	`health`, `version`, `list_applications`, `get_application`, `get_application_logs`, `list_application_envs`, `list_databases`, `get_database`, `list_services`, `get_service`, `list_projects`, `get_project`, `list_servers`, `get_server`, `list_resources`, `list_deployments`, `get_deployment`
Write (`write` or `full`)	`create_application`, `deploy`, `start_application`, `create_application_env`, `update_application_env`
Destructive (`full` only)	`restart_application`, `stop_application`, `cancel_deployment`, `delete_application_env`, `delete_application`

Destructive tools also require an exact confirmation string naming the target. The confirmation guards against accidents; it is not an approval mechanism and is never sent to Coolify.

Results

Each call returns a text summary and a JSON envelope with outcome, effect, request (method, path, attempted) and verification; failures add a reason and a message. HTTP status is checked before the response body, and a mutation whose outcome cannot be confirmed is reported as unverified or indeterminate.

Development

npm ci
npm test
node bin/vbcdx-coolify.js --help

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Related MCP Connectors

AMH Cloudflare Ops MCP by WT
io.github.pain2hustle
The bridge from K2 agents through Wrangler to your master AI - safe, approval-gated Cloudflare ops.
Cloud Platforms Security Agent Orchestration
19
https://cfops.nothingunseen.com/mcp
ActionDock A
app.actiondock
Supervised API-write gateway for AI agents with policy, human approval and execution receipts.
Agent Orchestration Security App Automation
81
https://actiondock.app/mcp
TeleQuick Platform
dev.telequick
Tenant-scoped control plane over the TeleQuick platform's full API surface
Cloud Platforms Developer Tools
1
https://portal.telequick.dev/mcp
FullmaktOAuth
ai.fullmakt
Credential broker for AI agents: scoped, revocable API access with policy enforcement and audit.
Security Autonomous Agents Agent Orchestration
1
https://fullmakt.ai/mcp

Related MCP Servers

Coolify MCP Server
App Automation Cloud Platforms Developer Tools
StuMason
F
license
A
quality
F
maintenance
Enables interaction with Coolify applications and resources through the Coolify API via a standardized interface, supporting application management operations such as listing, starting, stopping, restarting, and deploying.
Updated 9 months ago (2026-01-17 07:16 UTC)
11
13
-
Coolify MCP Server
Cloud Platforms Developer Tools Virtualization
FelixAllistar
A
license
D
quality
F
maintenance
Provides programmatic and CLI tools for managing Coolify deployments, allowing users to control applications, services, databases, and infrastructure through natural language or command line.
Updated 9 months ago (2026-01-17 10:31 UTC)
10
55 npm
7
Good Luck With That Public
Coolify MCP Server
Cloud Platforms Developer Tools Virtualization
kof70
A
license
B
quality
B
maintenance
Enables control and management of Coolify self-hosted PaaS instances, allowing you to deploy applications, manage databases, monitor servers, and execute operations directly from AI assistants.
Updated a month ago (2026-09-17 18:56 UTC)
89
12 npm
28
MIT
coolify-mcp-server
Cloud Platforms Developer Tools CI/CD & DevOps
AbdulWadudh
A
license
Not graded
quality
C
maintenance
Enables LLMs to manage a self-hosted Coolify instance, including applications, databases, services, servers, projects, deployments, environment variables, tags, teams, private keys, and S3 backup storages via the Coolify REST API.
Updated 2 months ago (2026-08-31 09:45 UTC)
215 npm
MIT

@vbcdx/coolify-plugin

Requirements

Install

Usage

Register with an MCP client

Configuration

Credentials (stdio mode)

Network mode

Docker

Tools

Results

Development

License

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Coolify MCP Server

Coolify MCP Server

Coolify MCP Server

coolify-mcp-server