Coolify MCP Server

Instructions

Implementation Reference

• src/tools/handlers.ts:73-77 (handler)

  Handler implementation for 'create_server' tool: checks required parameters and sends POST request to Coolify API /servers endpoint.

  case 'create_server':
    requireParam(args, 'name');
    requireParam(args, 'ip');
    requireParam(args, 'private_key_uuid');
    return client.post('/servers', args);

• src/tools/definitions.ts:157-173 (schema)

  Schema definition and registration in the allToolDefinitions array, including input schema with properties and required fields for create_server.

  {
    name: 'create_server',
    description: 'Create a new server',
    inputSchema: {
      type: 'object',
      properties: {
        name: { type: 'string', description: 'Server name' },
        description: { type: 'string', description: 'Server description' },
        ip: { type: 'string', description: 'Server IP address' },
        port: { type: 'number', description: 'SSH port (default: 22)', default: 22 },
        user: { type: 'string', description: 'SSH user (default: root)', default: 'root' },
        private_key_uuid: { type: 'string', description: 'UUID of the private key for SSH' },
        is_build_server: { type: 'boolean', description: 'Use as build server', default: false },
        instant_validate: { type: 'boolean', description: 'Validate immediately', default: true }
      },
      required: ['name', 'ip', 'private_key_uuid']
    }

• src/types.ts:111-120 (schema)

  TypeScript interface CreateServerInput defining the input parameters for create_server tool.

  export interface CreateServerInput {
    name: string;
    description?: string;
    ip: string;
    port?: number;
    user?: string;
    private_key_uuid: string;
    is_build_server?: boolean;
    instant_validate?: boolean;
  }

• src/tools/index.ts:2-2 (registration)

  Re-export of handleTool function used by the MCP server.

  export { handleTool } from './handlers.js';

• src/index.ts:41-67 (registration)

  MCP server request handler for CallToolRequestSchema, which dispatches to handleTool based on tool name, including create_server.

  this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
    if (!this.client) {
      throw new McpError(ErrorCode.InternalError, 'Client not initialized');
    }
  
    const { name, arguments: args } = request.params;
  
    // Block write operations in read-only mode
    if (isReadOnlyMode() && !READ_ONLY_TOOLS.includes(name)) {
      throw new McpError(
        ErrorCode.InvalidRequest,
        `Operation '${name}' is not allowed in read-only mode. Set COOLIFY_READONLY=false to enable write operations.`
      );
    }
  
    try {
      const result = await handleTool(this.client, name, args || {});
      return {
        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
      };
    } catch (error) {
      if (error instanceof McpError) throw error;
      
      const message = error instanceof Error ? error.message : 'Unknown error';
      throw new McpError(ErrorCode.InternalError, `Tool execution failed: ${message}`);
    }
  });