Integrations

Coolify

Connect Coolify to Claude, ChatGPT and other MCP clients with PopMCP. Step-by-step API credential setup, plus fixes for common errors.

API credentialsDeveloper & InfrastructureCoolify API docsCoolify MCP server overview

You paste one value into PopMCP: an API token you create in Coolify under Keys & Tokens, API Tokens. If you host Coolify yourself, you also paste the address you open it at.

Setup time
2 min
Auth
API credentials
API base URL
https://app.coolify.io/api/v1
Rate limits
200 requests a minute per user by default; self-hosted admins can change it with API_RATE_LIMIT. 30 refused requests in a minute block the token for a while.

Before you begin

  • Coolify Cloud, or self-hosted Coolify 4 on any plan, including the free open-source edition
  • Self-hosted only: a Coolify address the internet can reach over HTTPS, like https://coolify.yourdomain.com. Coolify opened at an IP and port such as http://203.0.113.10:8000 has no HTTPS until you give it a domain under Settings, General, URL
  • Self-hosted only: an instance admin to switch on API access under Settings, Advanced
  • A Coolify account in the team whose projects you want the AI to reach. A token works for one team

Get your credentials

Self-hosted only: switch on API access

On Coolify Cloud the API is already on, so skip to the next step. On your own Coolify, sign in as an instance admin, open Settings and then Advanced. Under API and MCP, set API access to Enabled. Leave Allowed API IPs empty: when it lists addresses, Coolify refuses every call from anywhere else, PopMCP included. Click Save changes.

Open https://YOUR-DOMAIN/settings/advanced (replace YOUR-DOMAIN with your Coolify domain).

coolify.yourdomain.com/settings/advanced
SearchAcme
Settings / Advanced

Advanced

Advanced settings for your Coolify instance.

API and MCP
API access
Enabled
MCP server
Disabled
Allowed API IPs
Empty allows every address
Save changes

Open API Tokens

Make sure the team you want is selected at the bottom of the sidebar: a token can only reach the team that was active when you made it. Open Keys & Tokens in the sidebar, then the API Tokens tab, and click New token.

Open this screen →

app.coolify.io/security/api-tokens
SearchAcme
Keys & Tokens / API Tokens

API Tokens

Tokens are created with the current team as scope.

Private KeysCloud TokensCloud-Init ScriptsAPI Tokens
New token

No API tokens yet.

Tokens let integrations and AI clients use the Coolify API.

Create the token

Under Description type PopMCP. Under Expires in pick how long it should last; Never saves you from reconnecting, a date is safer. Under Permissions tick read, read:sensitive, write, delete and deploy to let the AI do everything, or only read and read:sensitive for a connection that can look but not change anything. read:sensitive lets it read logs and environment variable values. Leave Access on All resources in the team, then click Create token.

Open this screen →

app.coolify.io/security/api-tokens
SearchAcme
Keys & Tokens / API Tokens

API Tokens

Tokens are created with the current team as scope.

Private KeysCloud TokensCloud-Init ScriptsAPI Tokens
New API token
Description
PopMCP
Expires in
1 year
Access
All resources in the team
rootNot needed
read
read:sensitiveLogs and variable values
write
delete
deployDeploy, start, stop, restart
CancelCreate token

Copy the token

Coolify shows the new token in the Copy your token window and will not show it again. Copy all of it: it starts with a number and a |, like 12|AbCd..., and PopMCP needs both halves. Then click Done. If you lose it, choose Roll on the token to get a new value.

Open this screen →

app.coolify.io/security/api-tokens
SearchAcme
Keys & Tokens / API Tokens

API Tokens

Tokens are created with the current team as scope.

Private KeysCloud TokensCloud-Init ScriptsAPI Tokens
Copy your token
Token
12|AbCdEfGh****56789abcd
Done

This is the only time the complete token is shown. Copy it now.

Paste the token into PopMCP and connect

In PopMCP open Coolify. If you host Coolify yourself, paste the address you open it at under Coolify address, like https://coolify.yourdomain.com; leave it empty for Coolify Cloud. Paste the token under API token and click Connect Coolify. PopMCP checks that Coolify accepts the token and names the connection after your team.

Open this screen →

Connect in PopMCP

Open your workspace, choose Coolify in the marketplace, and fill in the connect dialog:

FieldWhat to enter
Coolify addresstextLeave empty for Coolify Cloud. Self-hosted: the address you open Coolify at, like https://coolify.yourdomain.com. It needs HTTPS and the API switched on at Settings > Advanced.
API tokensecretCoolify shows it once, when you create it. Copy all of it, including the number and | at the start. Stored encrypted.Encrypted with AES-256-GCM on save and never shown again.

PopMCP verifies the credential against Coolify immediately. On success the connection flips to Verified and its MCP tools are provisioned.

Verify it worked

PopMCP calls your Coolify with the token, reads its version and the team the token belongs to, and marks the connection Verified under your team's name. Asking the AI for an overview of your Coolify returns its version, your projects and servers, and which applications, services and databases are running, stopped or unhealthy.

Troubleshooting

"Coolify at ... did not accept this token ..."

Why: Only part of the token was copied, or it expired, was paused, rolled or revoked. Changing your Coolify password also revokes your tokens. On a self-hosted Coolify with no address entered, PopMCP tried Coolify Cloud.

Fix: Create a new token and copy all of it, including the number and `|` at the start. If you host Coolify yourself, enter your Coolify address too.

"The API is switched off on this Coolify ..."

Why: API access is off on your self-hosted instance, which is the default.

Fix: As an instance admin open Settings, Advanced, and set API access to Enabled.

"This Coolify only accepts API calls from the addresses in ... Allowed API IPs ..."

Why: Allowed API IPs under Settings, Advanced lists addresses, and PopMCP's is not one of them.

Fix: Empty the field, or set it to 0.0.0.0, and save.

"We could not reach ... over HTTPS" or "... is a private address ..."

Why: Your Coolify is opened at an IP and port without HTTPS, or only on a private network or VPN.

Fix: Give Coolify a domain under Settings, General, URL, point its DNS at the server, and use that https:// address. A Coolify only on a private network cannot be connected.

A tool answers 403 with "Missing required permissions"

Why: The token does not have that permission, for example deploy for a restart or read:sensitive for logs.

Fix: In Coolify open Keys & Tokens, API Tokens, choose Edit on the token, tick the permission and save. The token keeps working with the new access, so there is nothing to reconnect.

Calls answer 429 "Too many failed API requests"

Why: Coolify blocks a token for 1, then 5, then 15 minutes after 30 refused calls in a minute.

Fix: Wait for the block to end and give the token the permissions the AI needs, so the calls stop being refused.

A tool answers 404

Why: A wrong uuid, a resource in another team, or a tool newer than your Coolify version.

Fix: Ask the AI to find the resource by name. Updating Coolify adds the newer tools.

Reference

On this page