ClipSpeedAI MCP for Claude Code: Terminal Setup, Keys and Tool Reference

Claude Code reaches ClipSpeedAI as a remote MCP server over streamable HTTP, authenticated with a Bearer key. Registration is one command:

claude mcp add --transport http clipspeed https://api.clipspeed.ai/mcp \
  --header "Authorization: Bearer <API_KEY>"

That is the whole install. Nothing is spawned on your machine, nothing is supervised, nothing needs updating locally. Claude Code sits in ClipSpeedAI's fully supported tier — verified end to end — alongside Claude on claude.ai, Claude Desktop, and Windsurf.

What arrives after that command is ten tools inside a terminal session: trend discovery, submission, clip retrieval with titles and viral scores and download URLs, per-clip creator assets, caption templates, YouTube publishing, and a four-call lifecycle for clipping a stream while it is still broadcasting. This page is written for the CLI reader specifically — the key format and the endpoints behind it, which identifier chains to which call, three worked terminal sessions, and the failure modes you can diagnose from the transcript in front of you instead of guessing.

Run This First: The Add Command, Flag by Flag

The canonical registration, exactly as ClipSpeedAI publishes it:

claude mcp add --transport http clipspeed https://api.clipspeed.ai/mcp \ --header "Authorization: Bearer <API_KEY>"

Four moving parts, and each one fails in its own way if you get it wrong.

• --transport http declares a remote server reached over HTTP. Leave it off and Claude Code is liable to treat the rest of the line as something to launch locally — and there is nothing local to launch.
• clipspeed is the local handle. It is what claude mcp list prints and what namespaces the tool names inside a session. Pick it once and keep it; every prompt you write later that says "use the clipspeed MCP" is keyed to this string.
• The URL is the endpoint itself, https://api.clipspeed.ai/mcp.
• --header is authentication. The server accepts OAuth for GUI clients and a Bearer API key for CLI clients; Claude Code is the second kind, so the key rides in a header on every request.

Pasting a live credential straight onto the command line puts it in your shell history. Export it first:

export CLIPSPEED_API_KEY="csai_live_..." claude mcp add --transport http clipspeed https://api.clipspeed.ai/mcp \ --header "Authorization: Bearer $CLIPSPEED_API_KEY"

In a shell configured with HISTCONTROL=ignorespace, prefixing the export line with a single space keeps that line out of history too. Otherwise, clear the entry afterwards or source the key from a file your shell reads at startup.

Claude Code can register servers at more than one scope — private to you, tied to a project, or available everywhere. The exact flag name varies by version, so run claude mcp add --help against the binary you actually have rather than copying a flag from a blog post. The choice matters: a project-scoped registration is written into a file that travels with the repository, which is convenient for a team and hazardous for a secret. That trade-off gets its own section further down.

You rarely need to hand-edit anything, because the CLI writes the registration for you. If you do want to inspect or repair it by hand, get the file location and its schema from Claude Code's own documentation rather than from memory, and restart the session afterwards — a stored registration is read at startup. Setting the same server up in a windowed client is a different exercise entirely, and ClipSpeedAI MCP for Claude Desktop: Complete Setup Guide covers that path.

Three Escalating Checks That the Wire Is Actually Live

"It installed" and "it works" are three checks apart. Run them in order, because each one rules out the layer below it.

1. Registered? claude mcp list should print clipspeed and the endpoint. A blank result means the add command failed, or it wrote to a scope that does not apply to the directory you are standing in.
2. Connected and advertising? Start a session and run /mcp. You get connection state plus the tools the server offered at handshake time. A server that is listed but advertises nothing is a transport or credential problem — the tools are fine, the connection never completed.
3. Round-tripping? Ask for the cheapest read there is: "Use the clipspeed MCP to list the caption templates." The tool is list_templates, and a healthy answer comes back with six ids — karaoke, hormozi, beasty, fire, youshaei, cinematic. Those exact strings are the proof. Discovery, authentication, and a full request-response cycle are all confirmed by one call that starts no work and consumes no video.

Do this before touching anything else.

csai_live_ Keys: Format, Endpoints, Counters, and Revocation

