Coolify MCP Server — AI DevOps Automation

Most Powerful Coolify MCP Server. Connect Claude, Cursor, Antigravity, Windsurf, Trae, Roo or any custom AI Agents directly to your self-hosted Coolify instance via this Model Context Protocol (MCP) server.

Manage and inspect deployments, monitor server health, analyze application logs, and even restart Docker containers entirely via natural language. This Apify Actor completely solves the MCP hosting headache by replacing complex 24/7 server infrastructure with simple, serverless MCP API calls!

---

🚀 Why Use This Actor?

The Model Context Protocol (MCP) is revolutionizing how AI interacts with infrastructure. But running a Node.js MCP server 24/7 on your local machine or a dedicated VPS just to talk to your AI is a massive headache.

This Apify Actor completely solves the hosting problem. By running heavily-optimized, serverless Node.js infrastructure, it turns a 30-minute infrastructure setup into a simple 30-second API URL generation. You simply paste your Coolify API Token, grab your Apify Integration URL then our coolify tools will be available to your AI.

About this MCP Server: To understand how to connect to and utilize this MCP server, please refer to the official Model Context Protocol documentation at mcp.apify.com

---

What is this Actor?

Runs as a long‑lived Standby Actor with a stable URL so tools can call it on demand. Serves an MCP server over HTTP, exposing tools directly to AI agents.

Standby Mode

This Actor uses Standby mode, a lightweight method for using Actors. Instead of starting an Actor for each input and waiting for results, the Actor remains ready in the background to handle arbitrary Server-Sent Events (SSE) or HTTP requests, just like any web API server.

---

Connection URL

The Actor is reachable at this endpoint URL:

https://aimcp--coolify-mcp-server.apify.actor/mcp

Note: Authenticate requests with your Apify API token via the Authorization: Bearer header. Get your token from the Apify Console.

---

Configuration

To use this MCP server, you'll need below three things:

1. Coolify API URL — Your Coolify instance URL with /api/v1 suffix (e.g. https://coolify.yourdomain.com/api/v1)
2. Coolify API Token — Generate one from your Coolify instance dashboard
3. Apify API Token — Generate one from your Apify Console

How to Get Your Coolify API Token

1. Log in to your Coolify dashboard
2. Navigate to Keys & Tokens on the sidebar
3. Ensure you have the right team selected on left side bar
4. Click Create New Token, name it something like mcp-agent, and copy the token.

How to Get Your Apify API Token

1. Log in to your Apify Console
2. Navigate to Settings → Integrations on the sidebar
3. Click Create New Token, name it something like mcp-agent, and copy the token.

---

MCP Client Configuration

To connect to this MCP server, simply paste the following one-time configuration in your MCP client. All credentials are passed securely via HTTP headers — no environment variables, no manual UI setup, just paste and go.

🔐 Security by Design

Your Coolify credentials are transmitted via custom HTTP headers (X-Coolify-*), which are:

• Never logged by web servers, proxies, or CDNs
• Never leaked via browser history, referrer headers, or URL sharing
• Validated on every request with input sanitization and SSRF protection

Option 1: Direct Connection (Recommended)

Connect directly to the Actor's Standby endpoint — lowest latency, simplest setup:

{
    "mcpServers": {
        "coolify-mcp-server": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "https://aimcp--coolify-mcp-server.apify.actor/mcp",
                "--header",
                "Authorization: Bearer YOUR_APIFY_API_TOKEN",
                "--header",
                "X-Coolify-Api-Url: https://coolify.yourdomain.com/api/v1",
                "--header",
                "X-Coolify-Api-Token: YOUR_COOLIFY_API_TOKEN",
                "--header",
                "X-Coolify-Safety-Mode: read-only",
                "--header",
                "X-Coolify-Toolsets: system,servers,applications,databases,services,deployments,projects,teams"
            ]
        }
    }
}

Option 2: Via Apify MCP Gateway

Connect through the Apify MCP gateway at mcp.apify.com — gives you access to helper tools like search-actors and fetch-actor-details alongside the Coolify tools:

{
    "mcpServers": {
        "coolify-mcp-server": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "https://mcp.apify.com/?tools=actors,docs,aimcp/coolify-mcp-server",
                "--header",
                "Authorization: Bearer YOUR_APIFY_API_TOKEN",
                "--header",
                "X-Coolify-Api-Url: https://coolify.yourdomain.com/api/v1",
                "--header",
                "X-Coolify-Api-Token: YOUR_COOLIFY_API_TOKEN",
                "--header",
                "X-Coolify-Safety-Mode: read-only",
                "--header",
                "X-Coolify-Toolsets: system,servers,applications,databases,services,deployments,projects,teams"
            ]
        }
    }
}

