@leap0/mcp

Model Context Protocol (MCP) server for Leap0, built on the leap0 JavaScript SDK. It exposes sandbox lifecycle, filesystem, and process tools over stdio so clients such as Cursor or Claude can manage Leap0 sandboxes.

Requirements

• Node.js 20.6 or newer
• A Leap0 API key (and network access to the Leap0 API)

Install

npm install -g @leap0/mcp
# or
pnpm add -g @leap0/mcp

For one-off runs without a global install:

npx @leap0/mcp --help

From a clone of this repo, after pnpm install and pnpm run build:

node dist/cli.js --help

Environment variables

The server uses the same variables as the leap0 SDK (see also Leap0Client in the SDK docs).

| Variable | Required | Description | |----------|----------|-------------| | LEAP0_API_KEY | Yes | API key for the Leap0 control plane | | LEAP0_BASE_URL | No | API base URL (SDK default applies if unset) | | LEAP0_SANDBOX_DOMAIN | No | Sandbox hostname domain (SDK default applies if unset) | | LEAP0_SDK_OTEL_ENABLED | No | SDK OpenTelemetry toggle (see leap0 SDK) |

Run on the host (not only inside an agent sandbox)

The MCP process must be able to reach the Leap0 API and should have your credentials in its environment. If your coding agent runs in an isolated container without secrets, configure MCP on the host (or inject LEAP0_API_KEY into the environment where leap0-mcp runs). Running only inside a restricted sandbox with no outbound API access will fail at client creation or on the first tool call.

Agent configuration

Generate a JSON snippet you can merge into your client’s MCP settings:

leap0-mcp --print-config

This prints a mcpServers block using your current node binary and the resolved path to this package’s cli.js. Placeholders use ${VAR} so you can rely on the shell or replace them with real values.

1. Copy the JSON into your app’s MCP config (e.g. Cursor Settings → MCP).
2. Ensure LEAP0_API_KEY is set in the server env (or remove the placeholder and set it in your user environment before starting the agent).
3. Remove or set optional entries (LEAP0_BASE_URL, LEAP0_SANDBOX_DOMAIN) if you use non-default endpoints.
4. Restart the editor or MCP host.

On Windows, the printed config includes APPDATA in env (similar to other MCP servers) so tools resolve user paths correctly.

Cursor

Paste the mcpServers object from --print-config into your Cursor MCP configuration, or merge it with existing mcpServers keys. The server name key is leap0-mcp.

Claude Desktop

Add the same mcpServers entry under Claude’s MCP configuration file for your platform (see Anthropic’s MCP documentation for the exact path).

CLI

| Flag | Meaning | |------|---------| | (none) | Start the MCP server on stdio (JSON-RPC on stdout only) | | --print-config | Print MCP JSON config to stdout | | --version / -V | Print package version | | --help / -h | Print usage |

Diagnostics and errors go to stderr; MCP traffic uses stdout.

Tools (summary)

Requires leap0 0.5.x (sandbox memory / disk / timeout fields, list API, and public URL helpers align with that release).

| Tool | Purpose | |------|---------| | leap0_sandboxes_create | Create a sandbox (memory in MiB, timeout in seconds) | | leap0_sandbox_get | Get sandbox by id | | leap0_sandbox_get_workdir | Configured sandbox working directory (getWorkdir) | | leap0_sandbox_delete | Delete sandbox | | leap0_sandboxes_list | List sandboxes (filters / pagination) | | leap0_sandbox_invoke_url | Public HTTPS URL for a path (and optional port) | | leap0_sandbox_websocket_url | Public WebSocket URL for a path | | leap0_sandbox_create_presigned_url | Time-limited public URL for a sandbox port | | leap0_fs_read / leap0_fs_write / leap0_fs_list | Files in a sandbox | | leap0_process_execute | Run a command in a sandbox |

Upgrading

1. Match the leap0 SDK version this MCP package declares (see dependencies in package.json); run pnpm update leap0 in a checkout or reinstall the published package so node_modules resolves to that range.
2. Rebuild after dependency changes: pnpm run build (or pnpm run ci before merging).
3. Restart the editor or MCP host so it spawns a fresh leap0-mcp process.

Troubleshooting

• Failed to create Leap0 client / API key errors — Set LEAP0_API_KEY in the MCP env or in the process environment before launching leap0-mcp.
• 401 / 403 from tools — Key invalid or missing; confirm the key in the Leap0 dashboard and that the same env is visible to the MCP process.
• Connection / timeout errors — Check LEAP0_BASE_URL, firewall, and that the machine running MCP can reach the API (not blocked in a no-network sandbox).
• Empty or wrong PATH in --print-config — The printed PATH is taken from the shell that ran the command; adjust in the MCP config if node or other binaries are not found when the editor spawns the server.

Development

pnpm install
pnpm run ci    # build, typecheck, and Vitest (use in CI pipelines)
pnpm test      # build + Vitest

License

Apache-2.0