Vexdock MCP 服务器是 Vexdock 自托管部署平台内置的模型上下文协议接口。每个 Vexdock 面板除仪表盘外，还在 /mcp 路径上提供 MCP 服务器，例如 https://panel.example.com/mcp，或在面板尚未绑定域名时使用 http://<server-ip>:3000/mcp。传输方式为 streamable HTTP。服务器本身不持有凭据：每次工具调用都以客户端发送的 bearer 令牌身份执行，因此能且只能执行该令牌权限范围内的操作。
连接方式有两种。第一种是创建令牌：在仪表盘的 System → Settings → API tokens 中创建令牌，令牌值只显示一次。应选择工作所需的最小范围。Claude Code 可使用命令 claude mcp add --transport http vexdock https://panel.example.com/mcp --header "Authorization: Bearer $VEXDOCK_TOKEN" 连接。接受带 headers 的 JSON 服务器列表的客户端（如 Cursor 及大多数其他客户端）可配置。令牌缺失或已撤销时，连接本身会以 401 失败。令牌应视为机密，放入客户端配置或环境变量，不得出现在回复、提交或日志中。第二种是 OAuth，无需令牌：无法发送请求头的客户端（claude.ai、ChatGPT）仅按 URL 添加服务器，401 会引导其访问面板的 OAuth 元数据，客户端自行注册并打开面板的同意屏幕，管理员选择完全访问或按项目和级别授权，此后客户端自行刷新访问令牌。此方式仅在面板已设置 https:// 地址为 PUBLIC_URL 后可用。授权会出现在令牌旁边，以客户端命名，并可在那里撤销。
权限分为四类。admin：所有工具、所有项目，如同仪表盘会话。项目令牌：一组项目，每个项目为 read 或 write。read：项目、服务、环境、日志、统计、部署、域名、任务；变量值、数据库凭据和 SQL 不可访问。write：项目内的一切，包括 deploy、exec、变量、query_database 以及编辑服务和域名；服务的来源（提供商、仓库、Git 连接、凭据、镜像、compose 片段、注册表登录）仍仅限 admin，分支和构建设置不在此限。docker_cleanup 无论项目如何都仅限 admin。whoami 可回答此令牌的类型；若为项目令牌，则给出每个授权的 project_id 和级别。应先调用 whoami。项目令牌在 list_projects 中只能看到自己的项目，访问范围外的 id 会返回 FORBIDDEN，与不存在的 id 表现相同。
工具按级别划分。读取类：whoami（任意级别，返回账户和此令牌的授权）、list_projects（read，返回可访问项目及其环境和容器数量）、get_project（read，返回项目的一个环境：服务状态、域名、最近十次部署）、get_service（read，返回一个服务的配置和计划任务）、service_logs（read，返回容器输出最后若干行，默认 tail 200，stderr 行以 [stderr] 开头）、service_stats（read，返回一次实时 CPU、内存、网络和磁盘采样，容器停止时失败）、list_deployments（read，返回环境最近五十次部署）、get_deployment（read，返回一次部署及其步骤，每步输出截取最后五十行）、list_templates（read，返回应用模板：每个模板添加的服务及其域名指向的服务）。写入类：deploy（write，部署项目的环境（project_id）或单个服务（service_id），最多等待 15 分钟，返回每次部署的状态、决定性步骤和日志尾部）、cancel_deployment（write，停止排队或运行中的部署）、rollback（write，重新部署过去成功部署所构建的镜像并等待）、service_action（write，在不构建的情况下启动、停止或重启容器）、service_exec（write，在运行中的容器内执行命令，返回退出码和输出，非交互式，限时十分钟）、get_variables（write，返回某一层的变量明文，scope 为 project、environment 或 service，id 为该对象的 id）、set_variables（write，添加或修改键（set），删除键（remove），将新键标记为机密（secret_keys），未触及的键保持不变）、add_service_from_template（write，使用生成的密码添加模板的服务，之后需部署）、update_service（write，按 get_service 返回的名称修改服务字段，下次部署生效；来源字段需要 admin）、add_domain（write，将主机名路由到 compose 服务和容器端口；https_enabled 会签发证书）、remove_domain（write，停止路由主机名）、run_task（write，立即运行计划任务并返回输出）、query_database（write，对数据库服务执行一条 SQL 语句，包括写入）、docker_cleanup（admin，清理容器、镜像、网络或构建缓存）。
变量在部署时合并：项目、环境、服务，最窄的层胜出。变量或服务字段的更改在下次部署时到达容器。当 deploy 返回 still_running 时，表示流水线超出了等待时间；应使用 get_deployment 逐个跟进 id，直到状态为 success、failed 或 cancelled。删除项目、环境、服务或卷不是工具操作，需由人员在仪表盘中完成。
错误方面，工具错误会携带 API 的状态和代码，如 403 FORBIDDEN: ...。FORBIDDEN 表示超出此令牌的授权范围，或没有该 id，应检查 whoami；NOT_FOUND 表示管理员令牌看到的不存在资源；INVALID_REQUEST 的消息会指出哪个参数有误，可安全展示；CONFLICT 表示名称或主机名已被占用；DATABASE_NOT_RUNNING 表示对已停止的数据库执行 query_database，需先部署或启动。
建议的工作方式：先 whoami，再用读取工具解析 id，报告时在 id 旁注明名称；优先选择最窄的操作，如服务部署优于项目部署，service_exec 或 service_action 优于重新部署；写入前先读取，如 set_variables 前先 get_variables，update_service 前先 get_service；在执行会写入的 query_database、会更改数据的 service_exec 或 remove_domain 之前，说明将更改什么并获得确认；部署后报告每个服务的状态，失败时报告步骤名称和能解释问题的日志尾部行；除非用户要求，变量值、数据库凭据以及 service_exec 从机密中打印的任何内容都不应出现在回复中。
适用场景包括：通过 MCP 客户端以最小权限对 Vexdock 部署进行读取和操作、自动化部署与回滚、查看日志和统计、管理变量和数据库查询、路由域名、运行计划任务等。限制包括：服务器本身不存储凭据，依赖客户端提供的令牌或 OAuth 授权；权限严格由令牌级别决定；删除项目、环境、服务或卷需人工在仪表盘完成；service_exec 非交互且限时十分钟；docker_cleanup 仅限 admin；OAuth 方式需要 PUBLIC_URL 为 https:// 地址。