Luxor Sandbox MCP

Luxor MCP：@luxorai/mcp

**一个适用于 Luxor Sandbox 的 Model Context Protocol 服务，是 Luxor AI 的 Luxor Agent Cloud 的一部分。**为任何 Agent（Claude、Codex、Cursor）提供一次性微型 VM，可创建 VM、在其中运行代码、读写文件、运行 git，并将其开放到 Web。沙箱约 2 秒即可启动，按秒计费。

Agent 编写代码，Luxor 在隔离环境中运行代码。（Luxor Code Review 和 Luxor 托管的 CI 运行器是独立产品；此服务目前提供 Sandbox。）

旧名称 @tenkicloud/mcp 仍可使用，发布的代码相同。

"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 LUXORAI_API_KEY=lx_your_key_here
npx -y @luxorai/mcp     # speaks MCP over stdio

无需克隆或构建。此软件包会安装命令 luxor-mcp（以及功能相同的 tenki-mcp）。

在 Claude Code 中使用

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

claude mcp add --transport http luxor https://mcp.luxor.ai/mcp
claude mcp login luxor

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

或者，使用 API 密钥在本地运行 MCP 服务：

claude mcp add luxor --env LUXORAI_API_KEY=lx_your_key_here -- npx -y @luxorai/mcp

或将其安装为 Claude Code 插件

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

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

tenki@tenki 插件仍可使用。

在 Claude Desktop 中使用

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "luxor": {
      "command": "npx",
      "args": ["-y", "@luxorai/mcp"],
      "env": { "LUXORAI_API_KEY": "lx_your_key_here" }
    }
  }
}

在 Cursor 中使用

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

{
  "mcpServers": {
    "luxor": {
      "command": "npx",
      "args": ["-y", "@luxorai/mcp"],
      "env": { "LUXORAI_API_KEY": "lx_your_key_here" }
    }
  }
}

在 Codex 中使用

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

[mcp_servers.luxor]
command = "npx"
args = ["-y", "@luxorai/mcp"]
env = { LUXORAI_API_KEY = "lx_your_key_here" }

确认配置有效

添加服务后，启动一个新会话，以便客户端加载该服务，然后让 Agent 执行以下任一操作：

• “检查 tenki 身份验证状态。”：确认是否已获取凭据。
• “在全新的 Luxor 沙箱中运行 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
LUXORAI_API_KEY=lx_your_key_here node dist/index.js

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

环境变量

变量	默认值	用途
LUXORAI_API_KEY	-	API 密钥（lx_… 或 tk_…）。必须设置此项或 LUXORAI_AUTH_TOKEN。
LUXORAI_AUTH_TOKEN	-	会话令牌（ory_st_… 或 Cookie 值）。同时设置两者时，优先使用 LUXORAI_AUTH_TOKEN。
LUXORAI_API_ENDPOINT	https://api.tenki.cloud（与 https://api.luxor.ai 使用相同的 API）	控制平面基础 URL（LUXORAI_API_URL 是其别名）。
LUXORAI_MCP_READONLY	关闭	1 表示仅注册读取工具（不创建、运行、删除或消费资源）。
LUXORAI_MCP_DISABLED_TOOLS	-	以逗号分隔的不注册工具名称。
LUXORAI_MCP_AUDIT	关闭	1 表示将每次工具调用的名称和参数键记录到 stderr。
LUXORAI_MCP_TRANSPORT	stdio	http 表示改为提供 Streamable HTTP 服务（见下文）。
PORT	3000	HTTP 传输端口。
LUXORAI_MCP_HTTP_HOST	127.0.0.1	HTTP 绑定主机；非环回地址需要设置 LUXORAI_MCP_HTTP_TOKEN。
LUXORAI_MCP_HTTP_TOKEN	-	HTTP 端点的 Bearer 令牌；环回地址上可选，非环回主机上必需。
LUXORAI_MCP_PUBLIC_URL	-	受 OAuth 保护的托管服务的公共基础 URL。
LUXORAI_MCP_OAUTH_ISSUER	-	OAuth 授权服务器颁发者。启用委派式 OAuth HTTP 模式。
LUXORAI_MCP_OAUTH_RESOURCE	<public URL>/mcp	RFC 8707 资源标识符，需包含在访问令牌的受众中。以逗号分隔的列表可为每个域名提供一个资源；元数据会返回与请求主机匹配的资源，否则返回第一个。
LUXORAI_MCP_OAUTH_SCOPE	mcp	必需的委派作用域。
LUXORAI_MCP_IDENTITY_URL	-	用于交换 OAuth 访问令牌的内部 Luxor Identity 服务端点。
LUXORAI_MCP_IDENTITY_SERVICE_TOKEN	-	用于私有 Identity 令牌交换 RPC 的服务凭证。
上述每个 LUXORAI_* 变量仍可使用对应的 TENKI_* 名称（例如 TENKI_API_KEY、TENKI_MCP_TRANSPORT）。所有 LUXORAI_* 凭据都会先于任何 TENKI_* 凭据读取。密钥以 lx_ 开头；仍接受 tk_… 密钥。

工具

82 个工具：所有 76 个值得作为工具公开的公开一元 API 方法（通过 CI 一致性审计 强制执行；如果某个工具调用了 API 已不再提供的方法，审计也会失败；GitOperation 按操作分别作为工具公开）、两个工作流辅助工具，以及 tenki_auth_status。工具名称保留 tenki_ 前缀。部分管理功能（已发布的镜像、已保存的 Tailscale 连接）和仅供实现使用的控制平面方法会有意排除。按领域分组：

