☰ Menu

Guides

Connect Claude (MCP)

Drive Lokki from your own Claude — Claude Code, Claude Desktop or your agents. Lokki is a remote MCP server: Claude can design templates and literally look at the rendered frames, push posts with your own translations, follow renders and approvals, read results and draft replies to comments. Everything still goes through your approval queue.

What Claude can do#

  • Make templates with MCP: read the template schema and your brand kit, draft a spec, validate it (structure, TikTok safe zone, text fit in every market language), render preview frames as images, fix and iterate, then save it.
  • Push content: create a post once — with your own translations per market in overrides — and Lokki localizes the rest, renders every version and queues it for approval.
  • Check the pipeline: what is rendering, what failed and why, what waits for approval; edit a version's text or ask for a new localization.
  • Results: per-market analytics, top posts and winners, and the comment inbox with suggested replies.

Endpoint and authentication#

URLhttps://uselokki.com/api/mcp
TransportStreamable HTTP (MCP spec 2025-03-26 and later), stateless, JSON responses. POST only — GET/DELETE return 405.
AuthAuthorization: Bearer lk_live_… — a Lokki API key (Settings → API keys).
PermissionsThe key's scopes decide which tools Claude sees. A read-only key gets read-only tools; decide_approval needs approvals:write.
Rate limitSame as the REST API: 120 requests per minute per key.

Use a dedicated key

Create a key just for Claude, with only the scopes you want it to have — e.g. without approvals:write if approving must stay in Lokki's own UI. Revoking the key disconnects Claude immediately.

Claude Code#

bash
claude mcp add --transport http lokki https://uselokki.com/api/mcp --header "Authorization: Bearer lk_live_…"

Add --scope project to share it with your team via .mcp.json — keep the key out of git with an environment variable:

.mcp.json
{
  "mcpServers": {
    "lokki": {
      "type": "http",
      "url": "https://uselokki.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${LOKKI_API_KEY}"
      }
    }
  }
}

Then run /mcp in Claude Code to check the connection, and try: "Design a template for our weekly offer and show me the frames".

Claude Desktop and claude.ai#

Custom connectors (claude.ai and Claude Desktop → Settings → Connectors → Add custom connector) sign in with OAuth. Lokki's MCP endpoint authenticates with an API key header today, so it can't be added as a custom connector yet — OAuth sign-in for connectors is on the roadmap.

Until then, Claude Desktop can reach Lokki through a local bridge that adds the header (mcp-remote, needs Node.js):

claude_desktop_config.json
{
  "mcpServers": {
    "lokki": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://uselokki.com/api/mcp",
        "--header",
        "Authorization:${LOKKI_AUTH}"
      ],
      "env": {
        "LOKKI_AUTH": "Bearer lk_live_…"
      }
    }
  }
}

Keep keys private

The key in this file gives access to your workspace. Use a key with only the scopes you need and revoke it when a machine is no longer used.

Agent SDK and your own agents#

Any MCP client that speaks Streamable HTTP and can send a header works. With the Claude Agent SDK:

ts
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const msg of query({
  prompt: "List what is waiting for approval in Lokki and summarise it per market.",
  options: {
    mcpServers: {
      lokki: { type: "http", url: "https://uselokki.com/api/mcp", headers: { Authorization: `Bearer ${process.env.LOKKI_API_KEY}` } },
    },
    allowedTools: ["mcp__lokki__get_workspace", "mcp__lokki__list_pending_approvals", "mcp__lokki__get_post"],
  },
})) {
  if (msg.type === "result" && msg.subtype === "success") console.log(msg.result);
}

Tools#

Tools hidden by the key's scopes are listed by get_workspace under tools.hidden_by_scope. Results are compact JSON with absolute links; preview_template returns PNG images.

Workspace

ToolScopeWhat it does
get_workspaceany keyOrg, key scopes, brand summary, markets + accounts, pending approvals, inbox counts
get_brandtemplates:readFull brand kit: tone, do's/don'ts, glossary, colours, fonts
update_brandtemplates:writeChange the brand kit (colours/fonts merged)
list_marketsmarkets:readMarkets with language, currency, approved offers, notes, posting times
list_locationsmarkets:readLocations inside markets (stores, venues) when enabled
list_accountsmarkets:readConnected TikTok accounts and their markets
list_fontstemplates:readBuilt-in and uploaded font families
upload_font_from_urlassets:writeAdd a .ttf/.otf/.woff(2) font from a URL

Templates

ToolScopeWhat it does
list_templatestemplates:readYour templates + system templates, with slot keys
get_templatetemplates:readFull spec + what a post must fill in
get_template_schematemplates:readTemplateSpec JSON Schema, authoring rules, fonts, brand tokens, example
validate_templatetemplates:readStructure errors, design lints (safe zone, sizes) and text fit per market language
preview_templatetemplates:readRenders frames as PNG images so Claude can see the design
create_templatetemplates:writeSave a new template
update_templatetemplates:writeRename or replace the spec (bumps version)
duplicate_templatetemplates:writeCopy a (system) template to edit it
generate_templatetemplates:writeAsk Lokki Studio to generate a spec from a prompt or reference
get_template_generationtemplates:readStatus and spec of a generation

