Luxor MCP: @luxorai/mcp
A Model Context Protocol server for Luxor Sandbox, part of Luxor Agent Cloud by Luxor AI. Give any agent (Claude, Codex, Cursor) a disposable microVM it can create, run code in, read and write files, run git, and expose to the web. Sandboxes boot in ~2 seconds and are billed per second.
The agent writes code and Luxor runs it in isolation. (Luxor Code Review and Luxor's managed CI runners are separate products; this server currently exposes the Sandbox.)
The old @tenkicloud/mcp name keeps working and publishes the same code.
Quickstart
Nothing to clone or build. The package installs the command luxor-mcp (and tenki-mcp, the same program).
Use it in Claude Code
Connect to Luxor's hosted MCP service and sign in with your Luxor account:
Claude Code's mcp add command stores the server configuration; mcp login performs the one-time browser authorization and workspace selection.
Alternatively, run the MCP server locally with an API key:
Or install it as a Claude Code plugin
The repo doubles as a plugin marketplace. This prompts for your API key on install and stores it in your OS keychain, so there is no env var to manage:
If you added this marketplace before it was named luxor, your installs keep working as luxor@tenki and tenki@tenki. To switch to the new name, run /plugin marketplace remove tenki (this uninstalls its plugins and their saved API key), then add the marketplace again.
The luxor plugin names its tools luxor_*; the legacy tenki plugin keeps tenki_*.
Use it in Claude Desktop
Add to claude_desktop_config.json:
Use it in Cursor
Add the same block to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):
Use it in Codex
The OpenAI Codex CLI reads MCP servers from ~/.codex/config.toml. Add:
Confirm it's working
After adding the server, start a fresh session so the client loads it, then ask your agent one of:
- "Check Luxor auth status.": confirms your credential was picked up.
- "Run
print(2+2) in a fresh Luxor sandbox.": a full boot → run → teardown round-trip.
If the tools don't show up, restart the client so it re-reads its config.
No key yet? Start the server without one and ask the agent to check tenki_auth_status; it reports what to set and where. See Auth.
Run it from a clone instead
For development, or to run an unreleased change:
Substitute node /absolute/path/to/tenki-mcp/dist/index.js for the npx command in any of the configs above. See CONTRIBUTING.md for the full development loop.
Environment variables
Every LUXOR_* variable above is still accepted under its TENKI_* name (for example TENKI_API_KEY, TENKI_MCP_TRANSPORT). All LUXOR_* credentials are read before any TENKI_* one. Keys start with lx_; tk_… keys are still accepted. LUXOR_API_KEY is only used when it starts with lx_ or tk_; any other value is ignored.
Tools
82 tools: all 76 tool-worthy public unary API methods (enforced by a CI parity audit, which also fails if a tool calls a method the API no longer has; GitOperation is exposed as one tool per operation), two workflow helpers, and tenki_auth_status. Tool names use the tenki_ prefix by default; set LUXOR_MCP_TOOL_PREFIX=luxor (as the luxor plugin does) to name them luxor_*. A few admin surfaces (published images, saved Tailscale connections) and implementation-only control-plane methods are intentionally excluded. Grouped by domain:
Full per-release breakdown in CHANGELOG.md.
Deprecated upstream, still served: tenki_expose_port / tenki_unexpose_port / tenki_list_exposed_ports (the API prefers the preview-URL tools), tenki_list_workspace_sandboxes / tenki_list_workspace_snapshots (prefer the credential-scoped lists), and the ExecuteCommand RPC behind tenki_exec / tenki_run_code / tenki_move_path (successor is the data-plane Run stream, which needs an HTTP/2 transport this server does not have yet). The parity audit prints these on every run.
Auth
Set one of LUXOR_API_KEY or LUXOR_AUTH_TOKEN (TENKI_API_KEY / TENKI_AUTH_TOKEN are still accepted). When both are set, the auth token wins. The header is chosen by token prefix: lx_… or tk_… → Authorization: Bearer, ory_st_… → X-Session-Token, otherwise a session cookie. Override the endpoint with LUXOR_API_ENDPOINT (default https://api.luxor.ai, the same API as https://api.tenki.cloud).
Without a credential the server still starts, registering only tenki_auth_status, so instead of an MCP client reporting an opaque "server failed to start", the agent can call that tool and get told what to set. Ask it "check Luxor auth status" any time other tools return auth errors: it reports the credential kind (API key vs session token), the endpoint, and whether a live identity probe succeeded, never the token itself. It reports status only; get a credential from the Luxor dashboard.
Host it over HTTP (v2.0-beta)
Besides stdio, the server speaks Streamable HTTP so it can be hosted for remote MCP clients:
For a single-user deployment, HTTP mode can hold one shared LUXOR_API_KEY and therefore exposes a powerful capability. By default it:
- binds to loopback (
127.0.0.1) only: set LUXOR_MCP_HTTP_HOST=0.0.0.0 to expose it, but then
- it requires a bearer token: set
LUXOR_MCP_HTTP_TOKEN and send Authorization: Bearer <token>. It refuses to start on a non-loopback host without one.
- DNS-rebinding protection is on (Host-header allowlist), so a malicious web page can't drive your local server.
Point an HTTP-capable MCP client at /mcp. Static-key mode uses one shared LUXOR_API_KEY for all sessions. Verified end-to-end (test/http-transport.test.mjs: auth gate, DNS-rebinding rejection, connect → tools/list → tool call over HTTP).
Hosted multi-tenant deployments instead use Luxor Identity's OAuth facade. The MCP server publishes RFC 9728 protected-resource metadata and exchanges each caller's access token through the private Identity service. Identity owns Hydra, validates the requested audience and scope, and issues a short-lived API delegation bound to the user, client, and workspace selected on the Luxor consent page. tenki-mcp has no Hydra Admin access and does not hold the delegation-signing secret.
How it works
Luxor's API is ConnectRPC: JSON over HTTP/1.1, not REST. Every control-plane call is POST https://api.luxor.ai/tenki.sandbox.v1.SandboxService/{Method} with a lowerCamelCase JSON body. Per-session file I/O runs on a separate data-plane endpoint returned at create time, authenticated with a short-lived session certificate. This server owns both transports so the tools stay one-liners.
Command output: tenki_exec and tenki_run_code capture stdout/stderr by redirecting to files (sh -c '… > out 2> err') and reading them back over the data plane, so you get the output inline through a plain HTTP client.
The wire details are ported from the live-verified n8n community node.
Security
This server holds a Luxor API key and can run code + spend credits, so treat it as a capability. Full model + CSA MCP Server Top-10 mapping in SECURITY.md. Quick controls:
- Least privilege: every tool carries a title and MCP annotations:
readOnlyHint on reads, and destructiveHint on every tool that can overwrite, modify, interrupt or delete existing state (only tools that create, resume, extend, attach or keep alive without changing existing state are non-destructive). Run LUXOR_MCP_READONLY=1 for an inspection-only server (read tools only), or LUXOR_MCP_DISABLED_TOOLS=tenki_run_code,… to drop specific tools.
- HTTP transport is loopback-only by default and requires a bearer token to expose to a network (see Host it over HTTP).
- Audit:
LUXOR_MCP_AUDIT=1 logs each tool call's name to stderr.
- Untrusted output:
tenki_run_code/tenki_exec/tenki_read_file return output from untrusted code; clients should treat tool results as data, not instructions.
Report vulnerabilities via a private security advisory, not a public issue.
Related
License
MIT