Coolify MCP Server

Instructions

Implementation Reference

• src/tools/handlers.ts:443-446 (handler)

  The handler logic for 'create_private_key' tool. Validates required 'name' and 'private_key' parameters using requireParam, then calls client.post('/security/keys', args) to create the key via Coolify API.

  case 'create_private_key':
    requireParam(args, 'name');
    requireParam(args, 'private_key');
    return client.post('/security/keys', args);

• src/tools/definitions.ts:624-636 (schema)

  Tool definition including name, description, and JSON input schema for validation in MCP.

  {
    name: 'create_private_key',
    description: 'Create a new SSH private key',
    inputSchema: {
      type: 'object',
      properties: {
        name: { type: 'string', description: 'Key name' },
        description: { type: 'string', description: 'Key description' },
        private_key: { type: 'string', description: 'Private key content (PEM format)' }
      },
      required: ['name', 'private_key']
    }
  },

• src/types.ts:158-162 (schema)

  TypeScript type definition for CreatePrivateKeyInput, matching the tool's input schema.

  export interface CreatePrivateKeyInput {
    name: string;
    description?: string;
    private_key: string;
  }

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

  Exports the tool definitions and handleTool function, used by the MCP server for tool listing and execution.

  export { toolDefinitions, getToolDefinitions, isReadOnlyMode, READ_ONLY_TOOLS } from './definitions.js';
  export { handleTool } from './handlers.js';

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

  Registers the CallToolRequestHandler which dispatches to handleTool based on tool name, including read-only checks.

  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}`);
    }
  });