Lumiqa
4 steps · about 2 minutes · no JSON wrangling

Connect Claude
to Lumiqa.

A complete walkthrough for Claude Desktop and Claude Code. Install the app, run one command, and your AI agent gets first-class video review tools — upload, comment, approve, deliver — via MCP.

1

What is MCP, and why does Lumiqa use it?

MCP — Model Context Protocol — is Anthropic's open standard for letting AI agents call external tools. Think of it like USB-C for LLMs: one connector, every tool supported. Lumiqa is built MCP-first, which means a single claude mcp add command gives Claude the ability to upload, review, approve, and deliver your videos — programmatically, no GUI required.

The alternative is glue code: SDKs, webhooks, custom CLIs. With MCP you skip all of it. Once connected, Claude sees Lumiqa's tools the same way it sees its own native ones — and you talk to your agent in plain English.

Deeper read: Our blog post Why MCP matters (and why most SaaS will need it) covers the architecture and why this is more than a fad. About a 7-minute read.
Before MCP vs. after MCP
Before: "Write Python that uploads to Lumiqa, parse the response, handle retries, run it from a cron, hope nothing changes." → 200 lines of code.
After: "Upload this final cut, ask the team to review, ping me when approved." → 1 sentence.
2

Install Claude Desktop or Claude Code

If you haven't already, download the app you want to use. Both speak MCP natively — the setup is identical except for one config detail (we'll cover both).

Claude Desktop
The chat app — best for natural conversation with your agent. Anthropic's official download is at claude.ai/download. Available for macOS and Windows. Free with any Claude account.
Claude Code
The terminal coding agent — best for builders, scripts, and full automation flows. Install via npm install -g @anthropic-ai/claude-code or follow the guide at docs.anthropic.com/claude-code.

Both apps ship the claude mcp CLI. Open Claude Desktop's "Developer Settings" pane (or just open a terminal for Claude Code) and you're ready for the next step.

3

Connect Lumiqa

You'll need two things: your workspace slug (e.g. acme-studio) and your API key (it starts with lk_live_). Both are shown the moment you create your first workspace on Lumiqa — and the API key is also surfaced on the post-signup screen, exactly once.

Haven't signed up yet? Create a free developer workspace — no credit card, 100 uploads/month, MCP + REST API.

Paste this in your terminal. Replace YOUR-SLUG and YOUR-KEY with the values from your Lumiqa workspace.

claude mcp add lumiqa \
  --url https://lumiqa.io/mcp/YOUR-SLUG \
  --header "Authorization: Bearer YOUR-KEY"

Claude will register the server, restart, and Lumiqa's tools will appear in the model's available toolset. You should see something like this:

~/projects · claude mcp add
# Adding MCP server "lumiqa" $ claude mcp add lumiqa --url https://lumiqa.io/mcp/acme-studio \ --header "Authorization: Bearer lk_live_••••••••••••" ✓ MCP server "lumiqa" registered ✓ Loaded 13 tools: list_content, get_content, approve_content, request_changes, list_calendar, upload_video, list_comments, add_comment, set_status, save_memory, recall_memory, list_workflow_templates, run_workflow ✓ Connection healthy. Ready to use in Claude Desktop.
Heads up — security. The API key in this command is your bearer credential. Never paste it into a public chat, repo, Loom, or screenshot. Lumiqa stores only a SHA-256 hash; if you ever lose track of who has it, revoke and regenerate from your dashboard → Settings → API Keys.

If you prefer to edit the config file directly (handy for sharing setups across machines or version-controlling them), here's the equivalent block for ~/.claude.json:

{
  "mcpServers": {
    "lumiqa": {
      "type": "http",
      "url": "https://lumiqa.io/mcp/YOUR-SLUG",
      "headers": {
        "Authorization": "Bearer YOUR-KEY"
      }
    }
  }
}

Save the file and restart Claude Desktop (or run claude mcp list in Claude Code to confirm). The "type": "http" tells Claude to talk to a remote MCP server over HTTPS — no local subprocess to manage.

Pro tip: If you already have a ~/.claude.json, merge the lumiqa entry into your existing mcpServers object instead of replacing the whole file.
4

Try it — 5 prompts to get going

Open Claude Desktop (or run claude in your terminal) and try any of these. Each one calls a Lumiqa MCP tool under the hood, but you don't need to think about that — just ask in English.

"List my Lumiqa workspaces."
Smoke test — verifies the API key + slug are correct and the workspace is reachable. Should respond in under a second.
"Show me content awaiting approval."
Calls list_content filtered to "Attesa Approvazione". Useful when you want a quick triage of the queue.
"Upload this video https://… to my workspace, title it 'Acme Q3 Hero Cut'."
Claude fetches the URL server-side via upload_video, stores it in your R2 review area, and links it to a new content item. Returns the upload id.
"Add a comment at 00:14 on content abc123 saying 'tighten the cut on the logo reveal'."
Times-stamped feedback via add_comment. The editor sees it as a timeline pin in the Lumiqa review UI.
"Approve content abc123 and notify me when the deliverable is in R2."
Calls approve_content, promotes the latest review file to Deliverables, and Claude can poll the storage event so it can confirm completion.
Want more examples? The lumiqa-examples repo on GitHub has Python and Node scripts that exercise the same tools without an LLM — useful for cron-style automation, CI hooks, or one-off batches.
?

Troubleshooting

  • "missing_api_key" or 401: The bearer token wasn't sent or doesn't match. Double-check the Authorization header value and that the key wasn't truncated by a shell escape. Generate a fresh key from Settings → API Keys if in doubt.
  • "invalid_api_key": The token is well-formed but no matching key exists or it was revoked. Issue a new one from the dashboard.
  • Tools don't appear in Claude: Restart Claude Desktop fully (quit + reopen — a window reload isn't enough). Run claude mcp list in Claude Code to confirm registration.
  • "api_key_expired": The key had an expiration set and time's up. Create a new one (default keys created during signup never expire).
  • Slow first call: Cold starts can take ~500 ms; subsequent calls are sub-100 ms. If they stay slow, ping [email protected] with your workspace slug and we'll check the worker metrics.

Still stuck? Email [email protected] with the command you ran (key redacted) and the error message. We usually respond within a few hours during business days.