Slates MCP Server README

slates-mcp

MCP server + CLI + skills package for Slates — drive the AI Video Creation Studio from ChatGPT via Codex, Claude Code, Cursor, Claude Desktop, or another local MCP client.

This monorepo publishes two installable packages, plus their shared core:

• @slatesvideo/mcp-server — stdio MCP server. Run with npx -y @slatesvideo/mcp-server.
• @slatesvideo/cli — slates binary. Run with npm i -g @slatesvideo/cli.
• @slatesvideo/shared — the operations layer both surfaces depend on (published as their dependency, not installed directly).

Agent-side recipe markdown ("skills") lives in packages/shared/skills/ and is embedded into @slatesvideo/shared at build time — install into your project with slates install-skills, or (MCP-only clients) read any guide at runtime via the slates_get_prompting_guide tool.

What it does

The MCP/CLI lets an AI agent control your Slates workspace end to end: create projects, build characters and boards, generate images and videos (blocking or in the background), surgically edit images, assemble clips on the editing timeline, export the result as an MP4 (or FCP7 XML for DaVinci Resolve), and watch the desktop app populate live as the agent works. 180 tools total.

Both surfaces share one operations layer (@slatesvideo/shared) and one config file (~/.slates/agent-connection.json).

Desktop version note: the timeline, export, background-generation, edit-image, and image-reference tools need a Slates desktop on agent API v2. If a tool reports a version error, update Slates (Settings → Check for Updates) and retry. Everything else works on older desktops.

Setup

1. Install or update Slates desktop. Open it.
2. Settings → AI tools → enter your email → Send link. This one click starts the local HTTP server on 127.0.0.1:27272 (or the next free port) AND emails you a sign-in link.
3. Click the link in your email to authorize this machine.
4. The connection file is now written with both:
   • desktop — port + token for the local server
   • cloud — slates_sk_ token for slates-api

That's it. Both the CLI and the MCP auto-discover the connection file. No env vars, no copy-paste. (Need the local server without the cloud token? There's a raw server toggle under Advanced — most people don't need it.)

Using it

MCP server (ChatGPT via Codex / Claude / Cursor)

For ChatGPT users, sign in to the local Codex app or CLI with your ChatGPT account. With Slates open on the same computer, run:

codex mcp add slates -- npx -y @slatesvideo/mcp-server

Restart Codex. This connects local Codex; a regular ChatGPT web chat does not connect to this stdio server. Connection guide.

For Claude Desktop or Cursor, add to your MCP config:

{
  "mcpServers": {
    "slates": {
      "command": "npx",
      "args": ["-y", "@slatesvideo/mcp-server"]
    }
  }
}

Restart your client. Slates tools appear in the tool palette.

Don't want to edit JSON? The Slates desktop app writes the config for you — Settings → AI tools → Connect (one click per tool, no terminal). Or, from a terminal, npx -y @slatesvideo/cli mcp --write detects your clients, writes Claude Desktop/Cursor configs, and prints the Codex/Claude Code setup commands. For Claude Desktop you can also drop in the one-click .mcpb bundle from the latest GitHub release.

CLI (Codex, Claude Code, terminal scripts)

Fastest path — one command wires the MCP config into supported detected clients, installs the skills, and points you at the account-connect step:

npx -y @slatesvideo/cli setup

Or step by step:

npm i -g @slatesvideo/cli
slates login                  # only if you haven't connected via Settings
slates install-skills         # installs the same skills for Claude Code and Codex
slates mcp --write            # detect clients, configure or print setup commands
slates status                 # show connection state
slates run --list             # list every operation
slates run slates_create_project --name "neon samurai"

In Codex or Claude Code, the agent shells out to slates run <op> --key value instead of loading 180 tool schemas into context — slates run <op> --help prints one op's flags, and --input '<json>' carries the nested objects flags cannot.

