# Coolify setup for PopMCP

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.

- Auth: API credentials
- Setup time: 2 min
- API base URL: https://app.coolify.io/api/v1
- Credentials screen: https://app.coolify.io/security/api-tokens
- Provider docs: https://coolify.io/docs/core/security/credentials/api-tokens

## 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

### 1. 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.

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

### 2. 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.

Screen: https://app.coolify.io/security/api-tokens

### 3. 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.

Screen: https://app.coolify.io/security/api-tokens

### 4. 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.

Screen: https://app.coolify.io/security/api-tokens

### 5. 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.

Screen: https://app.popmcp.com/marketplace

## Fields PopMCP asks for

- Coolify address (baseUrl): Leave 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 token (apiToken) [required]: Coolify shows it once, when you create it. Copy all of it, including the number and | at the start. Stored encrypted.

## Verify

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 ..."

Cause: 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 ..."

Cause: 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 ..."

Cause: 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 ..."

Cause: 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"

Cause: 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"

Cause: 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

Cause: 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.

---

Source: https://www.docs.popmcp.com/docs/integrations/coolify/