A ClipSpeedAI API key is the string csai_live_ followed by 48 hexadecimal characters. That is not decoration — it is a shape you can check before you paste. If your clipboard holds something shorter, or something that does not match that prefix, the copy was truncated and no amount of header-quoting will save it.

Keys are managed through three routes, and the account UI at Account → API & Integrations → Generate API Key drives the first of them:

• POST /auth/api-keys mints a key.
• GET /auth/api-keys lists what you hold: id, name, key_prefix, plan, rate_limit, requests_today, total_requests, last_request_at, is_active, and created_at.
• DELETE /auth/api-keys/:id revokes one: is_active flips to false and revoked_at is stamped.

Two consequences follow directly from that list. First, only the prefix is stored for display — the first 18 characters plus an ellipsis — so the full key exists in front of you exactly once, at creation. There is no "show key again" anywhere, because the server does not have it to show. Copy it into your password manager in the same motion you copy it into your shell.

Second, revocation is real and it is immediate at the record level, which makes rotation a clean three-step operation rather than a leap of faith. Create the replacement first. Then update the clients that hold the old one — in Claude Code the tidy route is claude mcp remove clipspeed followed by the add command again with the new value, so the stored header is rewritten whole rather than patched, and then restart the session. Only once nothing is using it do you DELETE the old key. Reversing steps one and three is how you break a running job.

The per-key rate_limit and the running counters are worth exploiting rather than ignoring. Issue a separate key per consumer — one for your laptop, one for a scheduled runner — and requests_today, total_requests and last_request_at become an audit trail per consumer. A key that is being used by something you did not authorise shows up as traffic you cannot account for, and DELETE ends it. The wider comparison of this model against browser-based authorisation lives in MCP Authentication: OAuth and Bearer Keys.

Rotate on sight if a key has ever appeared in a screen recording, a shared terminal, a pasted support ticket, a CI log, or a commit. You cannot un-send a leaked credential; you can only make it inert.

Eligibility note: API key generation requires a plan with API access. A $1 trial account qualifies; a free account does not — the endpoint returns 403 Feature not available. Keys are shown once at creation, carry a per-key daily rate limit (exceeding it returns 429 rate_limit_error), and can be revoked at any time, which stamps a revocation time against the key.

The Ten Tools, and the Two Identifiers That Chain Them

Ten tools are exposed, no more. The names below are exact — if a transcript shows your agent calling something that is not here, it invented the name and no call reached the server.

Argument names and shapes are advertised by the server itself at connection time, so /mcp in a live session is the authority on the current schema. The table describes purpose and the identifier each call turns on.

The whole surface reduces to two identifiers. A projectId is the handle for recorded work: it is what check_clips reads, what creator_pack decorates, and what publish_to_youtube targets. A subscriptionId is the handle for a live session, and the other three live calls do nothing without it. Ask your agent to state both back to you in plain text when it gets them. That single habit is what lets you resume tomorrow instead of resubmitting, and it costs one sentence in the prompt.

Notice what the split implies: submission and retrieval are different calls on purpose. submit_to_clipspeed returns quickly because clipping has not happened yet; check_clips is the only thing that produces clips. An agent that submits and then announces success has not seen a single frame of output. Why a server would decompose its capabilities this way rather than offering one do-everything call is the subject of MCP Tool Design: Writing Tools an Agent Can Actually Use.

Six Caption Templates, One captionStyle Argument

Captions are not an afterthought bolted on later — clips come back captioned. What you choose is the style, and the choice is made from a fixed catalogue. The real ids are exactly these six:

karaoke
hormozi
beasty
fire
youshaei
cinematic

You pass the chosen id as captionStyle. The id string is the contract: hormozi is an id, "hormozi-style" is not, and "the bold yellow one" is definitely not. A near-miss is a rejected argument, not a fuzzy match.

Call list_templates rather than guessing from the names, both because the server's own description of each template is the accurate one and because it doubles as your health probe. In a scripted run, listing first and choosing second means your caption style is selected from the live catalogue instead of from a value you hardcoded months ago.

One practical note for terminal workflows: because template selection is just a string, it belongs in your saved prompt. A weekly run that always uses the same style should say so explicitly, so that a model improvising a different one is visible as a diff rather than as a surprise in the output.

What the Protocol Is Doing While You Watch the Transcript

Most explanations of the Model Context Protocol are abstract because most clients hide it. A terminal does not. You can watch the entire mechanism scroll past, which makes Claude Code an unusually good place to learn what MCP actually is.

Here is the sequence you are looking at. Your client opens a connection to the server and the server answers with a manifest — the names of its tools, what each one is for, and what arguments each accepts. Nothing about ClipSpeedAI was compiled into Claude Code; the capability list arrives at runtime, which is why /mcp can show you tools that did not exist when you installed the CLI. From then on the model has a menu. When your instruction implies one of those tools, the model emits a call with arguments, the client sends it over HTTP, and the result comes back as content the model reads and reasons over. Then it may call again.

The part worth internalising is who decides. You do not name the call; you state the outcome, and the model selects and sequences. "Cut this episode and tell me which clip scored highest" becomes submit, wait, check, sort — a plan the model constructs, not one you encoded. That is the difference between an integration and a script, and it is why the same connection handles workflows nobody wrote a code path for.

If the concept is new, What Is MCP? Model Context Protocol Explained is the ground-floor version. The wire-level view of handshake, discovery and invocation is set out in How MCP Servers Work: Architecture and Request Flow. Two comparisons sharpen the edges from either side: MCP vs Function Calling: What Actually Differs deals with the confusion about tool definitions pasted into a prompt, and MCP vs REST API: When to Use Each addresses the reasonable objection that you could simply call an HTTP endpoint yourself.

Why the Heavy Work Happens Off Your Machine

MCP servers come in two deployment shapes. A local server is a process the client starts on your machine and talks to over stdio — the correct design when the work needs your filesystem, your ports, or your hardware. A remote server is a service reached over HTTP — the correct design when the work is heavy, long-running, or has to survive you closing the lid.

ClipSpeedAI is remote, and clipping is a good argument for why. Your machine sends a URL and reads back results. The media pipeline is not on your side of the wire at all, which is also why the install has no build step, no ffmpeg dependency, and no version of the engine pinned locally to go stale.

An npm package named clipspeed-mcp also exists (v1.0.0, published 2026-07-10). Claude Code has no use for it: the HTTP transport is native here, so registering the URL is both the shorter path and one fewer moving part to keep current. For the general case of choosing between the two shapes, Remote MCP vs Local MCP Servers makes the argument at length.

Session One: Trend Search to Reviewed Cuts, With Publishing Held Back

A first real run, typed into a session:

Use the clipspeed MCP. Find a fast-growing recent F1 breakdown video,
submit it for clipping with captionStyle cinematic, then poll until the
clips are done. Give me the projectId, and list every clip with its
title and viral score. Publish nothing.

Trace it:

1. discover_trending searches the niche. Its window is narrow by design — roughly the last three weeks of published video — so it surfaces things still climbing rather than evergreen back-catalogue. Make the agent tell you which URL it picked. Correcting the choice here costs a sentence; correcting it after a clipping run costs the run.
2. submit_to_clipspeed takes that URL and starts the job. It returns fast, and at this moment nothing is clipped.
3. check_clips runs against the projectId. Early polls may show work still in progress; the agent calls again. This is the loop that used to be you and a browser tab.
4. When clips exist, each one comes back with a title, a viral score and a download URL. The cuts are already 9:16, already captioned with the spoken words, already reframed. None of that was in your prompt because none of it is your job.

Publishing is a separate turn, taken after you have actually looked:

Publish clip 2 from that projectId to YouTube with the title
"Nobody Noticed This Pit Call". Leave privacyStatus at the default.
Show me the exact arguments before you send them.

publish_to_youtube takes the projectId, optionally a clipId, a title, and a privacyStatus — and it defaults to private. That default is a genuinely useful safety property: an unattended publish lands somewhere only you can see unless something explicitly overrode it. Treat any prompt that sets privacyStatus to a public value as a prompt that needs a human in the loop, and keep it in its own turn. Generation is reversible. An upload to a channel is the one step here that other people can see.

Session Two: A Stream That Runs Longer Than Your Window

Recorded video waits for you. A broadcast does not, which is the entire reason for a separate live path: capture happens as the stream runs rather than after a VOD materialises.

