Coolify Cloud

July 31, 2026 · View on GitHub

Use awesome-coolify-mcp with Coolify Cloud. The server exposes 19 tools and six prompts, with team-scoped tokens, per-request routing, and structured Cloud errors.

Branding: Icons via serverInfo.icons — embedded data URI (primary) + jsDelivr CDN entries (mcp-icon-192.png, favicon-32.png). See docs/assets/README.md and maintainer verify record.

Back to the main install walkthrough: README — Install.

Overview

Coolify Cloud (https://app.coolify.io) is Coolify's hosted SaaS. This MCP server treats Cloud instances the same as self-hosted for day-2 operations (deploy, logs, diagnose, resource CRUD, etc.), but some infrastructure endpoints differ or are unavailable on Cloud.

Use instance action cloud-info for local/static discovery — it reports isCloud, resolved URL, credential source, setup hints, known limits, and a docs link. It does not call the Coolify API.

instance({ action: "cloud-info" })

`cloud-info` response fields

Field	Meaning
`isCloud`	`true` when the resolved hostname is `*.coolify.io` or registry `type: "cloud"`
`url`	Resolved Coolify base URL (no trailing slash)
`source`	Where credentials came from: `registry` · `env` · `infer`
`knownLimits`	Static list of Cloud API gaps (mirrors Known limits below)
`docs`	Link back to this page

Setup

Generate a team-scoped API token in app.coolify.io under Keys & Tokens. Never commit real tokens — use placeholders or environment variables.

Multi-instance registry

For fleets that mix self-hosted and Cloud, register each instance in ~/.coolify-mcp/instances.json:

instance({
  action: "add",
  name: "cloud",
  url: "https://app.coolify.io",
  token: "<team-scoped-token>",
  type: "cloud",
})
instance({ action: "list" })
instance({ action: "set-default", name: "cloud" })

Registry directory: 0o700; instances.json: 0o600
Per-request credential resolution — no cross-instance token leakage
Pass instance: "<name>" on ops tools to target a specific registry entry

Path 1 — `instance.add` (registry)

instance({
  action: "add",
  name: "cloud",
  url: "https://app.coolify.io",
  token: "<team-scoped-token>",
  type: "cloud",
})

Path 2 — `import-env` (process environment)

Set env vars in your MCP client config (see README — Install), then import:

{
  "COOLIFY_URL": "https://app.coolify.io",
  "COOLIFY_TOKEN": "<team-scoped-token>"
}

instance({ action: "import-env" })

import-env copies COOLIFY_URL + COOLIFY_TOKEN from the process environment into the local registry — opt-in only.

Optional — token sanity check (curl)

Verify the token before wiring MCP:

curl -H "Authorization: Bearer $COOLIFY_TOKEN" \
  https://app.coolify.io/api/v1/version

Expect a JSON version payload on success; 401 means regenerate the token.

Branding

The MCP server advertises icons in initialize via an embedded PNG data URI (primary) and jsDelivr CDN URLs for mcp-icon-192.png and favicon-32.png. Cursor may still show a letter fallback — see maintainer verify record. This is a Cursor/MCP-list display path only; it does not call the Coolify API.

Local manifest

The workspace cache at .coolify/manifest.json speeds up discovery and UUID hints:

manifest({ action: "sync" })   // reconcile against live API
manifest({ action: "diff" })   // non-destructive diff report

Best-effort auto-hooks update the cache after app/service/DB mutations
Stale entries surface _meta.manifestWarning on related ops — run sync or diff to reconcile
The manifest is a cache, not source of truth — remote API wins on conflict; 404 hints only (D-15)

Smoke test

After connect, run this agent-first path to confirm Cloud works:

Discovery (local, no API call):
```
instance({ action: "cloud-info" })
```
Expect isCloud: true, url: "https://app.coolify.io", and source of registry, env, or infer.

Connectivity:

system({ action: "health" })
meta({ action: "version" })

Light resource read (pick one known UUID from your Cloud dashboard):

resource({ action: "list", per_page: 5 })
// or
application({ action: "get", uuid: "<app-uuid>" })

Optional — agent intelligence (v3.3):

system({ action: "version" })
// Check capabilities.intelligence_scorecard, deployment_preflight, diagnose_analyze
intelligence({ action: "scorecard" })

Agent intelligence (v3.3)

On Coolify 4.1.x, composite intelligence actions work on Cloud the same as self-hosted (read-only unless confirm: true):

Workflow	Entry action
Instance health	`intelligence({ action: "scorecard" })`
Dependency map	`intelligence({ action: "graph" })`
Manifest drift	`manifest({ action: "audit" })`
Deploy risk	`deployment({ action: "preflight", uuid: "<app-uuid>" })`
Log patterns	`diagnose({ action: "analyze", uuid: "<app-uuid>" })`

Always read system.version.capabilities before assuming support. Rollback, env promote, and janitor cleanup require explicit human confirmation.

Known limits

Coolify 4.1.x log support is resource-specific:

Log source	Support
Application runtime logs and follow	Supported through `application.logs`
Deployment/build logs	Supported through `application.logs` with `deployment_uuid`
`diagnose.logs`	Supported for applications only
Service/database logs	Unavailable because Coolify 4.1.x provides no REST endpoints

Check system.version.capabilities before choosing a workflow. Do not infer support from the presence of a resource tool.

Limit	Detail
Server CRUD via API	Cloud does not support server create, validate, or delete through the REST API — use the Cloud dashboard for server management.
Self-hosted-only endpoints	Some endpoints available on self-hosted return 404 on Cloud → structured code `COOLIFY_CLOUD_UNSUPPORTED`.
Team-scoped tokens	Tokens are scoped to a team — verify the token's team owns the target resource.
Same tool surface	All 19 MCP tools remain available; failures surface as structured errors, not silent stubs.

cloud-info knownLimits mirrors this list locally — no live capability probe.

Error codes

Cloud-specific structured codes apply when the instance hostname is *.coolify.io (or registry type: cloud):

`COOLIFY_CLOUD_FORBIDDEN` (HTTP 403)

Token or team permission issue on Cloud.

Recovery hints:

Regenerate the team-scoped token in app.coolify.io under Keys & Tokens and ensure it has the required abilities.
Cloud tokens are team-scoped — verify the token belongs to the team that owns the target resource.

`COOLIFY_CLOUD_UNSUPPORTED` (HTTP 404)

Endpoint not available on Coolify Cloud.

Recovery hints:

Endpoint not supported or not available on Coolify Cloud — use the self-hosted alternative or the Cloud dashboard.
See this doc for known Cloud-unsupported endpoints.

Generic codes (COOLIFY_401, COOLIFY_404, etc.) still apply as fallbacks on non-cloud hostnames.