Skip to main content
Glama
README.md
# Luxor MCP: `@luxorai/mcp`

**A [Model Context Protocol](https://modelcontextprotocol.io) server for [Luxor Sandbox](https://luxor.ai), 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.

```
"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
```

## Quickstart

```bash
export LUXOR_API_KEY=lx_your_key_here
npx -y @luxorai/mcp     # speaks MCP over stdio
```

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:

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

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:

```bash
claude mcp add luxor --env LUXOR_API_KEY=lx_your_key_here -- npx -y @luxorai/mcp
```

### 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:

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

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`:

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

### Use it in Cursor

Add the same block to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

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

### Use it in Codex

The OpenAI Codex CLI reads MCP servers from `~/.codex/config.toml`. Add:

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

### 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](#auth).

### Run it from a clone instead

For development, or to run an unreleased change:

```bash
git clone https://github.com/LuxorLabs/tenki-mcp.git && cd tenki-mcp
npm install && npm run build
LUXOR_API_KEY=lx_your_key_here node dist/index.js
```

Substitute `node /absolute/path/to/tenki-mcp/dist/index.js` for the `npx` command in any of the configs above. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development loop.

### Environment variables

| Variable                           | Default                                                            | Purpose                                                                                                                                                                                                   |
| ---------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LUXOR_API_KEY`                    | -                                                                  | API key (`lx_…`, or `tk_…`). One of this or `LUXOR_AUTH_TOKEN` is required.                                                                                                                               |
| `LUXOR_AUTH_TOKEN`                 | -                                                                  | Session token (`ory_st_…` or cookie value). **Takes precedence over `LUXOR_API_KEY`** when both are set.                                                                                                  |
| `LUXOR_API_ENDPOINT`               | `https://api.luxor.ai` (the same API as `https://api.tenki.cloud`) | Control-plane base URL (`LUXOR_API_URL` is an alias).                                                                                                                                                     |
| `LUXOR_MCP_READONLY`               | off                                                                | `1` registers only read tools (no create/run/delete/spend).                                                                                                                                               |
| `LUXOR_MCP_DISABLED_TOOLS`         | -                                                                  | Comma-separated tool names to skip registering.                                                                                                                                                           |
| `LUXOR_MCP_AUDIT`                  | off                                                                | `1` logs each tool call name + arg keys to stderr.                                                                                                                                                        |
| `LUXOR_MCP_TOOL_PREFIX`            | `tenki`                                                            | `luxor` names every tool `luxor_*` instead of `tenki_*` (the `luxor` Claude Code plugin sets it). Descriptions and errors use the same names.                                                             |
| `LUXOR_MCP_TRANSPORT`              | `stdio`                                                            | `http` serves Streamable HTTP instead (see below).                                                                                                                                                        |
| `PORT`                             | `3000`                                                             | HTTP transport port.                                                                                                                                                                                      |
| `LUXOR_MCP_HTTP_HOST`              | `127.0.0.1`                                                        | HTTP bind host; non-loopback requires `LUXOR_MCP_HTTP_TOKEN`.                                                                                                                                             |
| `LUXOR_MCP_HTTP_TOKEN`             | -                                                                  | Bearer token for the HTTP endpoint; optional on loopback, required on a non-loopback host.                                                                                                                |
| `LUXOR_MCP_PUBLIC_URL`             | -                                                                  | Public base URL for an OAuth-protected hosted server.                                                                                                                                                     |
| `LUXOR_MCP_OAUTH_ISSUER`           | -                                                                  | OAuth authorization-server issuer. Enables delegated OAuth HTTP mode.                                                                                                                                     |
| `LUXOR_MCP_OAUTH_RESOURCE`         | `<public URL>/mcp`                                                 | RFC 8707 resource identifier accepted in access-token audiences. A comma-separated list serves one resource per domain; metadata and the 401 `resource_metadata` follow the request host, else the first. |
| `LUXOR_MCP_OAUTH_SCOPE`            | `mcp`                                                              | Required delegated scope.                                                                                                                                                                                 |
| `LUXOR_MCP_RESOURCE_NAME`          | `Luxor MCP`                                                        | `resource_name` in the protected-resource metadata.                                                                                                                                                       |
| `LUXOR_MCP_IDENTITY_URL`           | -                                                                  | Internal Luxor Identity service endpoint used to exchange OAuth access tokens.                                                                                                                            |
| `LUXOR_MCP_IDENTITY_SERVICE_TOKEN` | -                                                                  | Service credential for the private Identity token-exchange RPC.                                                                                                                                           |

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](scripts/parity-audit.mjs), 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:

| Domain                          | Tools                                                                                                                                                                                                                                 |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Auth**                        | `tenki_auth_status` (which credential is configured, and does it work; the only tool available when none is)                                                                                                                          |
| **Identity**                    | `tenki_whoami`                                                                                                                                                                                                                        |
| **Run**                         | `tenki_run_code` (one-shot: boot → run shell/python/js → tear down)                                                                                                                                                                   |
| **Sandboxes**                   | `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` (copies of a running sandbox) |
| **Session admin**               | `tenki_extend_sandbox` · `tenki_update_sandbox` · `tenki_terminate_sandboxes` (bulk) · `tenki_report_sandbox_activity` · `tenki_list_workspace_sandboxes`                                                                             |
| **Exec**                        | `tenki_exec` (stdout/stderr/exit inline)                                                                                                                                                                                              |
| **Files**                       | `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` (the four operations the API supports; pass `directory` to target a cloned repo; run other git commands via `tenki_exec`)                               |
| **Ports & previews**            | expose · list-exposed · unexpose · create-preview-url · open-preview (viewer-token-gated, not public; port 7681 is the web terminal) · list/get/delete-preview-url · touch-preview · bind/unbind-preview-url · resolve-preview-token  |
| **Artifacts** (binary transfer) | `tenki_get_upload_url` · `tenki_get_download_url` (signed URLs for binary PUT/GET)                                                                                                                                                    |
| **SSH**                         | `tenki_update_ssh_keys` · `tenki_issue_ssh_cert` · `tenki_list_ssh_gateways`                                                                                                                                                          |
| **Snapshots**                   | create · get · list · list-session · list-workspace · list-dangling · update · delete · get-download-url                                                                                                                              |
| **Volumes**                     | create · get · list · update · delete · resize · attach · detach                                                                                                                                                                      |
| **Egress policies**             | create · get · list · update · delete (named workspace allowlists that `tenki_create_sandbox` pins via `egress_policies`)                                                                                                             |
| **Templates**                   | create · get · list · update · delete · build · cancel-build · get-build · list-active-builds · list-builds · delete-build                                                                                                            |
| **Workspace**                   | `tenki_get_workspace_usage` · `tenki_list_ci_runner_sizes` · `tenki_get_workspace_preview_domains` · `tenki_update_workspace_preview_domains`                                                                                         |

Full per-release breakdown in [CHANGELOG.md](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:

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

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.

```bash
# expose to a network safely:
LUXOR_MCP_TRANSPORT=http LUXOR_MCP_HTTP_HOST=0.0.0.0 PORT=3000 \
  LUXOR_MCP_HTTP_TOKEN=$(openssl rand -hex 32) LUXOR_API_KEY=… npx -y @luxorai/mcp
```

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](https://github.com/opencolin/n8n-nodes-tenki).

## 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](https://modelcontextprotocol-security.io/top10/server/) mapping in **[SECURITY.md](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](#host-it-over-http-v20-beta)).
- **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](https://github.com/LuxorLabs/tenki-mcp/security/advisories/new), not a public issue.

## Related

- **Luxor Sandbox**, the platform: https://luxor.ai
- **n8n-nodes-tenki**, Luxor Sandbox as an n8n node: https://github.com/opencolin/n8n-nodes-tenki

## License

MIT

TDQS

A3.5/5.0

Scored across 71 tools

Disambiguation2/5

Multiple tools overlap significantly: tenki_list_sandboxes and tenki_list_workspace_sandboxes have nearly identical purposes, several snapshot listing variants coexist, and deprecated retention-settings tools duplicate workspace-settings tools. Descriptions often clarify when to use what, but the boundary between run_code and create_sandbox+exec, git and exec, and open_preview versus expose_port/create_preview_url still creates real selection risk.

Naming Consistency5/5

Every tool uses the tenki_ prefix with a clear verb_noun pattern: create/get/list/update/delete for resources, plus exec/read/write/move for file operations and expose/unexpose for ports. Singular get_ versus plural list_ conventions are consistent, making the API predictable despite its size.

Tool Count1/5

71 tools is far beyond a well-scoped MCP surface and hits the extreme end of the calibration scale. Even accounting for a broad sandbox-management domain, the count is bloated by near-duplicate list/retrieval variants and deprecated endpoints that could be consolidated.

Completeness5/5

The domain is very thoroughly covered: full sandbox lifecycle, file operations, execution, preview URLs, snapshots, volumes, templates, SSH access, workspace settings, usage billing, and auth diagnostics. There are no obvious dead ends or missing core operations for managing sandboxes and their related resources.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues