Skip to content

grok-setup-brief.md

Latest commit

 

History

History
242 lines (176 loc) · 9.61 KB

grok-setup-brief.md

File metadata and controls

242 lines (176 loc) · 9.61 KB
Raw

Grok + Selects — Agent Setup Brief

Audience: an AI agent onboarding a teammate's machine. A human is present and can act, but will not read this document. Address them only through your own messages.

Verified 2026-08-12 · Selects.app 2.0.5 · Grok CLI 1.0.3 · macOS.

Objective

Get Grok Build running with two MCP servers — Selects (video editing) and xsearch (live X search) — verified working, then report capability to the user.

You are not deciding video content. The user writes the script. Your job ends at a verified working setup plus an accurate summary of what it can now do.

Do not waste time on these

All tested and confirmed dead on 2026-08-12. Do not retry them.

Approach Result
Connecting via the Grok app (grok.com, iOS, Android) Impossible. It runs in xAI's cloud and cannot reach 127.0.0.1. xAI explicitly rejects private-network URLs.
search_parameters on /v1/chat/completions HTTP 410 — Live Search is deprecated
tools:[{"type":"x_search"}] on /v1/chat/completions HTTP 422
Expecting native X search in Grok Build Not present. It has web search only. Hence the xsearch bridge.
Using pi (@earendil-works/pi-coding-agent) instead Works, but needs 3 config files vs 2 commands, and does not forward xAI server-side tools either. Not worth it.
Tunnelling Selects to the public internet Unsafe. See Security below.

x_search is only reachable through xAI's /v1/responses Agent Tools API. That is what the xsearch bridge wraps.

Preflight

Check all four. If any fails, STOP and tell the user — do not work around it.

  1. node --version → 18 or higher
  2. /Applications/Selects.app exists → if not, user installs from https://tryselects.com
  3. Selects is running and logged in → verify by POSTing MCP initialize to http://127.0.0.1:23100/mcp; anything other than HTTP 200 means it is not ready
  4. $XAI_API_KEY is set → if not, user gets one at https://console.x.ai and adds $5 credit

On the API key

Use an API key, not grok login. A SuperGrok / X Premium subscription signs into Grok Build but does not include API access — X search would then fail silently, which is worse than failing loudly. One API key covers both.

A brand-new xAI team with $0 credit returns permission-denied on every call, including /v1/models. If you see that, the user needs to add credit — the key itself is fine.

Setup

# 1. install Grok Build
curl -fsSL https://x.ai/cli/install.sh | bash
export PATH="$HOME/.grok/bin:$PATH"

# 2. connect Selects
grok mcp add --transport http Selects http://127.0.0.1:23100/mcp

# 3. connect X search
mkdir -p ~/.local/share/x-search-mcp
curl -fsSL https://raw.githubusercontent.com/CutbackVideo/automate-video-editing-distribution/main/resources/grok-x-search-mcp/x-search-mcp.mjs \
  -o ~/.local/share/x-search-mcp/x-search-mcp.mjs
grok mcp add xsearch node -- ~/.local/share/x-search-mcp/x-search-mcp.mjs

# 4. verify
grok mcp doctor

Never write the API key into a config file. Grok Build passes the parent environment through to stdio MCP servers, so XAI_API_KEY in the shell is enough. Verified.

Success gate

