Tenki Sandbox MCP

tenki-mcp — @tenkicloud/mcp

适用于 Tenki Cloud 的 Model Context Protocol 服务。 为任意 Agent——Claude、Codex、Cursor——提供可随时销毁的 microVM，让它能够创建实例、运行代码、读写文件、运行 git，并将实例开放到 Web。沙盒约 2 秒即可启动，按秒计费。

这是让 Tenki 成为编码 Agent 首选执行层的一部分：Agent 编写代码，Tenki 在隔离环境中运行代码。（Tenki 的 Code Reviewer 和 Runners——AI PR 审查和托管 CI——是独立产品；此服务目前提供 Sandbox。）

"Run this Python in a fresh sandbox and tell me what it prints."
        │
        ▼   tenki_run_code
   boots a microVM → runs it → returns stdout → tears it down

快速入门

export TENKI_API_KEY=tk_your_key_here
npx -y @tenkicloud/mcp     # speaks MCP over stdio

无需克隆或构建。该软件包会安装一个命令：tenki-mcp。

在 Claude Code 中使用

连接到 Tenki 托管的 MCP 服务，并使用 Tenki 账户登录：

claude mcp add --transport http tenki https://mcp.tenki.cloud/mcp
claude mcp login tenki

Claude Code 的 mcp add 命令会保存服务配置；mcp login 会执行一次性浏览器授权并选择工作区。

也可以使用 API 密钥在本地运行 MCP 服务：

claude mcp add tenki --env TENKI_API_KEY=tk_your_key_here -- npx -y @tenkicloud/mcp

或将其安装为 Claude Code 插件

此仓库也可用作插件市场。安装时会提示输入 API 密钥，并将其保存在操作系统密钥链中——无需管理环境变量：

/plugin marketplace add LuxorLabs/tenki-mcp
/plugin install tenki@tenki

在 Claude Desktop 中使用

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "tenki": {
      "command": "npx",
      "args": ["-y", "@tenkicloud/mcp"],
      "env": { "TENKI_API_KEY": "tk_your_key_here" }
    }
  }
}

在 Cursor 中使用

将相同的代码块添加到 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）：

{
  "mcpServers": {
    "tenki": {
      "command": "npx",
      "args": ["-y", "@tenkicloud/mcp"],
      "env": { "TENKI_API_KEY": "tk_your_key_here" }
    }
  }
}

在 Codex 中使用

OpenAI Codex CLI 从 ~/.codex/config.toml 读取 MCP 服务。添加：

[mcp_servers.tenki]
command = "npx"
args = ["-y", "@tenkicloud/mcp"]
env = { TENKI_API_KEY = "tk_your_key_here" }

确认运行正常

添加服务后，启动一个全新会话，让客户端加载该服务，然后向 Agent 提出以下任一请求：

• “检查 tenki 身份验证状态。”——确认凭据已被读取。
• “在全新的 Tenki 沙盒中运行 print(2+2)。”——完成启动 → 运行 → 销毁的完整往返流程。

如果没有显示 tenki_* 工具，请重启客户端，让它重新读取配置。

还没有密钥？不带密钥启动服务，然后让 Agent 检查 tenki_auth_status——它会说明需要设置什么以及设置位置。参见身份验证。

从克隆的仓库运行

用于开发或运行尚未发布的更改：

git clone https://github.com/LuxorLabs/tenki-mcp.git && cd tenki-mcp
npm install && npm run build
TENKI_API_KEY=tk_your_key_here node dist/index.js

在上述任意配置中，将 npx 命令替换为 node /absolute/path/to/tenki-mcp/dist/index.js。完整的开发流程请参见 CONTRIBUTING.md。

环境变量