Use the clipspeed MCP to start clipping this stream:
https://twitch.tv/<channel>
Tell me the subscriptionId. Check it every ten minutes and report the
highest-scoring clip so far. If it's still monitoring when we get near
the end of the session, extend it.

1. clip_livestream opens the session and hands back a subscriptionId. Everything after this is addressed to that identifier, so capture it in the transcript deliberately rather than trusting a long conversation to remember it.
2. check_livestream polls. A status of monitoring means the stream is still live and still being clipped — that word is the signal you are watching for, not an absence of errors. Clips accumulate during the broadcast, so you get moments while they still matter.
3. extend_livestream extends a session that is still active. The mechanic to remember is the ordering: extension applies to a session that has not ended.
4. stop_livestream ends it. Clips already made are kept and remain downloadable, so stopping is not destructive — a stop is a clean close, not a discard.

Two boundaries cause most live confusion. The stream has to be live at the moment you call clip_livestream; a URL for a broadcast that ended twenty minutes ago is a recorded video and belongs to submit_to_clipspeed. And a session that has already stopped is not a candidate for extension — you start a new one. The model behind all four calls is laid out in Livestream Clipping API: Clip While You Stream.

Session Three: A Backlog Pass That Ends in a Committed Manifest

The run that repays the setup is the unglamorous one you do every week — and this is where a terminal client pulls away from anything with a browser in it, because the results land in your repository instead of your downloads folder.

Use the clipspeed MCP. List the caption templates first so I can see the
real ids. Then submit these four episode URLs one at a time with the id I
pick, waiting for each before starting the next. For every finished
project, pull the creator pack. Write CLIPS.md with a table of episode,
projectId, clip title, viral score, download URL, suggested hook and best
posting time. Publish nothing.

1. list_templates puts the six ids in front of you before anything is committed to a style.
2. submit_to_clipspeed runs once per URL. Sequential is the right instruction here: each projectId stays attached to a known episode, and a failure is attributable to one URL instead of buried in interleaved output.
3. check_clips collects titles, viral scores and download URLs per project.
4. creator_pack adds the per-clip suggested titles, hooks and best posting times for the same projectId — the difference between having cuts and having something ready to schedule.
5. Claude Code writes CLIPS.md with its ordinary file tools and, if you ask, commits it. No MCP call was involved in that last step, which is the point: the clipping results are now inside the same workspace as everything else you do.

Because the instruction is text, it belongs in your project's instructions file, and next week's run becomes one line. Chaining a specialist service into work an agent was already doing is the general pattern behind AI Agent Video Automation: End-to-End Workflows, and the same weekly loop written for people who would rather never open a terminal is MCP for Creators: Automating Video Without Code.

When It Misbehaves: Symptoms You Can Read Off the Terminal

Each of these has a distinct signature. Match the symptom, then apply the fix — do not start rewriting config on a hunch.

Listed, but zero tools advertised. This is transport or credentials, not tooling. Confirm --transport http was present, then confirm the header survived quoting — inspect what claude mcp list stored. Re-adding the server is cleaner than editing around a bad entry.

Authentication rejected. Check these in turn: the key does not match csai_live_ plus 48 hex characters, so the copy was truncated; the literal word Bearer is missing or misspelled; your shell consumed the quotes and only part of the header reached the config; the key belongs to a different account than you assume; or the key has been revoked, in which case GET /auth/api-keys shows is_active false with a revoked_at timestamp. Re-add using the exported-variable form and confirm with list_templates.

Tools absent from the session you are sitting in. Registration is not retroactive. Restart Claude Code and check /mcp. Still empty, and the likely cause is scope: the server was registered somewhere that does not cover your current directory. Re-run the add command from the directory you work in, or register at a broader scope.

The agent says it clipped something and there is nothing. Look for check_clips in the transcript. If you only see submit_to_clipspeed, nothing was retrieved — submission and retrieval are separate calls. Give it the projectId and tell it to poll until clips come back.

A tool name you do not recognise. Compare it against the ten. Vague prompts invite invented calls; naming the tool — "use clip_livestream on this URL" — removes the ambiguity entirely.

