Heaper API Docs
These pages cover the supported ways to automate Heaper, connect an AI agent, or build a custom integration.
There is no separate "Agent API." Agents use the same supported surfaces as other integrations:
- MCP for typed tools in an MCP-compatible agent.
- CLI commands for shell-based agents, scripts, and terminal workflows.
- Server API for applications that need direct HTTP or WebSocket access.
- Client HTTP API for local automation through a running Heaper desktop app.
Pick the Right Surface
- Use Agent and MCP access when connecting Codex, ChatGPT desktop, Claude Desktop, or another MCP-compatible agent.
- Use the CLI for terminal-friendly access without writing HTTP calls.
- Use the Server API for a custom integration with a hosted or self-hosted Heaper server.
- Use the Client HTTP API for offline-capable automation of the Electron app on the same machine.
At a Glance
| Surface | Best for | Connection | Authentication |
|---|---|---|---|
MCP through heaper-cli | AI agents and desktop assistants | stdio to the CLI, then HTTPS or localhost HTTP | Saved remote login, environment credentials, or Local API token |
| CLI | Shell agents, scripts, and terminal workflows | HTTPS to a server or localhost HTTP to Electron | Same connection credentials as MCP |
| Server API | Remote integrations and custom clients | HTTPS and WebSocket | Server-issued bearer token |
| Client HTTP API | Local and offline-capable desktop automation | Localhost HTTP | Local API bearer token |
How Agent Access Connects
AI agent ──MCP over stdio──> heaper-cli ──HTTPS──> remote or self-hosted Heaper
└──localhost HTTP──> Electron Local API
Shell or script ──CLI commands──────────────┘
Custom integration ──HTTP or WebSocket──────────────────> Heaper server
MCP and normal CLI commands share authentication, server selection, token refresh, document operations, file transfer behavior, and capability checks. You can log in once with the CLI and reuse that connection from heaper mcp --stdio.