Lizard MCP

Lizard MCP

一个 MCP 服务，可让 ChatGPT、Claude 和其他 MCP 客户端在 Lizard (lizard.build) 上部署和管理应用。

连接一次后，就可以用自然语言让助手发布服务、读取日志、设置密钥、扩展副本或绑定域名。

连接客户端

该服务通过 POST /mcp 提供 Streamable HTTP 接口，也支持 stdio，供启动本地进程的客户端使用（参见下文）。托管实例运行在：

https://employ-woman-g1q2.us-east-1.onlizard.com/mcp

每个请求都需要携带 bearer token。支持 OAuth 的客户端会自行获取令牌——服务会公布获取地址，因此无需粘贴任何内容。只发送请求头的客户端则使用 liz_ API 密钥：

lizard keys create my-mcp-key

也可以在控制面板中通过 Sandboxes → Get started → New API key 创建相同的密钥。无论哪种方式，密钥都只会显示一次。

Claude Code

claude mcp add --transport http lizard https://employ-woman-g1q2.us-east-1.onlizard.com/mcp

Claude Code 会在首次使用时运行 OAuth 流程。若要跳过该流程并使用密钥：

claude mcp add --transport http lizard https://employ-woman-g1q2.us-east-1.onlizard.com/mcp \
  --header "Authorization: Bearer liz_your_key"

Cursor 和其他通过 JSON 配置的客户端

{
  "mcpServers": {
    "lizard": {
      "url": "https://employ-woman-g1q2.us-east-1.onlizard.com/mcp",
      "headers": { "Authorization": "Bearer liz_your_key" }
    }
  }
}

ChatGPT

ChatGPT 连接到 URL 后会自行运行 OAuth，无需粘贴密钥。它需要启用开发者模式并注册连接；详情请参阅下文的 发布到 Codex / ChatGPT。

连接本地服务

按下一节所述运行服务，然后使用 http://localhost:3000/mcp 替代托管服务的 URL。

检查连接

curl -sS -X POST https://employ-woman-g1q2.us-east-1.onlizard.com/mcp \
  -H "Authorization: Bearer liz_your_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

不带令牌时，同一请求会返回 401，并附带一个指向 OAuth 元数据的 WWW-Authenticate 请求头。这表示服务正常运行，并非发生故障。

运行

npm install
npm run build
npm start

开发时可启用热重载：

npm run dev

通过 stdio 运行

npm start 会启动 HTTP 服务。若要让客户端启动服务进程，请将其指向 dist/stdio.js：

{
  "mcpServers": {
    "lizard": {
      "command": "node",
      "args": ["/path/to/lizard-mcp/dist/stdio.js"],
      "env": { "LIZARD_TOKEN": "liz_your_key" }
    }
  }
}

启动的进程没有可用于运行 OAuth 的浏览器，因此令牌需从环境变量读取，并将进程绑定到单个用户。即使没有令牌，服务仍会启动并列出工具；调用工具时会返回要求提供密钥的提示。

配置

变量	默认值	用途
PORT	3000	监听端口（仅用于 HTTP）
PUBLIC_URL	http://localhost:$PORT	客户端访问此服务的 URL。用于设置 OAuth 资源标识符，因此在生产环境中必须与实际地址一致。
PLATFORM_URL	https://lizard.build	此服务调用的 Lizard API
LIZARD_TOKEN	—	stdio 模式下使用的 API 密钥，因为此模式没有 OAuth 握手流程。也可使用 LIZARD_API_KEY。

工具

区域	工具
账户	whoami、workspace_list、project_list、project_create、project_pause、project_resume、workspace_pause、workspace_resume、region_list、billing_status、billing_summary
服务	service_list、service_show、service_create、service_set、service_rename、service_delete、service_pause、service_resume、service_sleep_status、service_sleep_set、service_scale、service_get_port、service_set_port、addon_create
部署	deploy_redeploy、deploy_restart、deploy_events
日志和指标	logs_tail、metrics_get
密钥	secrets_list、secrets_set、secrets_delete、secrets_refs
域名	domain_attach、domain_verify、domain_delete
卷	volume_list、volume_resize
Git	git_connect、git_checkout、git_status
Shell	ssh_exec
沙盒	sandbox_list、sandbox_show、sandbox_create、sandbox_exec、sandbox_read_file、sandbox_write_file、sandbox_delete
配置即代码	config_apply

工具名称使用 snake_case（而非 MCP 规范允许的点号），以符合 OpenAI 的函数名称模式 ^[a-zA-Z0-9_-]{1,64}$，部分 ChatGPT/Codex 界面会直接强制执行此模式。

破坏性工具——service_delete、secrets_delete、domain_delete、ssh_exec——需要显式的确认参数，因此客户端不会意外删除任何内容或运行任意命令。

billing_status 为只读工具：它会显示套餐（Pro 套餐为每月 $19，每月含 $19 额度、试用版、有效期至 2026 年 11 月 1 日的预付额度，或企业版）和 Billing 链接。开通、付费及取消 Pro 均需在浏览器中操作。如果账户必须先付费才能创建资源，工具错误会在最后一行提供平台提示语及需要打开的页面，而 structuredContent.error 则包含错误代码（PAYMENT_REQUIRED）、paymentStatus 和相关链接。