变量	默认值	用途
TENKI_API_KEY	—	API 密钥（tk_…）。必须设置此变量或 TENKI_AUTH_TOKEN。
TENKI_AUTH_TOKEN	—	会话令牌（ory_st_… 或 Cookie 值）。同时设置时，优先于 TENKI_API_KEY。
TENKI_API_ENDPOINT	https://api.tenki.cloud	控制平面基础 URL（TENKI_API_URL 是其别名）。
TENKI_MCP_READONLY	关闭	1 仅注册读取工具（不创建、运行、删除或产生费用）。
TENKI_MCP_DISABLED_TOOLS	—	以逗号分隔的工具名称列表，跳过这些工具的注册。
TENKI_MCP_AUDIT	关闭	1 将每次工具调用的名称和参数键记录到 stderr。
TENKI_MCP_TRANSPORT	stdio	改用 http 提供 Streamable HTTP（见下文）。
PORT	3000	HTTP 传输端口。
TENKI_MCP_HTTP_HOST	127.0.0.1	HTTP 绑定主机；非环回地址需要设置 TENKI_MCP_HTTP_TOKEN。
TENKI_MCP_HTTP_TOKEN	—	HTTP 端点的 Bearer 令牌；环回地址上可选，非环回主机上必需。
TENKI_MCP_PUBLIC_URL	—	受 OAuth 保护的托管服务的公共基础 URL。
TENKI_MCP_OAUTH_ISSUER	—	OAuth 授权服务器颁发者。启用委托式 OAuth HTTP 模式。
TENKI_MCP_OAUTH_RESOURCE	<public URL>/mcp	RFC 8707 资源标识符，可用于访问令牌的受众。
TENKI_MCP_OAUTH_SCOPE	mcp	必需的委托作用域。
TENKI_MCP_IDENTITY_URL	—	用于交换 OAuth 访问令牌的 Tenki Identity 内部服务端点。
TENKI_MCP_IDENTITY_SERVICE_TOKEN	—	用于私有 Identity 令牌交换 RPC 的服务凭据。

工具

71 个工具——全部 68 个公开的一元 API 方法（由 CI 一致性审计强制检查）、两个工作流辅助工具，以及 tenki_auth_status。有意排除仅供实现使用的控制平面方法。按领域分组：

领域	工具
身份验证	tenki_auth_status（检查配置了哪种凭据，以及凭据是否可用——没有凭据时唯一可用的工具）
身份	tenki_whoami
运行	tenki_run_code（一次性：启动 → 运行 shell/python/js → 拆除）
沙盒	tenki_create_sandbox · tenki_get_sandbox · tenki_list_sandboxes · tenki_terminate_sandbox · tenki_pause_sandbox · tenki_resume_sandbox
会话管理	tenki_extend_sandbox · tenki_update_sandbox · tenki_terminate_sandboxes（批量） · tenki_report_sandbox_activity · tenki_list_workspace_sandboxes
执行	tenki_exec（内联输出 stdout/stderr/退出状态）
文件	tenki_read_file · tenki_write_file · tenki_list_files · tenki_stat_path · tenki_make_dir · tenki_remove_path · tenki_move_path
Git	tenki_git（克隆/检出/差异/日志——API 仅支持这四项；其他 git 命令请通过 tenki_exec 运行）
端口与预览	暴露 · 列出已暴露项 · 取消暴露 · 创建预览 URL · 打开预览 · 列出/获取/删除预览 URL · 更新预览 · 绑定/解绑预览 URL · 解析预览令牌
制品（二进制传输）	tenki_get_upload_url · tenki_get_download_url（用于二进制 PUT/GET 的签名 URL）
SSH	tenki_update_ssh_keys · tenki_issue_ssh_cert · tenki_list_ssh_gateways
快照	创建 · 获取 · 列出 · 列出会话快照 · 列出工作区快照 · 列出孤立快照 · 更新 · 删除 · 获取下载 URL
卷	创建 · 获取 · 列出 · 更新 · 删除 · 调整大小 · 挂载 · 卸载
模板	创建 · 获取 · 列出 · 更新 · 删除 · 构建 · 取消构建 · 获取构建信息 · 列出活动构建
工作区	tenki_get_workspace_usage · tenki_get_workspace_settings · tenki_update_workspace_settings · tenki_get_snapshot_retention_settings · tenki_update_snapshot_retention_settings

各版本的完整明细见 CHANGELOG.md。

身份验证

设置 TENKI_API_KEY 或 TENKI_AUTH_TOKEN 之一——如果两者都已设置，则优先使用 TENKI_AUTH_TOKEN。根据令牌前缀选择请求头：tk_… → Authorization: Bearer，ory_st_… → X-Session-Token，否则使用会话 Cookie。通过 TENKI_API_ENDPOINT 覆盖端点（默认为 https://api.tenki.cloud）。

没有凭据时，服务仍会启动，但只注册 tenki_auth_status——这样，Agent 可以调用该工具并了解需要设置什么，而不是由 MCP 客户端报告含糊的“服务启动失败”。其他工具返回身份验证错误时，可以随时让它“检查 tenki 身份验证状态”：该工具会报告凭据类型（API 密钥还是会话令牌）、端点，以及实时身份探测是否成功——绝不会泄露令牌本身。它只报告状态；请通过 tenki login 或控制面板获取凭据。

