All docs

Coolify MCP server

Last updated: September 24, 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 client like Claude Code, Cursor, or Codex can deploy your apps, start and stop resources, and read logs on your MapleDeploy server.

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.

What a connected client can do

The tools a client can call depend on the abilities of the token you give it, and Coolify's deploy ability is exclusive: a deploy token can act on your resources but cannot read them.

  • A deploy token can deploy and redeploy your applications and start, stop, and restart your resources.
  • A read token can list your resources and their environment variable names. It never returns the values.
  • Reading service logs needs a read:sensitive token.

Give the client the least powerful token for its job. If it needs to both act and read, create a separate token for each.

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. If you do not see the control, your server may need a Coolify update before it appears; it shows up on the Tools tab once the update is applied.

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 Security and then API Tokens.
  3. Create a token and choose its abilities. Coolify offers read, read:sensitive, write, write:sensitive, deploy, and root. Deploy is exclusive, so a deploy token cannot also read; create a separate read token if your client also needs logs or config. Start with the least you need.
  4. Copy the token. Coolify shows it once.

If token creation is hidden, Coolify's REST API is off on your instance. Turn it on under Settings and then Advanced in Coolify, then create the token. Turning the REST API on opens Coolify's REST surface too, so leave it off again if you do not need it.

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 or pull a service's logs. 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 Security and then API Tokens.

What to keep in mind

An enabled MCP server is a real capability, so treat it like one.

  • 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.
  • The realistic risk is prompt injection reaching a connected client. Be deliberate about what you connect and what you paste into it.
  • The endpoint returns environment variable names, never their values.
  • You can turn the endpoint off at any time from the Tools tab.