A live call errors. Three causes, three fixes. The stream is not live, so it is a recorded video and submit_to_clipspeed is the right tool. The session already stopped, so start a new one rather than extending. Or the subscriptionId went stale across a long conversation, in which case have the agent call check_livestream and re-establish state before doing anything else.

Publishing does not go through. publish_to_youtube operates on a finished clip via projectId and an optional clipId — if the project has not produced clips yet, there is nothing to publish, so verify with check_clips first. If the call reaches the server and still fails, check what your account needs for YouTube publishing in the app; that is account state, not something the CLI can repair.

Requests are being limited. Every key carries its own rate_limit alongside requests_today and total_requests. GET /auth/api-keys tells you what a key has actually consumed today, which converts a vague "it went quiet" into a number.

It worked on Monday and refuses on Thursday. Check plan state before assuming the integration broke. There is no free plan, and a trial is three days long.

Nothing leaves the network. If api.clipspeed.ai is unreachable from your network or your container, configuration cannot fix it. Confirm outbound HTTPS is permitted, including through any proxy your shell is set to use.

Keys, Repos and Unattended Runs — The Risks Specific to a CLI Client

A key is the account. Bearer authentication has no scope negotiation and no user prompt: whoever holds a valid csai_live_ string acts as you against this server. That is the trade you accept in exchange for a one-command setup with no browser round-trip. Store it like a password, not like a setting.

The repository is the specific hazard here. A project-scoped registration lives in a file that gets committed, which puts a live credential one git push from being public — and public repositories are scraped for exactly this. Prefer a personal-scope registration for a personal key. If a project-scoped entry is genuinely needed, keep the real value outside the committed file and make sure whatever holds it is gitignored. If a key ever lands in a commit, revoke it with DELETE /auth/api-keys/:id and issue a new one; rewriting history does not un-leak anything that has already been cloned.

What crosses the wire. The server sees what your calls carry: the URLs you submit, the arguments your prompt implies, and the account the key belongs to. It has no view of your filesystem, your repository, or your shell. Claude Code reads your files locally; MCP calls transmit only their arguments. That separation is worth stating in a CLI context precisely because the agent can see so much more than the server can.

Exactly one tool pushes outward. Of the ten, only publish_to_youtube puts something on the public internet, and it defaults to private. Everything else either reads or starts work inside ClipSpeedAI. Let that asymmetry set your caution budget: exploration is cheap, and the publish call deserves a confirmation step every time.

Scripted and scheduled runs need boundaries. If you wire Claude Code into CI or a cron job, decide in advance whether that context is permitted to publish at all — an automation that can generate and upload without a human turn is one malformed prompt away from an embarrassing video on your channel. Give the runner its own key so you can watch its counters and revoke it independently. These principles generalise past this one server, and MCP Security: Scopes, Keys and Safe Tool Design is where they are set out properly.

Boundaries: What This Server Will Not Do, and What It Costs

Ten tools is the surface. If a workflow needs something outside that list, it needs something outside this MCP server. Do not assume an unlisted capability exists because it would be sensible.

Clipping is asynchronous. There is no synchronous "return clips now" call. Design every prompt around submit-then-poll, and treat a confident success message with no check_clips behind it as wrong.

Publishing here is YouTube only. publish_to_youtube is the single publish tool exposed.

Viral scores are scores. check_clips returns one per clip and they are useful for ranking your own output against itself. Do not build thresholds on assumed ranges you have not seen documented.

Bearer keys are long-lived by design. That is the cost of a setup with no browser step. If you would rather have credentials the client manages on your behalf, the OAuth path exists on GUI clients — ClipSpeedAI MCP for Claude (claude.ai): Complete Setup Guide walks through it.

Pricing, once, in full. There is no free plan. $1 starts a 3-day trial — a one-time $1 today, converting after three days unless you cancel. Starter is $15/mo, Pro $29/mo, Ultra $49/mo, and annual billing saves 50%. A free demo exists but it is one demo on a video under 30 minutes: enough to judge the output, not enough to build a workflow on.