沙盒工作流

Lizard（lizard.build）提供 Lizard Sandboxes，用于短时运行代码。这些资源与应用服务相互独立。先调用 project_list，然后使用选定的项目调用 sandbox_create，并设置 confirm: true。保留返回的 sandboxId，供后续调用使用。

{"name":"sandbox_create","arguments":{"project":"YOUR_PROJECT_ID","lifetimeMs":300000,"confirm":true}}

使用 sandbox_write_file 写入脚本，使用 sandbox_exec 运行脚本，再使用 sandbox_read_file 读取结果。最后调用 sandbox_delete。创建、执行、写入和删除操作都需要先获得用户批准，客户端才能设置 confirm: true。MCP 服务不会打开确认对话框。

沙盒使用 interpreter 模板、small 大小，默认路径为 /workspace。沙盒默认在五分钟后过期；lifetimeMs 接受 60,000–3,600,000 毫秒。过期或删除后，所有文件都会丢失。创建沙盒会使用计费的云资源。主机文件、环境变量和访问令牌不会进入沙盒。

命令以 root 身份在沙盒内运行，默认超时时间为 60 秒，最长可达 120 秒。取消命令、命令超时或命令请求状态不确定时，都会销毁整个沙盒，以停止远程工作。confirm 字段用于确认接受文件丢失。请使用为当前任务创建的沙盒，并提前将所需文件保存在其他位置。正常的非零退出代码不会销毁沙盒。拒绝访问或输入不会导致沙盒被删除。服务端绝不会自动重试命令。

文本读写最多支持 64 KiB 的 UTF-8 内容。每个输出流上限为 64 KiB，并会包含截断标记。所有路径均指向沙盒。sandbox_show 和 sandbox_list 可用于在重试前检查状态不确定的操作结果。若沙盒已不存在，sandbox_delete 会将其视为成功的空操作。

HTTP 服务端使用调用方的 Bearer 令牌（包括 OAuth 令牌和 API 密钥）处理每次调用。它不会保存共享沙盒句柄或全局 SDK 凭据。客户端断开连接后，必须重新连接才能删除沙盒；沙盒的有限生命周期仍会作为最终清理保障。

认证

该服务以 MCP 受保护资源（RFC 9728）的形式实现 OAuth 2.1。它本身不持有任何密钥：每个请求都携带一个 bearer token，由 Lizard 判断该令牌是否有效。OAuth 签发的令牌和 liz_ API 密钥均可使用。

每个请求都会创建一个绑定到调用者令牌的新服务实例，因此单个进程可以为许多用户提供服务，且不会共享状态。

通过 stdio 使用时，不涉及 OAuth，也没有按请求传递的令牌——密钥来自环境变量，进程只为一个用户提供服务，如上所述。

测试

npm test        # unit and MCP transport tests
npm run typecheck
npm run build

要测试真实的沙箱资源，请设置 LIZARD_API_KEY、LIZARD_PROJECT_ID 和 LIZARD_LIVE_TESTS=1，然后运行 npm exec -- vitest run test/live/sandboxes.test.ts。该测试通过 stdio MCP 创建沙箱、运行 shell 和文件工具、检查超时清理，并删除沙箱。测试会使用计费资源；不会部署 MCP 服务。

test/manual/mcp-inspector.md 介绍了如何针对存根平台和真实平台执行端到端检查。

已部署实例

该服务本身作为 Lizard 应用运行：位于 mikelun 工作区中的 lizard-mcp， 直接从此仓库部署（git-source，推送到 main 时自动重新部署）。

https://employ-woman-g1q2.us-east-1.onlizard.com/mcp

该服务的 PUBLIC_URL 已设为与之匹配，因此 allowedHosts/OAuth 资源 元数据与实际域名一致——请参阅 src/index.ts。

发布到 Codex / ChatGPT

.codex-plugin/plugin.json 已就位。这是一个托管的远程 MCP 服务（而非 打包的 stdio 服务），因此通过 .app.json 和已注册的连接进行配置， 而不是通过 .mcp.json。最后一步需要在真实的 ChatGPT 会话中由人工完成—— 无法通过脚本实现：

1. 在 ChatGPT 中：设置 → 安全与登录 → 开发者模式（启用）。
2. 前往 ChatGPT 插件 → + → 输入上方的 MCP 服务 URL → 完成连接。
3. 从浏览器 URL 中复制生成的 plugin_asdk_app_... ID。
4. 在仓库根目录添加 .app.json：

   { "app": { "id": "plugin_asdk_app_..." } }
   

5. 在 .codex-plugin/plugin.json 中添加 "apps": "./.app.json"。
6. 通过市场条目在本地测试（使用 @plugin-creator，或手动编写 ~/.agents/plugins/marketplace.json），然后通过 插件提交门户 提交以供公开审核。

许可证

MIT