grok mcp doctor must print all of:

  Selects (http: http://127.0.0.1:23100/mcp)
    ✓ handshake OK (protocol 2025-11-25)
    ✓ 35 tools discovered

  xsearch (stdio: node .../x-search-mcp.mjs)
    ✓ handshake OK (protocol 2024-11-05)
    ✓ 2 tools discovered

Found 2 healthy, 0 failing.

Do not report success on tool discovery alone. Discovery and execution are different. Confirm execution:

grok --always-approve -p "Call Selects__read_app_log with a small limit and quote what came back. Do not simulate."

If it describes what it would do rather than doing it, the tools are not attached. Re-run doctor.

Capability map

Tools appear to the agent as Selects__<name>. Many prep-layer tools need libraryId and projectId — get them from list_synced_sequences or get_prep_workflows first.

Job Tools
Intake scan_directory, probe_media, create_project, add_files_to_project, list_prep_files
Analysis start_analysis, get_prep_workflows
Multicam compare_audio, create_synced_sequence, run_sequence_sync, add_clips_to_timeline, list_prep_timeline, move_timeline_clip, remove_timeline_clips, remove_vacant_ranges, remove_empty_tracks
Cutting create_draft, switch_full_draft_multicam, analyze_retakes
Search search_scenes, export_transcript, export_draft_text
Motion graphics install_overlay, update_overlay, remove_overlay, clear_overlays
Review capture_preview, open_synced_sequence
NLE handoff preview_timeline_xml, import_timeline_xml
Scripting run_script, get_sdk_docs
Diagnostics read_app_log

Read get_sdk_docs before using run_script. The server's own instructions say to prefer one run_script TypeScript program over chaining many lookup calls for any reading or analysis — totals, grouping, pauses, search, cross-project comparison.

Two frame coordinate systems exist: playback (cuts excluded, what exports) and transcript (cuts included). Deletion is a soft "cut" flag, not removal — cut clips stay visible and restorable. Getting these backwards produces silently wrong timecodes.

Stop conditions

Hand back to the human at these points. Do not improvise past them.

  • Selects not installed, not running, or not logged in
  • No API key, or permission-denied from xAI
  • Choosing which footage to use
  • Any export or file write outside the working directory
  • Anything that publishes, uploads, or posts

Security

Selects MCP currently accepts unauthenticated requests — a plain initialize with no credentials returns HTTP 200. That is acceptable while it is loopback-only.

It is not acceptable exposed. run_script executes arbitrary TypeScript, export_transcript writes to any absolute path, and add_files_to_project reads from any absolute path. Do not tunnel port 23100 to the public internet (ngrok, Cloudflare Tunnel, or similar), even to reach the Grok consumer app. That converts a local tool into remote code execution.

Cost

Billed to xAI credits, not a subscription. Measured over a full day of heavy building — 195 requests, 763K tokens, 28 X searches — $1.04 total.

Each x_search call is $0.10–0.17 and prints its own cost. $5 covers roughly ten full walkthrough runs. Report cost to the user if a session runs long.

Known rough edges

  • Grok 4.6 is weak at terminal work — 26% on Terminal-Bench 3.0, vs ~34% for GPT-5.6 and Claude Fable 5. Prefer MCP tool calls over shell improvisation.
  • Analysis on long footage takes minutes. Poll get_prep_workflows instead of assuming failure.
  • Edit output quality is unverified. Setup and tool execution were tested; no footage has been run through create_draft yet. Do not assume a quality level in either direction. Use capture_preview to check cut points before handoff, and report what you actually observe.

Report to the user

The person you are working with will likely ask "so what is this / what did you just set up?" Answer with the summary below. Keep it plain — they are a video producer, not an infrastructure engineer. Reply in whatever language they are speaking to you.

What you now have

Grok can edit your actual footage, and it can see what is happening on X right now. Both in the same conversation.

Ask it something like "what are people posting about AI editing this week?", then "scan this folder and build me a cut around that", and it does both without you switching tools.

What it can do with footage

  • Read every camera angle and audio track, and know who is speaking when
  • Sync multicam automatically — the part that normally eats an hour
  • Cut filler words, silences, and bad takes
  • Switch cameras based on who is talking
  • Find moments by meaning: "the part where he laughs"
  • Add captions and motion graphics
  • Hand off a real Premiere / Final Cut / Resolve project, still fully editable

What it needs

  • Selects has to be open and logged in. Close it and the tools stop working.
  • An xAI API key with credit on it. A SuperGrok or X Premium subscription is not enough — that is a separate product and X search will not work with it.

What it costs

  • About $1 for a heavy full day of use. Each X search is 10–17 cents and tells you as it goes.

Two things worth knowing

  • Nobody has run real footage through this yet — setup is verified, edit quality is not. Ask for preview frames as you go so you can see the cut points for yourself.
  • The Grok phone and web app cannot do this — only the terminal version. The app runs on xAI's servers and cannot reach your computer.

If they ask what is not set up, be straight with them: this is setup only. No footage has been processed and no editing decisions have been made.

Handoff prompt

Give an agent this single line:

Read https://raw.githubusercontent.com/CutbackVideo/automate-video-editing-distribution/main/resources/grok-setup-brief.md
and set up Grok Build with the Selects and xsearch MCP servers on this machine. Follow the preflight
and stop conditions exactly. Do not report completion until `grok mcp doctor` shows 2 healthy servers
AND a live Selects tool call has returned real data.

Related

  • Viewer walkthrough, for the video description: resources/grok-selects-walkthrough.md
  • X search bridge source and docs: resources/grok-x-search-mcp/