Lizard MCP

Lizard MCP

An MCP server that lets ChatGPT, Claude and other MCP clients deploy and manage apps, run code in Lizard Sandboxes and work with Lizard Git repositories on Lizard (lizard.build).

Connect it once, then ask your assistant to ship a service, read logs, set secrets, scale replicas, attach a domain, run a script in a sandbox or open a pull request — in plain words.

Connect a client

The server speaks Streamable HTTP at POST /mcp, and stdio for clients that spawn a local process instead (below). A hosted instance runs at:

https://lizard.build/mcp

Every request carries a bearer token. A client that speaks OAuth gets one itself — the server advertises where, so there is nothing to paste. Clients that only send headers use a liz_ API key instead:

lizard keys create my-mcp-key

The dashboard creates the same thing under Sandboxes → Get started → New API key. Either way the key is shown once.

Claude Code

claude mcp add --transport http lizard https://lizard.build/mcp

Claude Code runs the OAuth flow on first use. To skip it and use a key:

claude mcp add --transport http lizard https://lizard.build/mcp \

--header "Authorization: Bearer liz_your_key"

Cline

Follow the Cline installation guide to connect the hosted server with a bearer token. Use Cline's streamableHttp transport, keep tool approval on, then check the connection with whoami. No local build is needed.

Cursor and other clients configured by JSON

{

"mcpServers": { "lizard": { "url": "https://lizard.build/mcp", "headers": { "Authorization": "Bearer liz_your_key" } } } }

ChatGPT

ChatGPT connects to a URL and runs OAuth itself — no key to paste. It needs developer mode and a registered connection; see Publishing to Codex / ChatGPT below.

Against a local server

Run it as described in the next section, then use http://localhost:3000/mcp in place of the hosted URL.

Check the connection

curl -sS -X POST https://lizard.build/mcp \

-H "Authorization: Bearer liz_your_key" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Without a token the same call returns 401 and a WWW-Authenticate header pointing at the OAuth metadata. That is the server working, not failing.

Run it

npm install

npm run build npm start

For development with reload:

npm run dev

Run it over stdio

npm start serves HTTP. To have a client spawn the server instead, point it at dist/stdio.js:

{

"mcpServers": { "lizard": { "command": "node", "args": ["/path/to/lizard-mcp/dist/stdio.js"], "env": { "LIZARD_TOKEN": "liz_your_key" } } } }

A spawned process has no browser to run OAuth in, so the token comes from the environment and binds the process to one user. Without it the server still starts and lists its tools — calling one then returns a message asking for a key.

Configuration

Sandboxes profile

The standalone HTTP server also serves /mcp/sandboxes. This profile includes sandbox creation, files, code execution, pause and resume, snapshots, forks and port access, plus account, project, region, limits and billing reads. It excludes CI, DNS, support, schedules and other platform tools. New tools stay out of this profile until its allowlist includes them. Excluded tools cannot be called by name.

Use the same server origin with /mcp/sandboxes as the client URL. It has its own OAuth resource metadata. /mcp and stdio still provide the full tool set. In-process hosts can select the same profile with getServer(token, { profile: "sandboxes" }); they must add the HTTP route and OAuth resource metadata themselves. Deploying this package alone does not add a route to an in-process host.

This profile needs a Lizard workspace and project with permission to use Sandboxes. It does not need CI access or an owned domain. Cloud usage still incurs charges. It can attach an existing volume by ID, but cannot list or create volumes.

Tools