Header Reference

Header	Required	Default	Description
Authorization	✅ Yes	—	Your Apify API token (Bearer YOUR_TOKEN)
X-Coolify-Api-Url	✅ Yes	—	Your Coolify instance URL with /api/v1 suffix
X-Coolify-Api-Token	✅ Yes	—	Your Coolify API token
X-Coolify-Safety-Mode	No	read-only	read-only, safe, or full
X-Coolify-Toolsets	No	all	Comma-separated: system,servers,applications,databases,services,deployments,projects,teams

💡 Tip: Start with X-Coolify-Safety-Mode: read-only and upgrade to safe or full only when you need write/delete operations. Invalid safety modes automatically fall back to read-only for security.

✨ Key Features

Engineered this MCP Server from the ground up to be the absolute best, most secure, and most cost-effective bridge between AI and Coolify.

• 🧠 Smart Tool Discovery search_tools: Connects with 45 robust tools, but uses progressive disclosure. The AI can call search_tools("debug deploy") to instantly get suggested step-by-step workflows (like "find → read logs → retry"), avoiding blind trial-and-error. Guides the AI with 10 built-in, docs-backed workflow patterns.

• 📉 Massive Token Savings: Built-in Response Summarization automatically slims down bloated list endpoints (like get_services or get_resources). This slashes token usage by up to 90% per request, saving massive context window space (reducing costs and preventing the AI from "forgetting" early chat context).

• 🛡️ Three-Tier Safety Model: Control what the AI can do. read-only (monitoring only), safe (allows deploys, restarts, starts, stops — blocks deletes), or full (all operations). Defaults to read-only.

• 🔐 Zero-Leak Security (Auto-Redaction): Deep JSON payload sanitization scrubs passwords, private keys, database connection strings, and tokens before any data reaches the AI. All replaced with [REDACTED BY MCP SERVER].

• 🧩 Toolset Categorization: Enable only the tool groups you need (servers, applications, services, databases, deployments, projects, teams, system) to reduce AI context noise and improve tool selection accuracy.

• 📜 Context-Safe Log Tailing: A tailLines parameter slices application logs in-memory before transmitting, keeping payloads hyper-lean and within AI context limits.

• 📊 Structured MCP Logging: Every tool call emits structured log messages with call timing via the MCP logging protocol (e.g. ✓ get_servers completed in 142ms), visible in MCP Inspector and compatible clients.

• 🤖 6 Native AI Prompts: Pre-built diagnostic workflows that guide the AI step-by-step: health checks, deployment troubleshooting, service status reports, database backup audits, security reviews, and resource usage summaries.

---

🔍 The Built-in Knowledge Base (search_tools)

Instead of handing the AI 45 complex tools and hoping it guesses the right order, this MCP server includes a meta-tool called search_tools.

When an AI encounters a complex problem (e.g., "my app crashed" or "check my infrastructure security"), it calls this tool to retrieve 10 proven, docs-backed workflows.

Examples of guidance the AI receives:

• Debug Failed Deployment: get_application_deployments → get_deployment (build logs) → get_application_logs (runtime crash)
• Batch Deploy by Tag: get_resources → deploy({ tag }) → get_deployments
• DNS & Domain Troubleshooting: get_server_domains → get_application (check FQDN) → Check underlying A Records

This makes AI agents significantly smarter, faster, and cheaper when interacting with your architecture.

---

Available Tools (45 Total)

🟢 Read-Only Tools (Always Available)

Servers

Tool	Description	Parameters
get_servers	List all connected servers	—
get_server	Get detailed server info	uuid (string, required)
validate_server	Verify server connection	uuid (string, required)
get_resources_by_server	List all resources on a server	serverUuid (string, required)
get_server_domains	List domains/FQDNs on a server	uuid (string, required)

Applications

Tool	Description	Parameters
get_applications	List all applications	—
get_application	Get application details	uuid (string, required)
get_application_logs	Get container stdout/stderr logs	uuid (string, required), tailLines (number, optional)
get_application_deployments	List deployment history	uuid (string, required)
list_application_envs	List env var keys (values redacted)	uuid (string, required)

Services

Tool	Description	Parameters
get_services	List all services (Compose stacks)	—
get_service	Get service details & containers	uuid (string, required)
list_service_envs	List env var keys (values redacted)	uuid (string, required)

