Agent and MCP Access

The heaper-cli npm package includes a typed MCP server. It lets an MCP-compatible agent work with heaps, blocks, documents, relations, properties, history, files, and invites without implementing the Heaper HTTP APIs itself.

MCP is an agent-facing layer over the same connections used by normal CLI commands. It is not a separate data service or a separate Agent API.

Choose a Connection

The local stdio MCP server is intended for desktop agents. Browser-hosted agents cannot launch it directly and require a separately hosted HTTPS MCP endpoint.

Install and Log In

Install the CLI:

npm install -g heaper-cli
heaper --version

Log in to a hosted or self-hosted server with an agent identity:

heaper auth login https://your-heaper.example \
  --agent codex \
  --insecure-save-key

heaper auth status
heaper heaps

This creates or reuses an Ed25519 agent identity, completes the server challenge, and saves the selected server and refreshable session locally.

--insecure-save-key stores the reusable private key in ~/.heaper/cli/identities/<agent>.json with 0600 permissions. Omit that option for stricter environments and provide HEAPER_AGENT_PRIVATE_KEY to the process instead.

Configure an MCP Client

For a client that accepts an mcpServers JSON configuration:

{
  "mcpServers": {
    "heaper": {
      "command": "heaper",
      "args": [
        "--server",
        "https://your-heaper.example",
        "mcp",
        "--stdio"
      ]
    }
  }
}

Restart the agent after changing its MCP configuration. If the correct saved server is already the default, the shorter argument list also works:

{
  "command": "heaper",
  "args": ["mcp", "--stdio"]
}

Put global options such as --server, --port, and --token before mcp.

Codex Plugin From a Repository Checkout

This repository also contains a Codex plugin that starts the same MCP server:

codex plugin marketplace add /absolute/path/to/heaper
codex plugin add heaper@personal

Install heaper-cli first, then restart Codex so the desktop process receives the updated PATH.

Authentication Options

The CLI selects an active connection in this order:

1. Explicit --server <url-or-public-key>.
2. HEAPER_SERVER_URL with remote environment credentials.
3. Stored credentials created by heaper auth login.
4. Electron Local API discovery through ~/.heaper/api.json.

For a non-interactive remote agent:

export HEAPER_SERVER_URL="https://your-heaper.example"
export HEAPER_ACCESS_TOKEN="..."
export HEAPER_REFRESH_TOKEN="..."

heaper mcp --stdio

Do not commit bearer tokens or private keys to agent configuration, plugin manifests, or repository files. Supply them through the agent application's environment configuration.

For local Electron access, enable Settings → Local API in the desktop app. Set HEAPER_TOKEN when Local API authentication is enabled. Use --port only when discovery through ~/.heaper/api.json is unavailable.

Capabilities by Connection

Use the MCP connection_status tool to inspect the active mode, apiContractVersion, and available capabilities.

Remote block reads intentionally omit raw YDocument and encrypted-blob fields. Use get_document for structured collaborative content and list_files for file metadata.

Safe Agent Writes

Document writes use structured operations instead of replacing Markdown blindly:

1. Call get_document.
2. Copy the returned document hash.
3. Pass it as base_hash to patch_document.
4. Fetch the document again if the hash no longer matches.

Full document replacement is more destructive and additionally requires confirm_rebuild=true. File tools require explicit local paths, and downloads do not overwrite existing files unless explicitly allowed.

For Codex, keep the plugin's default approval mode on prompt. Pre-approve read tools only if desired, while document mutations, relation changes, property changes, uploads, and filesystem writes continue to require approval.

Troubleshooting

• heaper is not found: install the package globally and restart the agent so it receives the updated PATH.
• No active connection: run heaper auth status, log in to a remote server, or start Electron with the Local API enabled.
• Wrong server selected: run heaper auth servers, then pass --server <url-or-public-key> before mcp.
• A capability is unsupported: call connection_status; remote SQL and Electron-local uploads are intentionally unavailable.
• MCP protocol parse errors: avoid shell wrappers that print banners to stdout because stdout is reserved for MCP protocol messages.

Related Documentation

• Heaper CLI
• CLI Reference
• Server API
• Client HTTP API