@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

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