Kestroll setup

Kestroll is an AI video editor and media library. Every uploaded video is analyzed: transcript, speakers, people, scenes, and a moment-by-moment summary. Kestroll's MCP server, https://api.kestroll.com/app/mcp, lets you search footage by what's said or shown, edit compositions the user can open in Kestroll's editor, render and export videos, post to social accounts, and read post analytics.

To set it up, the user approves you in their browser, you get an API key, and you add the MCP server with that key.

Rules

• Never print a key, a token response, a device_code, or an emailed sign-in link, and never put them in tracked files. The commands below keep them out of your output.
• Never run commands that print the environment (env, printenv, ps e).
• Configure only this client, at user level so it works in every project.
• If you can't run a step, give the user the exact command and wait.

1. Reuse a saved key

If ~/.kestroll/auth.json exists, check its key:

KEY=$(grep -o '"access_token":"kest_[0-9a-f]*' ~/.kestroll/auth.json | cut -d'"' -f4)
curl -s -o /dev/null -w '%{http_code}\n' https://api.kestroll.com/app/mcp \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}'

200 means it works: skip to step 3.

2. Get a key

Register. Name the client after yourself and the machine. The name labels the key in the user's Settings → API Keys.

curl -s https://api.kestroll.com/oauth/register -H 'Content-Type: application/json' \
  -d '{"client_name": "Claude Code (work laptop)"}'

Start sign-in with the client_id from the response. login_hint is optional: pass the user's email if you already know it.

curl -s https://api.kestroll.com/oauth/device_authorization \
  -d client_id="$CLIENT_ID" -d login_hint=user@example.com

Keep device_code, user_code, and verification_uri_complete from the response. A 429 means too many requests from this network: tell the user instead of retrying.

Open the link in the user's browser:

open "$VERIFICATION_URI_COMPLETE" 2>/dev/null || xdg-open "$VERIFICATION_URI_COMPLETE" >/dev/null 2>&1

Then send the user this message with the real values, unshortened. On a remote machine no browser opens, and Kestroll never emails the code, so they need it:

Connect Kestroll in your browser

1. A browser window should have opened to this link. If it didn't, open it yourself:

   {verification_uri_complete}

2. Sign in, or create an account if you're new.

3. Check that the page shows this code, then click Approve:

   {user_code}

The link expires in 10 minutes.

Wait for approval. Set CLIENT_ID and DEVICE_CODE, then run this. It polls for up to 10 minutes, so give it a long timeout or run it in the background. On approval it saves the token response to ~/.kestroll/auth.json, readable only by the user, and prints approved.

mkdir -p ~/.kestroll && chmod 700 ~/.kestroll
RESULT=timed_out
for _ in $(seq 120); do
  RESPONSE=$(curl -s --max-time 30 https://api.kestroll.com/oauth/token \
    -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
    -d client_id="$CLIENT_ID" -d device_code="$DEVICE_CODE")
  if printf '%s' "$RESPONSE" | grep -q 'kest_'; then
    (umask 077 && printf '%s' "$RESPONSE" > ~/.kestroll/auth.json); RESULT=approved; break
  fi
  ERROR=$(printf '%s' "$RESPONSE" | grep -oE 'authorization_pending|slow_down|access_denied|expired_token|invalid_grant')
  case "$ERROR" in
    authorization_pending|"") sleep 5 ;;
    slow_down) sleep 10 ;;
    *) RESULT=$ERROR; break ;;
  esac
done
echo "$RESULT"

The token response names the account (user.email, organization.name): tell the user which one you connected.

Other ways to get a key:

• Your own inbox. POST https://api.kestroll.com/auth/magic_link with {"email": "…"}. Copy the "Sign In to Kestroll" link from the email without opening it (opening uses it up), then POST https://api.kestroll.com/oauth/accounts/verify with {"email": "…", "name": "<key label>", "confirmation_url": "<link>"} and save the response to ~/.kestroll/auth.json.
• From the user. An organization owner creates a key in Settings → API Keys and saves it to ~/.kestroll/auth.json as {"access_token":"kest_…"}.

3. Add the MCP server

If a server named kestroll is already configured, replace it. Each command reads the key from ~/.kestroll/auth.json.

Claude Code

KEY=$(grep -o '"access_token":"kest_[0-9a-f]*' ~/.kestroll/auth.json | cut -d'"' -f4)
claude mcp remove --scope user kestroll >/dev/null 2>&1
claude mcp add --transport http --scope user kestroll https://api.kestroll.com/app/mcp \
  --header "Authorization: Bearer $KEY"

Codex

KEY=$(grep -o '"access_token":"kest_[0-9a-f]*' ~/.kestroll/auth.json | cut -d'"' -f4)
codex mcp remove kestroll >/dev/null 2>&1
printf '\n[mcp_servers.kestroll]\nurl = "https://api.kestroll.com/app/mcp"\nhttp_headers = { Authorization = "Bearer %s" }\n' "$KEY" >> ~/.codex/config.toml

Cursor: add this to ~/.cursor/mcp.json, keeping other servers, with a command that fills in the key:

{"mcpServers": {"kestroll": {"url": "https://api.kestroll.com/app/mcp", "headers": {"Authorization": "Bearer <key>"}}}}

Other clients: a remote Streamable HTTP server named kestroll at https://api.kestroll.com/app/mcp with the header Authorization: Bearer <key>.

4. Restart and verify

Clients load MCP servers at startup. Ask the user to restart you (for Claude Code, claude --continue keeps this conversation). Then call the filesystem tool with {"action": "list_folders"}; a real result confirms the connection. Tool names may have a client prefix such as mcp__kestroll__.

5. Hand off

Tell the user what you configured and which files you changed. Then offer a first task:

• To add footage, they can upload it at https://app.kestroll.com, or hand you files or links: you upload files from this machine with file_transfers and import links with web_fetch.
• Once it's processed: "Find the best 30-second moment in my latest video and cut it as a vertical clip with captions."