tenki-mcp — @tenkicloud/mcp

A Model Context Protocol server for Tenki Cloud. 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.

Part of making Tenki the execution layer coding agents reach for: the agent writes code and Tenki runs it in isolation. (Tenki's Code Reviewer and Runners — AI PR review and managed CI — are separate products; this server currently exposes the 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

Quickstart

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

Nothing to clone or build. The package installs one command, tenki-mcp.

Use it in Claude Code

claude mcp add tenki --env TENKI_API_KEY=tk_your_key_here -- npx -y @tenkicloud/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 — no env var to manage:

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

Use it in Claude Desktop

Add to claude_desktop_config.json:

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

Use it in Cursor

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

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

Use it in Codex

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

[mcp_servers.tenki]
command = "npx"
args = ["-y", "@tenkicloud/mcp"]
env = { TENKI_API_KEY = "tk_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 tenki auth status." — confirms your credential was picked up.
• "Run print(2+2) in a fresh Tenki sandbox." — a full boot → run → teardown round-trip.

If the tenki_* 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:

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

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

Tools

71 tools — all 68 public unary API methods (enforced by a CI parity audit), two workflow helpers, and tenki_auth_status. Implementation-only control-plane methods are intentionally excluded. Grouped by domain:

Full per-release breakdown in CHANGELOG.md.

Auth

Set one of TENKI_API_KEY or TENKI_AUTH_TOKEN — when both are set, TENKI_AUTH_TOKEN wins. The header is chosen by token prefix: tk_… → Authorization: Bearer, ory_st_… → X-Session-Token, otherwise a session cookie. Override the endpoint with TENKI_API_ENDPOINT (default 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 tenki 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 with tenki login or from the dashboard.

Host it over HTTP (v2.0-beta)

Besides stdio, the server speaks Streamable HTTP so it can be hosted for remote MCP clients:

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]

Security — this endpoint is a capability. In HTTP mode the process holds one shared TENKI_API_KEY and exposes every tool, including arbitrary code execution and credit spend. So by default it:

• binds to loopback (127.0.0.1) only — set TENKI_MCP_HTTP_HOST=0.0.0.0 to expose it, but then
• it requires a bearer token: set TENKI_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.

# 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

Point an HTTP-capable MCP client at /mcp. v2.0-beta uses one shared TENKI_API_KEY for all sessions; per-request auth (multi-tenant hosting) is not yet implemented. Verified end-to-end (test/http-transport.test.mjs: auth gate, DNS-rebinding rejection, connect → tools/list → tool call over HTTP).

How it works

Tenki's API is ConnectRPC — JSON over HTTP/1.1, not REST. Every control-plane call is POST https://api.tenki.cloud/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 Tenki 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:

Read the full README on GitHub →