All docs

Coolify MCP server

Last updated: November 3, 2026

Coolify ships a built-in MCP server, a Model Context Protocol endpoint at /mcp on your instance. Once you enable it and create an API token, an AI coding agent like Claude, Cursor, or Codex can set up a project on your MapleDeploy server, add your app and its database, set the environment variables, and deploy it. It can also read logs, explain a failed deploy, roll back, find unhealthy resources, and check whether your scheduled backups and tasks ran.

The MCP server is off until you turn it on. This guide covers enabling it, creating a token, connecting a client, and turning it back off.

A typical first session

With a token that has read, deploy, and write, one request in your client covers what usually takes a dozen clicks:

Set up a staging project for this repo with a Postgres database, add the env vars from .env.example, and deploy it.

The client creates the project and a staging environment, creates the application from your Git repository and a Postgres database beside it, adds each environment variable your app expects, starts the deploy, and reads the build output. If the build fails, it can tell you why, fix the cause, and deploy again. Connection URLs are not returned to the client, so tell it how your app should reach the database, or set that variable yourself.

What a connected client can do

The tools a client can call depend on the abilities of the token you give it. Deploy and read are separate abilities, so a token with only deploy can act on your resources but cannot read them.

  • A deploy token can deploy and redeploy your applications, including pull request previews if you use them, cancel a deployment in progress, and start, stop, and restart your resources. It can also roll an application back to an earlier image. Listing the images to pick from needs read.
  • A read token can list your resources and their environment variable names, browse deployment history, find unhealthy resources, and see when scheduled backups and tasks ran. It does not return environment variable values.
  • Reading service logs, a deployment's build output, and backup or task messages needs a read:sensitive token. A read:sensitive token can also read environment variable values.
  • A write token can create and change projects, environments, applications, databases, services, environment variables, servers, private keys, backups, and storage. It can also order a paid server from a cloud provider whose token you saved in Coolify. From Coolify 4.6, it can also save and change integration tokens for Cloudflare, Doppler, Infisical, and Vault, and add or replace DNS records in the Cloudflare zones a saved token reaches.
  • Deleting needs the delete ability from Coolify 4.6. Tokens that had write when your instance moved to 4.6 got delete as well. Before 4.6, a write token can delete, and deleting an application, database, or service needs deploy as well.

A client only sees the tools and actions its token can use, except some read tools, which every token sees. Calling one of those without read fails with a missing permissions error.

The MCP server also ships two guided prompts, one to troubleshoot an application and one to explain a failed deploy. Clients that support MCP prompts offer them as ready-made commands.

If a client needs to both act and read, its token needs both abilities. A root token can do everything above.

Enable the MCP server

  1. Sign in to the MapleDeploy dashboard.
  2. Open the server and go to the Tools tab.
  3. Under MCP server, select Enable MCP server.
  4. Read the warning about what an enabled endpoint exposes, then confirm.

Only organization owners and admins can change this setting.

Create a Coolify API token

The MCP endpoint authenticates with a Coolify API token. The token's abilities decide what a connected client can do.

  1. Open your Coolify dashboard. The link is on your server details page.
  2. Go to Keys & Tokens and then API Tokens.
  3. Create a token and choose its abilities. Coolify offers Root, Write, Deploy, Read, and Read sensitive data (read:sensitive), and from 4.6 also Delete. A token with deploy but not read cannot list your resources or read logs, so add read if your client also needs config, and read:sensitive if it needs logs. Start with the least you need.
  4. Copy the token. Coolify shows it once.

The MCP endpoint does not need Coolify's REST API, so you can create a token and use it with the API off.

Connect your client

Your endpoint is your Coolify address with /mcp on the end. Once the MCP server is on, the Tools tab shows it with a copy button:

https://your-server.mapledeploy.ca/mcp

Every client needs two things: that URL, and your API token sent as a bearer token. Replace YOUR_TOKEN below with the token you copied.

Claude Code. Run:

claude mcp add --transport http coolify https://your-server.mapledeploy.ca/mcp --header "Authorization: Bearer YOUR_TOKEN"

Cursor. Add the server to ~/.cursor/mcp.json. Use this global file rather than a project's .cursor/mcp.json, so the token never ends up in a repository.

{
  "mcpServers": {
    "coolify": {
      "url": "https://your-server.mapledeploy.ca/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Codex. Codex reads the token from an environment variable, so set one where Codex runs, such as your shell profile, then add the server:

export COOLIFY_TOKEN=YOUR_TOKEN
codex mcp add coolify --url https://your-server.mapledeploy.ca/mcp --bearer-token-env-var COOLIFY_TOKEN

Once connected, ask the client to deploy an app, pull a service's logs, or explain why the last deploy failed. Whether it can depends on the token's abilities, described above.

Turn it off

Return to the server's Tools tab and select Disable MCP server. The endpoint stops responding immediately. Disabling does not delete your API tokens, so revoke any tokens you no longer need in Coolify under Keys & Tokens and then API Tokens.

What to keep in mind

  • Any Coolify API token on your instance can reach the endpoint once it is on, including read-only tokens. Keep token abilities as narrow as the task needs, and give a client write, delete, or root only when it needs to change your setup.
  • The Allowed IPs setting under Settings and then Advanced applies to the MCP endpoint as well as the REST API.
  • The realistic risk is prompt injection reaching a connected client. With a write or delete token, that reaches changing or deleting resources and ordering servers, so be deliberate about what you connect and what you paste into it. Destructive actions need an explicit confirmation in the call, but the client sets it itself, so it does not replace a narrow token.
  • Logs can contain secrets, and anything the client reads becomes part of its conversation with its AI provider.
  • You can turn the endpoint off at any time from the Tools tab.