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 any of the 10 built-in tools to browse your infrastructure — listing servers, inspecting applications, checking database status, and more.
All data is 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.
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 10 tools. All tools are currently read-only.
Overview
| Tool | Description |
|---|---|
get_infrastructure_overview | High-level summary of your entire infrastructure — start here |
Servers
| Tool | Description |
|---|---|
list_servers | List all servers with name, IP, and reachability status |
get_server | Full details for a specific server by UUID |
Projects
| Tool | Description |
|---|---|
list_projects | List all projects with name and description |
Applications
| Tool | Description |
|---|---|
list_applications | List all applications (filterable by tag) |
get_application | Full details for a specific application by UUID |
Databases
| Tool | Description |
|---|---|
list_databases | List all databases with name, status, and type |
get_database | Full details for a specific database by UUID |
Services
| Tool | Description |
|---|---|
list_services | List all one-click services and stacks |
get_service | Full details for a specific service by UUID |
Recommended Workflow
Start with get_infrastructure_overview to get a bird's-eye view of your setup.
Then use list_* tools to browse specific resource types, and get_* tools when you need full details on a particular resource.
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.
Security Considerations
Your infrastructure metadata (server IPs, application names, domains, environment variable names) is visible to the AI client.
Revoking the API token used for MCP immediately cuts off MCP access.