Heavenly MCP

Introduction

The Heavenly MCP server gives an assistant a safe window into your workspace. It can list projects, read timelines, prepare edits, and return a proposal for your review. Saving an edit or publishing a post always requires the permission you granted.

Base URL:

https://lenslab.dev/api/heavenly-mcp

MCP carries project metadata and commands; it does not return original media files to the client. Editing source footage stays on your device unless you ask Heavenly to analyze it, export it, or publish a finished file.

Quickstart

Three steps: connect, list tools, then ask Heavenly to work on a project.

1. Connect your client

Paste the URL into an OAuth-capable client, or create a scoped token from Heavenly settings for a terminal client.

2. List tools

curl --fail-with-body --silent --show-error 'https://lenslab.dev/api/heavenly-mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

3. Ask Heavenly

Try “List my Heavenly projects.” Review every proposed edit before it is saved; publishing remains a separate, permissioned action.

Authentication

OAuth is the default for hosted clients. Claude Code and compatible terminal clients use a scoped, revocable token. Never paste a Heavenly password into an MCP client.

claude mcp add --transport http heavenly https://lenslab.dev/api/heavenly-mcp \
  --header "Authorization: Bearer hv_pat_YOUR_TOKEN"

Tokens are scoped to the workspace and can be revoked without changing your password.

Rate limits & plans

The MCP connection follows the limits of your Heavenly workspace. Requests over the burst cap receive HTTP 429 with a retry hint. Your media plan controls editing and export access; connecting a client does not create a second subscription.

Errors

Errors use JSON-RPC with a stable code and a human-readable message. A revoked token returns an authentication challenge; a missing scope identifies the permission needed.

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": { "code": -32000, "message": "missing_scope" }
}

Clipping

Ask Heavenly to find moments, trim a sequence, split clips, set an aspect ratio, or prepare a short-form cut. The assistant returns a proposal with the affected clips before anything changes.

Use the project timeline as the source of truth. An unsuccessful operation is not saved.

Captions

Caption generation and corrections stay attached to the project timeline. Ask for a preset, text correction, or timing change, then preview before applying it.

Motion designs

Create a motion design from a prompt, refine it in follow-ups, and check its job status. These tools create and inspect motion-design jobs; they do not create recurring schedules or automations.

Scheduling

Scheduling tools read connected accounts and prepare posts for review. Publishing is always a separate action, so a draft cannot silently become a live post.

Credits

Credit and plan information is read-only from MCP. The assistant cannot purchase a plan, change billing, or move credits between workspaces.

MCP server

Streamable HTTP is available at https://lenslab.dev/api/heavenly-mcp. It is the connection layer for Heavenly, not a second editor. Connect once, then use the workspace directly.

Need help connecting? Open the interactive MCP setup for client-specific instructions.

Changelog

MCP is versioned with the Heavenly workspace. New tools are additive; existing tools keep their permission checks and approval boundary.

• Streamable HTTP and OAuth are available for hosted clients.
• Scoped tokens are available for terminal clients.
• Publishing remains opt-in and approval-gated.