# MCP

Source: https://heaven.dev/docs/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.

| Server | For | Signs in with |
| --- | --- | --- |
| `https://heaven.dev/mcp` | Hosted clients, such as Claude.ai | OAuth in the browser, or an API key header |
| `heaven mcp` | Clients on your own computer, such as Claude Code | The `heaven` program's sign-in or `HEAVEN_API_KEY`, or else your SSH key |

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

Server URL:

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

Header:

```
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](https://heaven.dev/docs/cli#login), or `HEAVEN_API_KEY` when it's set. With neither, it uses your computer's SSH key.

```sh
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](https://heaven.dev/docs/operations#groups), 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.