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#
| URL | https://uselokki.com/api/mcp |
| Transport | Streamable HTTP (MCP spec 2025-03-26 and later), stateless, JSON responses. POST only — GET/DELETE return 405. |
| Auth | Authorization: Bearer lk_live_… — a Lokki API key (Settings → API keys). |
| Permissions | The key's scopes decide which tools Claude sees. A read-only key gets read-only tools; decide_approval needs approvals:write. |
| Rate limit | Same 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. withoutapprovals:write if approving must stay in Lokki's own UI. Revoking the key disconnects Claude immediately.Claude Code#
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:
{
"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):
{
"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:
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);
}import asyncio, os
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(
mcp_servers={"lokki": {"type": "http", "url": "https://uselokki.com/api/mcp",
"headers": {"Authorization": f"Bearer {os.environ['LOKKI_API_KEY']}"}}},
allowed_tools=["mcp__lokki__get_workspace", "mcp__lokki__list_pending_approvals", "mcp__lokki__get_post"],
)
async def main():
async for msg in query(prompt="What is waiting for approval in Lokki?", options=options):
print(msg)
asyncio.run(main())curl -s https://uselokki.com/api/mcp \
-H "Authorization: Bearer $LOKKI_KEY" \
-H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_workspace","arguments":{}}}'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
| Tool | Scope | What it does |
|---|---|---|
get_workspace | any key | Org, key scopes, brand summary, markets + accounts, pending approvals, inbox counts |
get_brand | templates:read | Full brand kit: tone, do's/don'ts, glossary, colours, fonts |
update_brand | templates:write | Change the brand kit (colours/fonts merged) |
list_markets | markets:read | Markets with language, currency, approved offers, notes, posting times |
list_locations | markets:read | Locations inside markets (stores, venues) when enabled |
list_accounts | markets:read | Connected TikTok accounts and their markets |
list_fonts | templates:read | Built-in and uploaded font families |
upload_font_from_url | assets:write | Add a .ttf/.otf/.woff(2) font from a URL |
Templates
| Tool | Scope | What it does |
|---|---|---|
list_templates | templates:read | Your templates + system templates, with slot keys |
get_template | templates:read | Full spec + what a post must fill in |
get_template_schema | templates:read | TemplateSpec JSON Schema, authoring rules, fonts, brand tokens, example |
validate_template | templates:read | Structure errors, design lints (safe zone, sizes) and text fit per market language |
preview_template | templates:read | Renders frames as PNG images so Claude can see the design |
create_template | templates:write | Save a new template |
update_template | templates:write | Rename or replace the spec (bumps version) |
duplicate_template | templates:write | Copy a (system) template to edit it |
generate_template | templates:write | Ask Lokki Studio to generate a spec from a prompt or reference |
get_template_generation | templates:read | Status and spec of a generation |
Content
| Tool | Scope | What it does |
|---|---|---|
upload_asset_from_url | assets:write | Import an image/video/audio from a URL |
list_assets | posts:read | Recent media in the library (or assets:write) |
create_post | posts:write | One post → a version per market/location; own translations via overrides |
get_post | posts:read | Every version's status, text, checks, preview and TikTok link |
list_posts | posts:read | Posts with per-status counts, filter and paginate |
update_variant | posts:write | Edit one market's text/caption/schedule (re-renders) |
submit_variant | posts:write | Send a rendered version to the approval queue |
relocalize_variant | posts:write | Fresh AI localization with an instruction |
Review & results
| Tool | Scope | What it does |
|---|---|---|
list_pending_approvals | posts:read | The approval queue with exact captions and previews |
decide_approval | approvals:write | Approve (publishes) or reject with a reason — only on the user's explicit request |
analytics_overview | analytics:read | Totals vs previous period, per-market results |
top_posts | analytics:read | Best versions by views, winners vs baseline |
list_inbox | posts:read | Comments with category and suggested reply |
draft_or_send_reply | approvals:write | Draft a reply, or send it after the user confirms — only on the user's explicit request |
Resources and prompts
| Resource | |
|---|---|
lokki://docs/template-spec | Template authoring guide (markdown) |
lokki://brand | Current brand kit (JSON) |
| Prompt | Arguments | |
|---|---|---|
design_template | brief, base_template_id? | Schema → draft → validate → preview → fix → save |
weekly_batch | week?, 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:
> /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_approvalanddraft_or_send_replyare marked destructive and their descriptions tell Claude to use them only when you explicitly ask for that specific decision. Leaveapprovals:writeoff 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#
| Response | Fix |
|---|---|
401 Missing API key / Invalid or revoked | Send Authorization: Bearer lk_live_… with an active key. |
406 Not Acceptable | The client must send Accept: application/json, text/event-stream (all MCP clients do). |
405 on GET | Expected: the server is stateless and has no server-to-client stream. |
Tool missing in /mcp | The key lacks the scope — see get_workspace → tools.hidden_by_scope. |
429 | Rate limit (120/min per key); retry after the Retry-After seconds. |