Coolify MCP Server

# Security Considerations This document outlines security considerations and guardrails for the Coolify MCP Server. ## API Token Security ### Token Protection - The Coolify API token is stored server-side as an environment variable (`COOLIFY_API_TOKEN`) - The token is NEVER exposed to AI agents through tool responses - Token is only used server-side for API authentication ### Recommended Token Permissions Create a dedicated API token in Coolify with minimal required permissions: - Read access to projects and applications - Create/update/delete applications within specific projects - Deployment permissions - NO access to system-wide settings or other teams' resources ## Input Validation ### Schema Validation - All tool inputs are validated using Zod schemas - Strict type checking prevents injection attacks - Required fields are enforced ### Sanitization - Environment variable values are passed as-is but validated - Git URLs and Docker image names are validated for proper format - Application names are restricted to safe characters ## Resource Isolation ### Project-Level Isolation - Each tool call requires a `projectId` parameter - Applications are scoped to specific projects - Optional team-level isolation with `COOLIFY_DEFAULT_TEAM_ID` ### Quotas and Limits - `COOLIFY_MAX_APPS_PER_PROJECT` prevents unlimited app creation - Name conflict checks prevent accidental overwrites - Built-in safety tools (`coolify.check_quota`, `coolify.check_name_conflicts`) ## Network Security ### API Communication - All Coolify API calls use HTTPS - Request/response logging doesn't include sensitive data - Retries are limited to prevent API abuse ### Container Security - The MCP server runs in its own container - No direct Docker socket access - All container operations go through Coolify API ## Audit Trail ### Logging - Every tool invocation is logged with: - Tool name - Input arguments (sanitized) - Success/failure status - Timestamp ### API Request Tracking - Each Coolify API request gets a unique request ID - Request/response correlation for debugging - Error details are logged for security review ## Deployment Safety ### Idempotent Operations - Template deployments are idempotent - Same request won't create duplicate applications - Deploy with `overwrite: false` by default ### Template Security - Pre-vetted templates from trusted sources - Docker images pinned to specific tags - No privileged container operations ## Recommended Practices ### For Operators 1. Use dedicated Coolify API token with minimal permissions 2. Set appropriate app quotas per project 3. Monitor MCP server logs for suspicious activity 4. Regularly rotate API tokens ### For AI Agent Developers 1. Always check quotas before creating apps 2. Verify name availability before deployment 3. Handle errors gracefully 4. Log deployment IDs for tracking ### For Users 1. Review template environment variables before deploying 2. Use unique application names 3. Monitor deployment status 4. Keep sensitive data in Coolify secrets, not MCP tool calls ## Known Limitations 1. **Secret Management**: The MCP server doesn't directly manage Coolify secrets - Templates require secrets to be passed as environment variables - Consider using Coolify's native secret management 2. **Network Isolation**: No direct control over container networking - Relies on Coolify's network policies - All network access is mediated by Coolify 3. **Resource Limits**: Limited to what Coolify enforces - No CPU/memory limits set by MCP server - Uses Coolify's default resource constraints ## Reporting Security Issues If you discover a security vulnerability: 1. Do NOT open a public issue 2. Send details to: security@coolify.io 3. Include steps to reproduce 4. Allow time for fix before disclosure