领域	工具
身份验证	tenki_auth_status（配置了哪种凭据，以及是否可用；没有配置凭据时唯一可用的工具）
身份	tenki_whoami
运行	tenki_run_code（一次性：启动 → 运行 shell/python/js → 拆除）
沙箱	tenki_create_sandbox · tenki_get_sandbox · tenki_get_sandbox_metrics · tenki_list_sandboxes · tenki_terminate_sandbox · tenki_pause_sandbox · tenki_resume_sandbox · tenki_fork_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_clone · tenki_git_checkout · tenki_git_diff · tenki_git_log（API 支持的四种操作；传入 directory 以指定克隆的仓库；通过 tenki_exec 运行其他 git 命令）
端口与预览	expose · list-exposed · unexpose · create-preview-url · open-preview（由 viewer-token 控制访问，不公开；端口 7681 是 Web 终端） · list/get/delete-preview-url · touch-preview · bind/unbind-preview-url · resolve-preview-token
制品（二进制传输）	tenki_get_upload_url · tenki_get_download_url（用于二进制 PUT/GET 的签名 URL）
SSH	tenki_update_ssh_keys · tenki_issue_ssh_cert · tenki_list_ssh_gateways
快照	create · get · list · list-session · list-workspace · list-dangling · update · delete · get-download-url
卷	create · get · list · update · delete · resize · attach · detach
出站策略	create · get · list · update · delete（命名的工作区允许列表，tenki_create_sandbox 通过 egress_policies 固定使用）
模板	create · get · list · update · delete · build · cancel-build · get-build · list-active-builds · list-builds · delete-build
工作区	tenki_get_workspace_usage · tenki_list_ci_runner_sizes · tenki_get_workspace_preview_domains · tenki_update_workspace_preview_domains
每个版本的完整变更记录请见 CHANGELOG.md。

上游已弃用，但仍提供：tenki_expose_port / tenki_unexpose_port / tenki_list_exposed_ports（API 更推荐预览 URL 工具）、tenki_list_workspace_sandboxes / tenki_list_workspace_snapshots（建议使用按凭据范围限定的列表），以及 tenki_exec / tenki_run_code / tenki_move_path 背后的 ExecuteCommand RPC（后继方案是数据平面 Run 流，但该流需要本服务目前尚不具备的 HTTP/2 传输）。每次运行时，并行性审计都会列出这些项目。

身份验证

设置 LUXORAI_API_KEY 或 LUXORAI_AUTH_TOKEN 其中之一（仍接受 TENKI_API_KEY / TENKI_AUTH_TOKEN）。两者都设置时，优先使用身份验证令牌。根据令牌前缀选择请求头：lx_… 或 tk_… → Authorization: Bearer，ory_st_… → X-Session-Token，其他情况使用会话 Cookie。使用 LUXORAI_API_ENDPOINT 覆盖端点（默认为 https://api.tenki.cloud，与 https://api.luxor.ai 使用相同的 API）。

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

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

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

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

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

• 仅绑定到环回地址（127.0.0.1）：设置 LUXORAI_MCP_HTTP_HOST=0.0.0.0 可将其公开，但随后
• 必须使用 Bearer 令牌：设置 LUXORAI_MCP_HTTP_TOKEN，并发送 Authorization: Bearer <token>。如果主机不是环回地址且未设置令牌，服务将拒绝启动。
• 已启用 DNS 重绑定防护（Host 请求头允许列表），因此恶意网页无法驱动本地服务。

# expose to a network safely:
LUXORAI_MCP_TRANSPORT=http LUXORAI_MCP_HTTP_HOST=0.0.0.0 PORT=3000 \
  LUXORAI_MCP_HTTP_TOKEN=$(openssl rand -hex 32) LUXORAI_API_KEY=… npx -y @luxorai/mcp

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

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

工作原理

Luxor 的 API 使用 ConnectRPC：通过 HTTP/1.1 传输 JSON，而非 REST。每个控制平面调用都是 POST https://api.luxor.ai/tenki.sandbox.v1.SandboxService/{Method}，并附带 lowerCamelCase JSON 请求体。每个会话的文件 I/O 在创建时返回的独立数据平面端点上运行，并使用短期会话证书进行身份验证。本服务负责处理两种传输，因此这些工具只需一行命令即可使用。

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

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

安全

此服务持有 Luxor API 密钥，可以运行代码并消耗额度，因此请将其视为一项能力。完整的模型和 CSA MCP Server Top-10 映射见 SECURITY.md。快速控制措施：

• 最小权限： 每个工具都带有标题和 MCP 注释：读取工具使用 readOnlyHint，所有可能覆盖、修改、中断或删除现有状态的工具均使用 destructiveHint（只有创建、恢复、延长、附加或保持活动状态且不更改现有状态的工具才属于非破坏性工具）。设置 LUXORAI_MCP_READONLY=1 以运行仅供检查的服务（仅限读取工具），或设置 LUXORAI_MCP_DISABLED_TOOLS=tenki_run_code,… 以禁用指定工具。
• HTTP 传输 默认仅限环回地址；若要将其暴露到网络，必须使用 bearer token（参见通过 HTTP 托管）。
• 审计： LUXORAI_MCP_AUDIT=1 会将每次工具调用的名称记录到 stderr。
• 不可信输出： tenki_run_code/tenki_exec/tenki_read_file 会返回不可信代码的输出；客户端应将工具结果视为数据，而非指令。

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

相关项目

• Luxor Sandbox，该平台：https://luxor.ai
• n8n-nodes-tenki，将 Luxor Sandbox 作为 n8n 节点使用：https://github.com/opencolin/n8n-nodes-tenki

许可证

MIT