如何把 AI 编程工具接入 Coolify 的 MCP 服务器【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolifyCoolify 内置了一个基于 Model Context ProtocolMCP的服务器让支持 MCP 的 AI 编程工具可以通过 JSON-RPC 接口查询服务器、项目、应用、数据库、部署状态并执行控制与部署操作。本文介绍如何在一台已运行的 Coolify 实例上完成三件事在实例设置中开启 MCP 服务器、创建带正确权限的 API Token以及把端点接入 MCP 客户端并验证连通。完成后可用命令核对每一步的预期结果接入失败时也能按返回的 401 / 403 / 404 定位是哪一层开关或 Token 出了问题。开启实例级 MCP 服务器开关进入 Coolify 的Settings → Advanced页面找到API and MCP分区。该分区里有一个MCP server开关对应配置项is_mcp_server_enabled其界面说明为 “Expose the authenticated Streamable HTTP endpoint at /mcp”即把/mcp暴露为一个需要鉴权的 Streamable HTTP 端点。将其设为Enabled并保存该表单项为即时保存。开启后页面会显示一条 “MCP endpoint” 提示内容等价于https://你的域名/mcp使用 Security → API Tokens 中创建的 Sanctum Bearer Token 鉴权。判断这一步是否必要如果实例开关为Disabled/mcp端点对所有请求直接返回404见 EnsureMcpEnabled——它检查InstanceSettings的is_mcp_server_enabled未开启即abort(404)。创建带权限的 API TokenMCP 端点通过 Sanctum Bearer Token 鉴权且每个 Token 只能访问其所属团队的资源。Token 需要在Security → API Tokens页面创建。Token 的权限ability决定 MCP 工具能做什么只读查询类工具list_projects、get_server、get_logs等要求 Token 带有read权限。缺少该权限时工具调用不会报 HTTP 错误而是返回result.isError: true内容为 “Missing required permissions”见 McpEndpointTest 中 “tool calls fail when the token lacks the read ability” 用例。生命周期操作control的 start/stop/restart、deploy、cancel_deployment要求 Token 带有deploy权限这一点在 MCP 服务器的 instructions 中明确声明见 CoolifyServer。测试用例创建的 Token 形如$user-createToken(mcp-read, [read])即名称为mcp-read、ability 为read的 Sanctum Token。另外注意如果 Token 所属的用户已不再属于该团队请求会返回401。在 MCP 客户端中配置端点在 AI 编程工具或任意 MCP 客户端中添加一个 MCP 服务器端点 URL 为https://你的Coolify域名/mcp通信采用 Streamable HTTP 方式请求需携带以下请求头其中 Bearer Token 替换为你在上一步创建的 API Token 明文值请求头值Content-Typeapplication/jsonAcceptapplication/json, text/event-streamAuthorizationBearer 你的API Token协议是标准 JSON-RPC 2.0。用curl可以直接完成连通性验证等价于客户端初始化后的tools/list调用curl -X POST https://你的Coolify域名/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -H Authorization: Bearer 你的API Token \ -d { jsonrpc: 2.0, id: 1, method: tools/list, params: {} }验证接入是否成功验证工具列表。上面的tools/list请求成功时应返回200result.tools中应能看到工具名包括coolify_help、get_infrastructure_overview、list_servers、list_projects、list_applications、get_logs、list_env_keys以及操作类工具control、deploy等完整清单见 McpEndpointTest 第 119–144 行的断言服务器共注册约 40 个工具见 CoolifyServer。验证工具调用。以list_projects为例发起tools/callcurl -X POST https://你的Coolify域名/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -H Authorization: Bearer 你的API Token \ -d { jsonrpc: 2.0, id: 1, method: tools/call, params: { name: list_projects, arguments: { per_page: 2, page: 1 } } }成功时响应体result.content[0].text是一段 JSON包含data项目数组每项含uuid、name等字段和_paginationtotal、per_page等分页信息。per_page上限为 100page从 1 开始。数据范围被限定为 Token 所属团队的项目。按错误码排查接入失败现象含义处理404实例级 MCP 开关未开启回到 Settings → Advanced 把 MCP server 设为 Enabled401未带 Token未通过 Sanctum 鉴权检查Authorization: Bearer token请求头401Token 无效Token 所属用户已不属于该团队用仍属于该团队的用户重新创建 Token403响应体为{message:MCP server is disabled for this team.}团队级 MCP 开关被关闭在团队设置中重新启用。团队默认是开启的此错误只在团队开关被显式关闭时出现见 EnsureTeamMcpEnabled 与测试 “MCP endpoint is enabled for teams by default”result.isError: true内容为 “Missing required permissions”Token 缺少 read或 deploy权限创建带对应 ability 的新 Token端点由四条中间件链式保护mcp.enabled实例开关、auth:sanctum鉴权、api.token.teamToken 必须属于当前团队、mcp.team.enabled团队开关见 routes/ai.php。接入后可以用它做什么工具调用成功后会写入审计日志audit 通道事件mcp.tool.called含tool、team_id、outcome三个字段outcome 为success/denied/error可以在实例的审计记录中核对 AI 工具都调用了哪些操作。按 MCP 服务器自带的 instructionsAI 客户端的推荐用法是先调coolify_help按意图分类的工具目录或get_infrastructure_overview资源计数 health_hints健康提示获取全局视图用search_resources做模糊查找再用list_*/get_*深入细节排查部署问题时按list_deployments → get_deployment(include_log_summarytrue)的顺序走。需要执行control、deploy、cancel_deployment时确保 Token 带 deploy 权限。响应格式统一为{ data, _actions?, _pagination? }。有两点数据安全边界值得注意环境变量只返回键名、永不返回键值配置快照与完整部署日志也不会通过 MCP 返回仅部署日志摘要可选会做尽力而为的脱敏。服务器详情中的sentinel_token、private_key_id、已保存的代理配置等敏感字段会被剔除后再返回见 McpEndpointTest 第 217–246 行用例。【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
如何把 AI 编程工具接入 Coolify 的 MCP 服务器【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolifyCoolify 内置了一个基于 Model Context ProtocolMCP的服务器让支持 MCP 的 AI 编程工具可以通过 JSON-RPC 接口查询服务器、项目、应用、数据库、部署状态并执行控制与部署操作。本文介绍如何在一台已运行的 Coolify 实例上完成三件事在实例设置中开启 MCP 服务器、创建带正确权限的 API Token以及把端点接入 MCP 客户端并验证连通。完成后可用命令核对每一步的预期结果接入失败时也能按返回的 401 / 403 / 404 定位是哪一层开关或 Token 出了问题。开启实例级 MCP 服务器开关进入 Coolify 的Settings → Advanced页面找到API and MCP分区。该分区里有一个MCP server开关对应配置项is_mcp_server_enabled其界面说明为 “Expose the authenticated Streamable HTTP endpoint at /mcp”即把/mcp暴露为一个需要鉴权的 Streamable HTTP 端点。将其设为Enabled并保存该表单项为即时保存。开启后页面会显示一条 “MCP endpoint” 提示内容等价于https://你的域名/mcp使用 Security → API Tokens 中创建的 Sanctum Bearer Token 鉴权。判断这一步是否必要如果实例开关为Disabled/mcp端点对所有请求直接返回404见 EnsureMcpEnabled——它检查InstanceSettings的is_mcp_server_enabled未开启即abort(404)。创建带权限的 API TokenMCP 端点通过 Sanctum Bearer Token 鉴权且每个 Token 只能访问其所属团队的资源。Token 需要在Security → API Tokens页面创建。Token 的权限ability决定 MCP 工具能做什么只读查询类工具list_projects、get_server、get_logs等要求 Token 带有read权限。缺少该权限时工具调用不会报 HTTP 错误而是返回result.isError: true内容为 “Missing required permissions”见 McpEndpointTest 中 “tool calls fail when the token lacks the read ability” 用例。生命周期操作control的 start/stop/restart、deploy、cancel_deployment要求 Token 带有deploy权限这一点在 MCP 服务器的 instructions 中明确声明见 CoolifyServer。测试用例创建的 Token 形如$user-createToken(mcp-read, [read])即名称为mcp-read、ability 为read的 Sanctum Token。另外注意如果 Token 所属的用户已不再属于该团队请求会返回401。在 MCP 客户端中配置端点在 AI 编程工具或任意 MCP 客户端中添加一个 MCP 服务器端点 URL 为https://你的Coolify域名/mcp通信采用 Streamable HTTP 方式请求需携带以下请求头其中 Bearer Token 替换为你在上一步创建的 API Token 明文值请求头值Content-Typeapplication/jsonAcceptapplication/json, text/event-streamAuthorizationBearer 你的API Token协议是标准 JSON-RPC 2.0。用curl可以直接完成连通性验证等价于客户端初始化后的tools/list调用curl -X POST https://你的Coolify域名/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -H Authorization: Bearer 你的API Token \ -d { jsonrpc: 2.0, id: 1, method: tools/list, params: {} }验证接入是否成功验证工具列表。上面的tools/list请求成功时应返回200result.tools中应能看到工具名包括coolify_help、get_infrastructure_overview、list_servers、list_projects、list_applications、get_logs、list_env_keys以及操作类工具control、deploy等完整清单见 McpEndpointTest 第 119–144 行的断言服务器共注册约 40 个工具见 CoolifyServer。验证工具调用。以list_projects为例发起tools/callcurl -X POST https://你的Coolify域名/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -H Authorization: Bearer 你的API Token \ -d { jsonrpc: 2.0, id: 1, method: tools/call, params: { name: list_projects, arguments: { per_page: 2, page: 1 } } }成功时响应体result.content[0].text是一段 JSON包含data项目数组每项含uuid、name等字段和_paginationtotal、per_page等分页信息。per_page上限为 100page从 1 开始。数据范围被限定为 Token 所属团队的项目。按错误码排查接入失败现象含义处理404实例级 MCP 开关未开启回到 Settings → Advanced 把 MCP server 设为 Enabled401未带 Token未通过 Sanctum 鉴权检查Authorization: Bearer token请求头401Token 无效Token 所属用户已不属于该团队用仍属于该团队的用户重新创建 Token403响应体为{message:MCP server is disabled for this team.}团队级 MCP 开关被关闭在团队设置中重新启用。团队默认是开启的此错误只在团队开关被显式关闭时出现见 EnsureTeamMcpEnabled 与测试 “MCP endpoint is enabled for teams by default”result.isError: true内容为 “Missing required permissions”Token 缺少 read或 deploy权限创建带对应 ability 的新 Token端点由四条中间件链式保护mcp.enabled实例开关、auth:sanctum鉴权、api.token.teamToken 必须属于当前团队、mcp.team.enabled团队开关见 routes/ai.php。接入后可以用它做什么工具调用成功后会写入审计日志audit 通道事件mcp.tool.called含tool、team_id、outcome三个字段outcome 为success/denied/error可以在实例的审计记录中核对 AI 工具都调用了哪些操作。按 MCP 服务器自带的 instructionsAI 客户端的推荐用法是先调coolify_help按意图分类的工具目录或get_infrastructure_overview资源计数 health_hints健康提示获取全局视图用search_resources做模糊查找再用list_*/get_*深入细节排查部署问题时按list_deployments → get_deployment(include_log_summarytrue)的顺序走。需要执行control、deploy、cancel_deployment时确保 Token 带 deploy 权限。响应格式统一为{ data, _actions?, _pagination? }。有两点数据安全边界值得注意环境变量只返回键名、永不返回键值配置快照与完整部署日志也不会通过 MCP 返回仅部署日志摘要可选会做尽力而为的脱敏。服务器详情中的sentinel_token、private_key_id、已保存的代理配置等敏感字段会被剔除后再返回见 McpEndpointTest 第 217–246 行用例。【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