Client tiers are not interchangeable, and the labels are deliberate. Claude Code, Claude on claude.ai, Claude Desktop and Windsurf are fully supported and verified end to end. Cursor, Codex, OpenClaw and Hermes speak the same protocol and are listed as compatible, with verification still in progress. ChatGPT is rolling out and depends on vendor gating, so it is unverified. Where a guide in this cluster says compatible rather than fully supported, read that as a statement about what has been tested, not a hint about quality. If you are weighing editors before committing, Claude Code vs Cursor for MCP Workflows compares them on the axis that matters here, and ClipSpeedAI MCP for Cursor: Complete Setup Guide covers that client's own steps.

Two directions lead out of this page. If you would rather call the engine from your own code than through an agent, AI Clipping API: Programmatic Short-Form Video and Video Clipping API for Developers take the direct route, while MCP for Video Editing and Clipping Workflows stays at the agent layer. And if reading the tool table gave you ideas about your own service, How to Build an MCP Server (Practical Guide) is the build-side companion, with Best MCP Servers for Video and Content Workflows as the survey of what already exists.

Frequently asked questions

What is the exact command to register the server in Claude Code?

claude mcp add --transport http clipspeed https://api.clipspeed.ai/mcp --header "Authorization: Bearer " — where is generated at Account → API & Integrations → Generate API Key. Export the key to an environment variable first and reference it as $CLIPSPEED_API_KEY if you want to keep the literal value out of your shell history.

What does a ClipSpeedAI API key look like?

The string csai_live_ followed by 48 hexadecimal characters. Only the prefix — the first 18 characters plus an ellipsis — is stored for display, so the full key is shown once at creation and cannot be retrieved afterwards. If what you pasted is shorter than that or lacks the csai_live_ prefix, the copy was truncated.

Can an API key be revoked, and how?

Yes. DELETE /auth/api-keys/:id revokes a key: is_active is set to false and revoked_at is stamped. GET /auth/api-keys lists what you hold along with each key's plan, rate_limit, requests_today, total_requests and last_request_at. Rotate in this order — create the replacement, update every client, then revoke the old key.

How do I prove the connection works without starting a clipping job?

Ask the agent to call list_templates. It is read-only and it returns the six caption template ids — karaoke, hormozi, beasty, fire, youshaei, cinematic. Getting those exact strings back proves discovery, authentication and a full round trip in one call. Before that, claude mcp list confirms registration and /mcp inside a session confirms the server is connected and advertising tools.

What are the caption template ids, and how do I choose one?

karaoke, hormozi, beasty, fire, youshaei and cinematic. Pass the chosen id as captionStyle. The id string is what the server accepts — a paraphrase such as "hormozi-style" is not an id. Call list_templates rather than guessing, so the choice is made from the live catalogue.

My agent said it clipped a video but there are no clips. Why?

Submission and retrieval are separate calls. submit_to_clipspeed starts an asynchronous job and returns quickly; check_clips is what returns the finished 9:16 clips with their titles, viral scores and download URLs, and it is keyed by projectId. If the transcript shows a submit with no follow-up check, nothing was retrieved — give the agent the projectId and tell it to poll.

Will publishing to YouTube post something publicly by accident?

publish_to_youtube defaults to private. It takes projectId plus an optional clipId, title and privacyStatus, so a public post requires privacyStatus to be set explicitly. Keep publishing in its own turn anyway: it is the only one of the ten tools that pushes content to the public internet, and it is the hardest step to walk back.

Can it clip a stream that has already ended?

Not through the live tools. clip_livestream, check_livestream, extend_livestream and stop_livestream all operate on a session against a stream that is live right now, addressed by subscriptionId. Once the broadcast is over the recording is an ordinary video and belongs to submit_to_clipspeed. A stopped session also cannot be extended — start a new one.

Do I need the clipspeed-mcp npm package?

Not for Claude Code. A package named clipspeed-mcp (v1.0.0, published 2026-07-10) is published on npm, but Claude Code speaks the streamable HTTP transport natively, so registering the endpoint URL directly is all that is required — and it is one fewer dependency to keep current.

What does using the MCP server cost?

It requires a ClipSpeedAI plan or trial; there is no free plan. $1 starts a 3-day trial — a one-time $1 today that converts after three days unless you cancel. Starter is $15/mo, Pro $29/mo and Ultra $49/mo, with annual billing saving 50%. A free demo exists but is limited to one demo on a video under 30 minutes.

Related reading