MCP Server
Coolify includes a built-in MCP (Model Context Protocol) server that lets AI assistants query your Coolify Instance without exposing sensitive credentials.
Currently Read-Only
The MCP server is currently read-only, with write operations planned for a future release.
Who this is for?
This setup is ideal for people who:
- Use AI coding assistants like Claude Code, Cursor, Codex and want them to understand your infrastructure.
- Want to ask natural language questions about your deployed apps, databases, and servers.
- Need a read-only view of your Coolify resources from AI tools without risking accidental changes.
- Manage multiple projects and want AI help navigating your infrastructure.
Before We Start
API Access Required
MCP relies on API tokens for authentication.
Make sure API access is enabled on your instance before enabling the MCP server.
You can enable it by following the API Setup guide.
How It Works?
Your AI assistant connects to Coolify's MCP endpoint over HTTP using a standard API token. Once connected, the assistant can call the built-in read-only tools to browse your infrastructure — servers, projects, applications, databases, services, deployments, logs, and more.
All data is always scoped to the team associated with your API token. If you have multiple teams, the assistant only sees resources belonging to the token's team. Cross-team UUIDs are rejected.
Example Data
The following data is used as an example in this guide. Please replace it with your actual data when following the steps.
- Coolify Domain: coolify.shadowarcanist.com
- MCP Endpoint: https://coolify.shadowarcanist.com/mcp
- API Token:
67|abcthisisa123dummytoken
1. Enable the MCP Server
You can enable or disable the MCP server from the dashboard:
- Log in to your Coolify dashboard
- Go to Settings in the sidebar.
- Click on Advanced.
- Find the MCP Server section and toggle Enable MCP Server on.
You can enable or disable the MCP server programmatically using the API:
# Enable MCP
curl -X POST https://coolify.shadowarcanist.com/api/v1/mcp/enable \
-H "Authorization: Bearer 67|abcthisisa123dummytoken"
# Disable MCP
curl -X POST https://coolify.shadowarcanist.com/api/v1/mcp/disable \
-H "Authorization: Bearer 67|abcthisisa123dummytoken"These endpoints require a API token with root permissions.
Once enabled, your MCP endpoint becomes available at:
https://coolify.shadowarcanist.com/mcp2. Create an API Token
The MCP server uses your existing Coolify API tokens for authentication. Follow the API Authorization guide to create a token.
Your token must have the read permission.
Token Permissions
Your MCP token only needs read permissions for now.
Since the server currently only supports read operations, extra permissions provide no benefit and increase risk if the token is leaked.
3. Configure Your AI Client
Use your MCP endpoint and API token to connect your AI assistant.
Coolify's MCP server uses Streamable HTTP transport.
When configuring any client, you'll need:
- URL:
https://coolify.shadowarcanist.com/mcp - Authentication Header:
Authorization: Bearer 67|abcthisisa123dummytoken
Follow the setup guide for your client:
Any other MCP-compatible client that supports Streamable HTTP transport can also connect using the URL and authentication header above.
Available Tools
Once connected, your AI assistant can use the following tools (MCP server version 0.2.0). Every tool enforces team ownership via the API token. Most tools need read; lifecycle tools need deploy.
Overview & team
| Tool | Description |
|---|---|
coolify_help | Tool catalog by intent (overview, debug, deploy, essentials, …) — start here if unsure |
get_infrastructure_overview | High-level summary (counts + SQL health_hints) |
search_resources | Fuzzy search by name / UUID / domain / IP across resource types |
list_unhealthy_resources | Unhealthy resources (sample_only=true for cheap sample + counts) |
get_current_team | Team for the authenticated token |
list_team_members | Members of the token's team |
Servers & destinations
| Tool | Description |
|---|---|
list_servers | List servers (optional reachable filter) |
get_server | Full details for a server by UUID |
get_server_domains | Domains hosted on a server |
get_server_resources | Resources defined on a server |
list_destinations | Docker destinations (optional server_uuid filter) |
get_destination | Destination details by UUID |
Projects & inventory
| Tool | Description |
|---|---|
list_projects | List projects |
get_project | Project with environments and resource counts |
get_environment | Environment by name/UUID within a project |
list_resources | Flat inventory (filter: type, project_uuid, tag) |
list_tags | Team tags |
Applications
| Tool | Description |
|---|---|
list_applications | List applications (filters: tag, project_uuid, environment_uuid, server_uuid, status, name) |
get_application | Full details by UUID |
list_application_previews | PR preview deployments for an application |
Databases
| Tool | Description |
|---|---|
list_databases | List databases (filters: project_uuid, environment_uuid, server_uuid, status, name) |
get_database | Full details by UUID |
list_database_backups | Backup schedules for a database |
list_backup_executions | Executions for a backup schedule |
Services
| Tool | Description |
|---|---|
list_services | List services (filters: project_uuid, environment_uuid, server_uuid, status, name) |
get_service | Full details by UUID |
list_service_applications | Service application components |
get_service_application | One service application |
list_service_databases | Service database components |
get_service_database | One service database |
Deployments & observability
| Tool | Description |
|---|---|
list_deployments | Active/queued deployments, or history with application_uuid |
get_deployment | Deployment details; optional include_log_summary for capped redacted tail |
get_logs | Live container logs; on failure returns reason + next_tools (not_running / server_unreachable) |
list_env_keys | Env key names only (never values) |
list_shared_env_keys | Shared project/environment env key names only |
Lifecycle (token ability: deploy)
| Tool | Description |
|---|---|
control | start / stop / restart for application, database, or service (stop requires confirm=true) |
deploy | Queue application deployment (force, optional pull_request_id) |
cancel_deployment | Cancel queued/in-progress deployment by UUID |
list_storages | Volume/file mount metadata (no file contents) |
list_resource_tags | Tags on a resource |
list_scheduled_tasks | Scheduled tasks on app/service |
list_scheduled_task_executions | Task execution history |
GitHub
| Tool | Description |
|---|---|
list_github_apps | GitHub apps for the team (secrets scrubbed) |
list_github_repositories | Repos for a GitHub app |
list_github_branches | Branches for a repo via a GitHub app |
Recommended Workflow
get_infrastructure_overview,search_resources, orlist_unhealthy_resourceslist_projects/get_project/get_environmentlist_*inventories (with filters), thenget_*for detailslist_deployments+get_deployment(include_log_summary)+get_logsfor failureslist_env_keys/list_shared_env_keys/list_storagesfor config (never secret values)
Prompts: troubleshoot_application, explain_failed_deploy
Resources: coolify://overview, coolify://application/{uuid}
Pagination
All list_* tools support pagination:
- page — Page number (default: 1)
- per_page — Items per page (default: 50, max: 100)
The response includes a _pagination field with a next value indicating the next page, if available.
Responses use { data, _actions?, _pagination? }. _actions suggests related read tools.
Security Considerations
Your infrastructure metadata (server IPs, application names, domains, environment variable names) is visible to the AI client.
Never returned over MCP: passwords, env values, private keys, cloud tokens, webhook secrets, file storage contents, full deploy build logs.
Revoking the API token used for MCP immediately cuts off MCP access.