The 43 bundled skills provide higher-level recipes: 28 workflow guides (blocking-to-prompt, camera-language, captions, character-identity, chatgpt-images, cinematic-look, content-policy, cost-discipline, cuts, dialogue-blocking, direct-response-ad, edit-and-iterate, layer-brand-captions, layer-lower-third, layer-title, model-selection, motion, one-prompt-film, previs-blocking, project-organization, restyle-from-blocking, script-craft, shot-variety, storyboard-from-script, style-prompting, transitions, ugc-influencer-ad, vision-feedback-loop) and 15 per-model prompting guides covering kling-v3.0-std, kling-v3.0-pro, kling-v3.0-omni, Seedance 2.0, Seedance 2.5, Gemini Omni Flash, MiniMax H3, MiniMax H3 Max, MiniMax H3 Max Turbo, LTX-2.5, LTX-2.5 Pro for video, Nano Banana 2 (Gemini 3.1 Flash Image), Nano Banana 2 Lite, Nano Banana Pro, GPT Image 2.5 Flare, GPT Image 2.5 Sunburst, FLUX.2 Max, Seedream 5 Lite for images, and Seed Audio 1.0, ElevenLabs Sound Effects v2, Inworld Realtime TTS-2 for audio.

Architecture

~/.slates/agent-connection.json          ← single source of truth
        │
        ├── cloud.token   (slates_sk_)   ← carried in Authorization headers to slates-api
        └── desktop.{port,token}         ← carried in Authorization headers to 127.0.0.1:PORT

@slatesvideo/shared
    operations/index.ts                  ← single tool surface
    clients/cloud.ts                     ← https://slates-api.fly.dev
    clients/desktop.ts                   ← http://127.0.0.1:PORT
    auth.ts                              ← read/write connection file
    skills/                              ← bundled markdown recipes (embedded at build time)

@slatesvideo/mcp-server
    server.ts                            ← stdio server, registers operations as MCP tools

@slatesvideo/cli
    src/index.ts                         ← commander entry
    src/commands/login.ts                ← magic-link polling
    src/commands/op.ts                   ← `slates run <op>` dispatcher
    src/commands/install-skills.ts       ← installs portable skills for Claude Code and Codex

Operations choose their transport internally. slates_get_credit_balance hits the cloud. slates_create_project hits the desktop. slates_generate_image hits the cloud, then the desktop client writes the resulting asset to the local project folder. The user watches it appear in the Slates UI as it lands.

Publishing

Publish order matters: @slatesvideo/shared must land before @slatesvideo/mcp-server and @slatesvideo/cli (both depend on it at an exact version). Always publish from the repo root with:

npm run publish:all

This builds everything first, then publishes shared → mcp → cli with --access public. Each package also has a prepublishOnly build hook, so a stray npm publish from a fresh clone can't ship an empty dist.

Privacy + security

• The desktop server is bound to 127.0.0.1 only. It rejects any non-loopback connection at the OS level.
• Every request is rejected if it carries a cross-origin Origin header (kills browser-fetch attacks) or a non-loopback Host header (kills DNS rebinding), before the bearer token is even read.
• The slates_sk_ token is sent only to the configured cloud host (slates-api.fly.dev by default). SLATES_CLOUD_BASE_URL can override the host for dev/staging, but only over https:// (or http://localhost) — an insecure override is ignored so the token can't be exfiltrated or sent in cleartext.
• Disconnect (Slates desktop → Settings → AI tools) revokes the slates_sk_ token server-side and clears it locally. Once revoked, that token's hash never authenticates again — so a leaked copy stops working too.

License

MIT — see LICENSE. Copyright Blueprint Online Learning Inc.

Context on demand

The server lists every tool, and the list stays the same for the whole connection. Your client decides how much of it to load: Claude Code and Codex send the model the tool names only and fetch a tool's full definition when it is needed. slates_load_tools with query finds a tool by task. Legacy --tools=compact and --tools=flat launch flags are accepted; both expose the full fixed list.

slates_get_prompting_guide with no topic discovers guides from a brief in query, or lists the catalog without a query. With a topic it returns a short card by default. Use query for a section or cinematic technique ID, depth: "index" for headings, or depth: "full" for the complete guide. Both text and structured content include the actual guide body. No extra loading hook is required.