Databases

Tool	Description	Parameters
get_databases	List all databases	—
get_database	Get database configuration	uuid (string, required)
get_database_backups	List backup configurations	uuid (string, required)

Deployments

Tool	Description	Parameters
get_deployments	List all recent deployments	—
get_deployment	Get deployment details & build logs	uuid (string, required)

Projects

Tool	Description	Parameters
get_projects	List all projects	—
get_project	Get project details	uuid (string, required)
get_project_environment	Get environment within a project	projectUuid (string, required), environmentNameOrUuid (string, required)

Teams

Tool	Description	Parameters
get_teams	List all accessible teams	—
get_team	Get team details	id (string, required)
get_team_members	List team members & roles	id (string, required)
get_current_team	Get current API token's team	—

System

Tool	Description	Parameters
get_version	Get Coolify instance version	—
get_resources	List ALL resources instance-wide	—
search_tools	[META] Find tools and suggested workflows	query (string), toolset (string)

🟡 Write Tools (Requires safe or full mode — 11 tools)

Tool	Description	Parameters
deploy_application	Trigger a new deployment build	uuid (string, required), force (boolean, optional)
stop_application	Stop a running application	uuid (string, required)
restart_application	Restart an application	uuid (string, required)
start_service	Start a stopped service stack	uuid (string, required)
stop_service	Stop a running service	uuid (string, required)
restart_service	Restart a service	uuid (string, required)
start_database	Start a stopped database	uuid (string, required)
stop_database	Stop a running database	uuid (string, required)
restart_database	Restart a database	uuid (string, required)
deploy	Universal deploy by UUID or tag	uuid (string, optional), tag (string, optional), force (boolean, optional)
cancel_deployment	Cancel an in-progress build	uuid (string, required)

🔴 Destructive Tools (Requires full mode only — 6 tools)

Tool	Description	Parameters
delete_application	⚠️ Permanently delete an application	uuid (string, required)
delete_service	⚠️ Permanently delete a service	uuid (string, required)
delete_database	⚠️ Permanently delete a database	uuid (string, required)
delete_server	⚠️ Remove a server registration	uuid (string, required)
delete_project	⚠️ Delete a project & environments	uuid (string, required)
delete_environment	⚠️ Delete an environment	projectUuid (string, required), environmentNameOrUuid (string, required)

---

Available Prompts (6 Total)

Prompt	Arguments	Description
coolify-health-check	—	Full infrastructure health assessment across servers, apps, services, and databases
deployment-troubleshooter	uuid (required)	Diagnose failed deployments with log analysis and actionable remediation
service-status-report	uuid (optional)	Deep-dive one service or survey all services for unhealthy containers
database-backup-audit	—	Audit all databases for backup configurations and flag gaps
security-audit	—	Security posture check: public databases, missing FQDNs, safety mode review
resource-usage-summary	serverUuid (optional)	Resource distribution overview per server or across all servers

---

The server resolves credentials in this priority order: HTTP Headers (per-connection) → Actor Input → Environment Variables.

Parameter	Header	Env Variable	Description
Coolify API URL	X-Coolify-Api-Url	COOLIFY_API_URL	Your Coolify API URL (required)
Coolify API Token	X-Coolify-Api-Token	COOLIFY_API_TOKEN	Your Coolify API token (required)
Safety Mode	X-Coolify-Safety-Mode	COOLIFY_SAFETY_MODE	read-only (default), safe, or full
Toolsets	X-Coolify-Toolsets	COOLIFY_TOOLSETS	Comma-separated toolsets to enable (default: all)

🛡️ Security Note: Invalid safety modes silently default to read-only. Invalid toolset names are stripped. API URLs are validated against SSRF. Tokens are checked for whitespace injection.

---

💸 Pricing (Pay-Per-Event)

This Actor functions entirely on a Pay-per-Event SaaS model — no flat monthly subscription.

• Usage Fee: $0.005 per actor event.
• What is an "Event"? An event occurs when your AI actively connects to the Actor to check servers, read logs, or trigger a deployment.
• Compute Costs: Completely serverless — you pay Apify's fractional compute rates when the server is awake.

Billing Protection: Set a maximum monthly usage limit in your Apify billing settings (e.g., "$5/month"). Once hit, the Actor simply pauses. Zero risk of runaway bills.

---

References

• Model Context Protocol Documentation
• Apify MCP Integration Guide
• Coolify Documentation
• Coolify API Reference
• Apify SDK for JavaScript
• Apify Platform Documentation