Tool names use snake_case (not the MCP spec's permitted dots) to match OpenAI's function-name pattern ^[a-zA-Z0-9_-]{1,64}$, which some ChatGPT/Codex surfaces enforce directly.

Every tool includes a title in both title and annotations.title. Read tools set readOnlyHint: true; all write tools set destructiveHint: true so clients can ask before changing resources. Shell access to app services is unavailable, so the server exposes no service-shell tool. Use sandbox_exec to run commands in Lizard Sandboxes.

Destructive tools — project_delete, workspace_delete, service_delete, secrets_delete, domain_delete, volume_delete, sandbox_delete, sandbox_snapshot_delete, repo_delete, and domain_dns_update with remove — require an explicit confirmation argument, so a client cannot delete anything or run arbitrary commands by accident.

project_delete puts the project's services and databases in trash for 3 days, but deletes its sandboxes, their volumes and snapshots at once.

billing_status is read-only: it shows the plan (Pro at $19/month with $19 of usage included each month, Pro 5x at $99 with $99, Pro 20x at $499 with $499, the trial, prepaid credits until November 1, 2026, or enterprise), the tier and the Billing link. Starting, changing tier, paying for and cancelling Pro happen in the browser. When the account has to pay before it can create something, the tool error gives the platform's sentence with the page to open on its last line, and structuredContent.error carries the code (PAYMENT_REQUIRED), paymentStatus and the links.

What the Lizard CLI has and this server does not

test/parity/cli-coverage.json maps every Lizard CLI command to the tools that cover it, or says why none does. The main gaps, on purpose:

• lizard up and other commands that read local files: a remote server never sees them. Deploy from a GitHub or Lizard Git repo instead, or commit files with repo_commit.
• API keys (lizard keys), payments (lizard billing changes), agent credentials (lizard agents): they handle secrets or money and belong in the browser or a terminal.
• Lizard Git admin (webhooks, branch rules, collaborators, CI secrets and environments, releases, labels, issues): the Lizard CLI and Lizard SDK cover them.
• Interactive tools: sandbox shell, VNC and desktop streams, live log streams.

Bought domains: an API key can read their DNS records but not change them. Changes (domain_dns_update, domain_attach on a bought domain) need a client connected with OAuth.

Lizard Git

repo_*, pr_* and ci_* reach Lizard Git (lizard.build/git) with the caller's own token, as Authorization: Bearer. Lizard Git refuses API keys with scopes. Every commit is made on the server with repo_commit; there is no clone. To deploy a repository, call service_create with repoUrl set to lizard:owner/name. LIZARD_GIT_URL points the server at another Lizard Git (default /git).

Sandbox workflow

Lizard (lizard.build) provides Lizard Sandboxes for short-lived code execution. These resources are separate from app services. Start with project_list, then call sandbox_create with the chosen project and confirm: true. Keep the returned sandboxId for later calls.

{"name":"sandbox_create","arguments":{"project":"YOUR_PROJECT_ID","lifetimeMs":300000,"confirm":true}}

Use sandbox_write_file to write a script, sandbox_exec to run it, and sandbox_read_file to read its results. Finish with sandbox_delete. Create, execute, write, and delete need the user's approval before the client sets confirm: true. The MCP server does not open a confirmation dialog.

Sandboxes use the interpreter template and size small unless template and size say otherwise, with /workspace as the default path. Sizes are mini (1 vCPU / 2 GB; only the base, claude, codex and interpreter templates, no volume), small (2 vCPU / 4 GB), medium (4 vCPU / 8 GB) and large (8 vCPU / 16 GB). The trial runs 1 Small and 2 Mini at a time (US regions only); Medium and Large unlock after the first payment. They expire after five minutes by default; lifetimeMs accepts 60,000–86,400,000 milliseconds (a day), and sandbox_set_timeout changes it later. On the trial a sandbox lives 1 hour at most, then it is deleted: a longer lifetime fails with TRIAL_SANDBOX_LIFETIME, and sandbox_set_timeout cannot extend it past 1 hour from its creation. Expiry or deletion loses all files except those on an attached volume. Creation uses billed cloud resources. Host files, environment variables, and access tokens stay out of the sandbox.

sandbox_pause saves memory, processes and files and stops the sandbox; sandbox_resume continues it. sandbox_snapshot saves a running sandbox to start new ones from in the same project (sandbox_create with snapshotId), and sandbox_fork starts live copies. sandbox_expose_port gives a port an HTTPS URL that carries its access token (other clients send it as X-Lizard-Access-Token). Pause, resume and snapshot wait up to two minutes for the platfor