Content

ToolScopeWhat it does
upload_asset_from_urlassets:writeImport an image/video/audio from a URL
list_assetsposts:readRecent media in the library (or assets:write)
create_postposts:writeOne post → a version per market/location; own translations via overrides
get_postposts:readEvery version's status, text, checks, preview and TikTok link
list_postsposts:readPosts with per-status counts, filter and paginate
update_variantposts:writeEdit one market's text/caption/schedule (re-renders)
submit_variantposts:writeSend a rendered version to the approval queue
relocalize_variantposts:writeFresh AI localization with an instruction

Review & results

ToolScopeWhat it does
list_pending_approvalsposts:readThe approval queue with exact captions and previews
decide_approvalapprovals:writeApprove (publishes) or reject with a reason — only on the user's explicit request
analytics_overviewanalytics:readTotals vs previous period, per-market results
top_postsanalytics:readBest versions by views, winners vs baseline
list_inboxposts:readComments with category and suggested reply
draft_or_send_replyapprovals:writeDraft a reply, or send it after the user confirms — only on the user's explicit request

Resources and prompts

Resource
lokki://docs/template-specTemplate authoring guide (markdown)
lokki://brandCurrent brand kit (JSON)
PromptArguments
design_templatebrief, base_template_id?Schema → draft → validate → preview → fix → save
weekly_batchweek?, theme?, posts_per_market?Draft a week of posts per market from brand + approved offers

Example: design a template with Claude#

A typical Claude Code session. Claude reads the rules, drafts, looks at real rendered frames, fixes what it sees, and only then saves:

claude code
> /mcp                                       # lokki · connected · 32 tools

You: Make us a template for weekly offers: big price, our logo, 3 scenes, works in German.

Claude  → get_workspace, get_template_schema
        ← brand "Aurora Outdoor" (Anton / Inter, #0FA36B), markets DE · FR · GB, rules + JSON schema
Claude  → validate_template { spec: { slots: [hook, price, deal, bg], scenes: [hook, offer, cta] } }
        ← warnings: scenes[offer].layers[price] leaves the safe zone at the right (x+w 0.9 > 0.84)
Claude  → preview_template { spec, per_scene: true, language: "de" }
        ← 3 PNG frames + "price: needs 3 lines, max 2 — shorten by 35%"
Claude: The price sits under TikTok's like button and the German deal text wraps badly.
        Moving the price card left, enabling autoFit (minSize 72) and adding a scrim…
Claude  → preview_template { spec (v2), per_scene: true, language: "de" }
        ← 3 PNG frames, "All text fits its boxes."
Claude: [shows the frames] Hook pops in over the photo, the price card uses brand.primary with
        brand.on-primary text, the logo closes the video. Save it as "Weekly offer"?
You: Yes.
Claude  → create_template { name: "Weekly offer", category: "promo", spec }
        ← tpl_8Kq2… · slots: hook*, price*, deal, bg* (media)

You: Use it for this week's autumn deal in every market, our own German text is below.
Claude  → list_markets  (offers: DE "15% off in October" …)
Claude  → create_post { template_id: "tpl_8Kq2…", fields: {…}, media: { bg: { url: "https://cdn…/lake.jpg" } },
                        overrides: { de: { fields: { hook: "Wach über den Wolken auf" } } }, external_ref: "autumn-w48" }
        ← 3 versions: DE manual · FR localizing · GB source → rendering
Claude  → get_post  … ← all rendered and waiting for approval (preview links)
Claude: All three versions are in your approval queue — approve them in Lokki or tell me which ones.

The design_template prompt (/mcp__lokki__design_template in Claude Code) starts exactly this loop from a one-line brief.

Approvals stay human#

  • Nothing Claude creates is posted until a person approves that exact video and caption (hash-locked) — the same rule as everywhere in Lokki.
  • decide_approval and draft_or_send_reply are marked destructive and their descriptions tell Claude to use them only when you explicitly ask for that specific decision. Leave approvals:write off the key to make approving impossible from Claude.
  • Prices and offers come from your market data (list_markets); Claude is told never to invent them.

Troubleshooting#

ResponseFix
401 Missing API key / Invalid or revokedSend Authorization: Bearer lk_live_… with an active key.
406 Not AcceptableThe client must send Accept: application/json, text/event-stream (all MCP clients do).
405 on GETExpected: the server is stateless and has no server-to-client stream.
Tool missing in /mcpThe key lacks the scope — see get_workspace → tools.hidden_by_scope.
429Rate limit (120/min per key); retry after the Retry-After seconds.