通过 HTTP 托管（v2.0-beta）

除了 stdio，服务还支持 Streamable HTTP，因此可以托管，供远程 MCP 客户端使用：

TENKI_MCP_TRANSPORT=http PORT=3000 TENKI_API_KEY=… npx -y @tenkicloud/mcp
# → tenki-mcp running on http://127.0.0.1:3000/mcp (Streamable HTTP) [loopback only, no auth]

对于单用户部署，HTTP 模式可以持有一个共享的 TENKI_API_KEY，因此会暴露强大的能力。默认情况下：

• 仅绑定到回环地址（127.0.0.1）——设置 TENKI_MCP_HTTP_HOST=0.0.0.0 可对外开放，但此时
• 必须使用 bearer token：设置 TENKI_MCP_HTTP_TOKEN 并发送 Authorization: Bearer <token>。如果绑定到非回环地址却未设置 token，服务将拒绝启动。
• 已启用 DNS 重绑定防护（Host 标头允许列表），因此恶意网页无法操控本地服务。

# expose to a network safely:
TENKI_MCP_TRANSPORT=http TENKI_MCP_HTTP_HOST=0.0.0.0 PORT=3000 \
  TENKI_MCP_HTTP_TOKEN=$(openssl rand -hex 32) TENKI_API_KEY=… npx -y @tenkicloud/mcp

将支持 HTTP 的 MCP 客户端指向 /mcp。静态密钥模式对所有会话使用同一个共享的 TENKI_API_KEY。已通过端到端验证（test/http-transport.test.mjs：身份验证门控、拒绝 DNS 重绑定、通过 HTTP 执行 connect → tools/list → 工具调用）。

托管式多租户部署则使用 Tenki Identity 的 OAuth 外观服务。MCP 服务会发布 RFC 9728 受保护资源元数据，并通过私有 Identity 服务交换每位调用者的访问 token。Identity 负责 Hydra、验证请求的受众和作用域，并签发短期 API 委托，该委托与 Tenki 同意页面上所选用户、客户端和工作区绑定。tenki-mcp 无权访问 Hydra Admin，也不持有委托签名密钥。

工作原理

Tenki 的 API 使用 ConnectRPC——基于 HTTP/1.1 的 JSON，而非 REST。每次控制平面调用都是 POST https://api.tenki.cloud/tenki.sandbox.v1.SandboxService/{Method}，并附带 lowerCamelCase JSON 请求体。每个会话的文件 I/O 则通过创建时返回的独立数据平面端点运行，并使用短期会话证书进行身份验证。此服务同时管理这两种传输，因此工具调用始终只需一行命令。

命令输出：tenki_exec 和 tenki_run_code 通过重定向到文件来捕获 stdout/stderr（sh -c '… > out 2> err'），再通过数据平面读取这些文件，因此可以通过普通 HTTP 客户端内联获取输出。

协议细节移植自经过实时验证的 n8n 社区节点。

安全

此服务持有 Tenki API 密钥，可以运行代码并消耗额度，因此请将其视为一种能力。完整的模型和 CSA MCP Server Top-10 对照表见 SECURITY.md。快速防护措施：

• **最小权限：**每个工具都带有 MCP 注解（readOnlyHint / destructiveHint）。设置 TENKI_MCP_READONLY=1 可运行仅供检查的服务（仅提供读取工具），或者设置 TENKI_MCP_DISABLED_TOOLS=tenki_run_code,… 来禁用指定工具。
• HTTP 传输默认仅绑定到回环地址；要在网络上开放，必须使用 bearer token（参见通过 HTTP 托管）。
• 审计：TENKI_MCP_AUDIT=1 会将每次工具调用的名称记录到 stderr。
• 不可信输出：tenki_run_code/tenki_exec/tenki_read_file 会返回不可信代码的输出——客户端应将工具结果视为数据，而非指令。

请通过私密的安全公告报告漏洞，而不要提交公开议题。

相关项目

• Tenki Sandbox——平台：https://tenki.cloud
• n8n-nodes-tenki——将 Tenki 用作 n8n 节点：https://github.com/opencolin/n8n-nodes-tenki

许可证

MIT