CLI, SSH and MCP

Agents use the same commands as tools, through Heaven's MCP server.

Overview

Each command the API serves is an MCP tool with the same fields. A tool is named after its command, with _ for spaces: create, pool_view, snapshot_create. A tool call runs exactly as its endpoint does, with the same permissions, limits and errors, and returns the endpoint's JSON.

Hosted clients

Add a custom connector with this address. The client sends you to Heaven to sign in and approve it. Then it acts as you, with every tool.

https://heaven.dev/mcp

Each approval is listed with your API keys under the client's name, and api-key remove disconnects it. Its access token lasts an hour. It refreshes for up to 30 days after its last use, and for at most a year in all. A refresh token works once, and sending it again ends the sign-in. Each approval counts as one of the 1,000 API keys you can hold.

With an API key instead

A client that takes a fixed header can use an API key. It sees only the tools whose commands the key names, plus feedback and command_view.

Authorization: Bearer heaven1.…

The hosted server doesn't accept tokens signed with an SSH key. Use heaven mcp for those.

Local clients

Install the heaven program, sign in once, and add it to your agents. It uses the program's sign-in, or HEAVEN_API_KEY when it's set. With neither, it uses your computer's SSH key.

curl -fsSL https://heaven.dev/install | sh
heaven login
heaven mcp install

heaven mcp install adds a server named heaven to each agent it finds on your computer: Claude Code, Codex, Gemini CLI, Claude Desktop, Cursor and VS Code. To choose agents, name them, as in heaven mcp install claude codex. Running it again replaces that server and changes nothing else. An agent that's already running picks it up when it next starts. For any other agent, add a stdio server whose command is heaven mcp. You don't run heaven mcp yourself; the agent starts it.

Through heaven mcp, file tools also take a local path of any size. A sign-in that expired or was revoked returns denied, with a message to run heaven login.

How tools behave

• Retries. Tools whose command takes an Idempotency-Key take request_id. If you leave it out, the server makes one and returns it. Calling again with it never acts twice.
• Waiting. A change waits for its operation, up to timeout, and returns it finished or still running. The hosted server waits 15s, which is also its limit. heaven mcp waits 1m by default, up to 10m. 0s returns at once. For an operation group, it waits on each Computer's operation in its results, and returns the group's state as it is after the wait. Read either later with operation_view.
• Files. exec takes command (with stdin), download, or upload (with content). Up to 1 MiB travels in the call, as text or with encoding: "base64". Larger files, and every export, return a one-time url to POST to within 15 minutes. If it's used again or later, it returns 410. A key can hold up to 100 unused links, and returns busy past that.
• Before you allow a tool. Tools that change nothing are marked read-only. Tools that can delete or replace something are marked destructive. Harmless changes, such as tag or start, aren't marked. A tool that can spend money says so in its first words. heaven mcp --read-only serves only the read-only tools, and --tools computers,snapshots serves only those groups, plus operation_view and feedback.
• Feedback. Agents can always call feedback to tell the Heaven team what got in their way. With a scoped key, they name one of its Computers.