ClipSpeedAI MCP in Windsurf: Wiring Cascade to the Clipping Engine

Windsurf sits in ClipSpeedAI's top support tier — the connection has been checked end to end, not assumed to work because the protocol happens to match. In practice that means Cascade can look for a trending video, drop it into the clipping engine, read back scored 9:16 clips with their download links, run a live stream session, and push a finished cut to YouTube, without you leaving the editor.

Nothing gets installed on your machine. ClipSpeedAI runs a single remote HTTP MCP endpoint at https://api.clipspeed.ai/mcp, and Windsurf authenticates to it with a long-lived API key sent as an Authorization: Bearer header. An npm package (clipspeed-mcp) also exists for people who want a local process, but it is not part of this setup and you can ignore it.

This page starts with getting the thing connected, because that part has a correct answer, and only afterwards explains why the pieces are shaped the way they are. If you would rather understand the protocol before touching a settings panel, What Is MCP? Model Context Protocol Explained is the better front door and this guide will still be here.

Before You Open the Settings Panel

Five things, and only two of them are about ClipSpeedAI.

• A Windsurf build with an MCP section in Cascade's settings. If you open the settings and there is no MCP area at all, updating the editor is step zero — everything below assumes the panel exists. Which builds carry it is Windsurf's business to document, not this page's to guess at.
• An account that is actually paying. The pricing runs like this: a single $1 charge opens a three-day trial, and when those three days are up it becomes whichever plan you picked unless you cancel first. Starter is $15 a month, Pro $29, Ultra $49, and paying annually halves the rate. Nothing here is free. There is a demo — one run, on a video shorter than half an hour — which is plenty for judging output quality and not nearly enough to drive the batch workflows further down.
• An API key. Issued in the web app; the next section covers what the key looks like, what the server keeps, and what the counters on it tell you.
• A clean outbound path to api.clipspeed.ai on 443. Corporate proxies and TLS-inspecting middleboxes are the environmental failure that costs people the most time, mostly because it disguises itself. A blocked or intercepted connection shows up as a certificate or connection error, never as a 401 — so if you find yourself regenerating keys against a certificate warning, the key was never the problem.
• Optional: a YouTube account already connected to your ClipSpeedAI account. Only publish_to_youtube needs it. Everything else works without it.

Notice what is not on the list: Docker, Python, Node, a background daemon, a tunnel, or any per-tool integration work on your side. The whole client-side surface is one server entry and one header.

Your csai_live_ Key: What It Is and What the Server Keeps

Generate the key in the web app under Account → API & Integrations → Generate API Key. The same action over HTTP is POST /auth/api-keys.

The key you get back starts with the literal prefix csai_live_ followed by 48 hexadecimal characters — 24 random bytes, hex-encoded. That is worth internalising for one reason: if the string sitting in your config does not begin csai_live_ and end in a long unbroken run of 0-9a-f, you have pasted the wrong thing, and no amount of reloading the editor will fix it.

You see the full key exactly once, at creation. ClipSpeedAI stores only a display prefix — the first 18 characters, then an ellipsis — so the key list can distinguish rows without holding the secret. There is no "reveal key" button waiting for you later. Copy it into a password manager or your OS keychain the moment it appears.

GET /auth/api-keys lists what your account holds, and the fields are more useful than they sound: id, name, key_prefix, plan, rate_limit, requests_today, total_requests, last_request_at, is_active and created_at. When you are trying to work out whether Cascade is genuinely reaching the server or just talking convincingly about doing so, last_request_at and requests_today settle the argument in a way that a chat transcript cannot. Each key also carries its own rate_limit, so a runaway polling loop on one key does not silently spend another's headroom.

Keys can be revoked: DELETE /auth/api-keys/:id sets is_active to false and stamps revoked_at. Because the list carries names and ids, giving each machine its own named key is a real strategy rather than a nice idea — when a laptop leaves your possession you kill that one row and every other client keeps working untouched.

Rotation follows from that. Generate the replacement first, put it into Windsurf, reload, confirm a call succeeds, and revoke the old row last. Do it in the other order and you get to debug a broken connection and a missing credential at the same time. The general shape of key-based versus browser-based auth is laid out in MCP Authentication: OAuth and Bearer Keys; ClipSpeedAI's server accepts both, and Windsurf takes the key path.

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.

Pointing Windsurf at the Endpoint Without Copying Someone Else's JSON

This is the point where most setup guides hand you a config block to paste. This one will not, on purpose. The field names Windsurf uses to describe a remote HTTP MCP server belong to Windsurf, they are not something ClipSpeedAI can verify on your behalf, and a stale block copied off a blog post is the most efficient way to lose an evening to a config that never had a chance of loading. Windsurf's own MCP documentation, and the add-server form inside the editor, are authoritative for your build.

So here is what you are configuring, described by what it has to end up meaning:

• A server entry with a name you will recognise in the panel later — clipspeed does fine.
• Transport: remote HTTP. Not a command to launch, not stdio, not a local binary path. If the form is asking you for an executable, you are filling in the wrong kind of entry.
• URL: https://api.clipspeed.ai/mcp, exactly, with no trailing path.
• One header: name Authorization, value Bearer then a single space then your csai_live_… key.

Reach the config through Cascade's MCP settings rather than hunting for a file on disk. Whatever file that panel opens is the file the editor actually reads, which is not always the file a search engine told you about. If your build offers an add-server form, use it once and then edit what it generated — that guarantees the surrounding structure matches your version's schema, and it turns any later mistake into a one-field mistake.

The header is the one piece this page can pin down to the character, because the same connection is documented for command-line clients:

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

That command is for Claude Code, not Windsurf — do not run it here. It is reproduced because the header it constructs is byte-for-byte the header Windsurf has to send. The literal word Bearer, one space, the key, nothing else. Dropping the scheme and pasting just the key is the most common setup mistake there is, and it fails in a way that looks like something else entirely.

If the editor rejects your entry complaining about an unknown or missing field, that is a mismatch between what you typed and what your build's schema expects — not a ClipSpeedAI problem, and not something to fix by changing the URL or regenerating a key. Let the add-server form write the entry instead.

First Call: Ask Cascade for the Six Caption Styles

Windsurf does not re-read MCP config on file save, so reload the server from the panel or restart the editor. Then check three things in order, cheapest first.

1. The entry is listed without an error badge. If it is not listed at all, you edited a different file than the one the panel opens.
2. The tool count is ten. A server that connects and then exposes nothing is the classic signature of a transport that worked and an auth header that did not.
3. A real call comes back. Ask Cascade: "Use ClipSpeedAI to list the caption-style templates."

That routes to list_templates, which takes no arguments, has no side effects, costs you nothing, and still exercises the full path — transport, header, account. It is the ideal smoke test, and it is worth making it a reflex after any change to the config or the key.

What comes back is a fixed set of caption-style ids, and they are exactly these six:

karaoke
hormozi
beasty
fire
youshaei
cinematic

You pass the one you want as captionStyle when submitting a video. Two things follow from that. First, these are caption styling only — this is not a layout picker, and the tool is not returning some per-account entitlement list. Second, because the set is small and fixed, you can decide your house style once and then simply name it in every prompt. "Clip this with the hormozi style" is an unambiguous instruction; "use a bold caption look" makes the model guess.

If list_templates returns the six ids, your setup is finished. Everything below is about using it.

What Cascade Actually Learns When It Connects

The interesting thing about this integration is how little of it exists in your editor. When Windsurf opens the connection, it asks the server to describe itself, and the server answers with an inventory: what it can do, what each capability is called, and what arguments each one expects. Cascade holds that inventory in the model's working context, and from then on the tools are simply things the model can decide to call, the same way it decides to read a file.

The consequence people miss is that nothing about ClipSpeedAI is compiled into Windsurf. You did not write a wrapper function. There is no SDK pinned to a version in a lockfile. If ClipSpeedAI changes an argument name tomorrow, your next connection picks up the new description and the model plans against it — no editor update, no package bump, no broken build on your side. That is also why you should never hardcode argument names into your prompts: the schema the server publishes is the contract, and the model is already reading it.

Coming from a services background, the instinct is to file this under "HTTP API with extra steps". MCP vs REST API: When to Use Each is where that instinct gets tested properly, and MCP vs Function Calling: What Actually Differs covers the closer comparison — the one where people assume MCP is a repackaged tool-calling API and then discover where the discovery step changes things. The request path itself, from the model's decision to the server's response, is traced in How MCP Servers Work: Architecture and Request Flow. If you get far enough into this to want your own server on the other end of Cascade, How to Build an MCP Server (Practical Guide) is the build-side companion.

Why the Clipping Runs on ClipSpeed's Hardware, Not Yours

MCP servers come in two shapes, and it is worth being clear about which one you just connected. A local server is a process your editor spawns on your machine; it can see your filesystem, it inherits your environment, and it dies when the editor does. A remote server is a hosted endpoint reached over the network; it has no view of your machine whatsoever.

ClipSpeedAI is remote, and the reason is the workload rather than fashion. That is sustained encoding work measured against the length of the source video, not against your typing speed. Run it locally and a two-hour stream would own your CPU and your battery for as long as it takes — while you are trying to write code in the same editor.

The second reason is duration. Submission does not return clips; it returns a project reference, and the work continues on the server side while you do something else. That model only makes sense if the thing doing the work is not tied to your editor's process lifetime. Because the state lives server-side and is keyed by a reference, picking a job back up later is a matter of handing Cascade the same reference again rather than keeping a window open — although you should treat live sessions as having a finite run window, which the live workflow section covers.

The trade you are making: you get no local compute cost and no local install, and in exchange the server sees whatever you send it and nothing else. Remote MCP vs Local MCP Servers compares the two architectures properly, and MCP for Video Editing and Clipping Workflows looks at how the asynchronous shape changes how you write prompts.

The Ten Tools, Grouped by Blast Radius

Every guide lists these ten tools in the order the server happens to return them. That ordering is useless for deciding what to let an agent do unsupervised. Here they are grouped by what a call actually changes.

Group 1 — reads nothing changes. Safe to let Cascade call freely, in a loop, without asking you.

Group 2 — starts work on your account. Consumes plan usage, produces private artifacts, nothing leaves your account.

Group 3 — the two worth a human decision.

That grouping is the whole permissions policy: let group 1 run, let group 2 run when you asked for work, put yourself in front of group 3. Why tools deserve to be designed so that grouping is even possible is the subject of MCP Tool Design: Writing Tools an Agent Can Actually Use.

Run One: From a Three-Week Trend Window to a Private Upload

The full path, typed into Cascade.

Find the fastest-growing Formula 1 video from the past couple of weeks.
Clip it with the hormozi caption style.
When the clips are done, list them with their titles and scores.
Don't publish anything yet.

What runs, in order:

1. discover_trending returns candidates from its recent window. Cascade shows them; pick one or let it pick and tell you which.
2. submit_to_clipspeed takes that URL with captionStyle: hormozi. You get a project reference back quickly — that reference is not the clips, and a prompt written as if it were will produce an agent that either waits badly or makes something up.
3. check_clips runs against the projectId. Early calls may return little or nothing; clips land progressively.
4. Cascade prints titles, scores and download URLs. Because you said not to publish, nothing did.

Then, after you have read the list and watched the ones that matter:

Publish the top two to YouTube as private, using the titles
you drafted but swap "insane" for "unbelievable" in both.
I'll flip them public myself after I watch them.

That fires publish_to_youtube twice with an explicit privacyStatus. Being explicit is worth the extra words even though private is the default — a default you stated is a default you cannot be surprised by later. Splitting the run into two prompts is the entire technique: the reversible work is automated, the outward-facing step gets a person in front of it.

On scores: check_clips returns a viral score per clip, and this page is not going to tell you what scale it uses or invent a threshold to filter on. Ask for the highest-scoring clips, or for them sorted by score, and judge the numbers you get against each other rather than against a number you read on a blog.

Run Two: Cascade Watching a Live Stream While You Work

This is the run with no manual equivalent, because when you start it the material you want does not exist yet.

Start a ClipSpeed live session on <live stream URL>.
Check it every few minutes and tell me each time a new clip lands,
with its score. Don't stop the session without asking me first.

Step by step:

1. clip_livestream opens the session and returns a subscriptionId. Write it down, or at least keep it in the conversation — every other live call is keyed by it.
2. check_livestream polls that subscriptionId. A status of monitoring means the stream is still live and still being clipped, which is the answer you want and the one people misread as "nothing is happening". Poll in minutes. Second-by-second polling produces no clips faster and fills the context window with noise.
3. extend_livestream keeps an active session going. This is the call people forget exists and then wonder why coverage stopped mid-stream.
4. stop_livestream closes it out — with your confirmation, because you asked for that. The clips it already produced are kept and stay downloadable, so stopping is an end to the session, not a discard of the work.

Decide your stop condition before you start, out loud, in the prompt. "Stop when the stream ends, and ask me first" is a complete instruction. "I'll deal with it later" is how a session runs on while your attention is somewhere else. The live path in more depth, including what the engine is doing on the other side, is in Livestream Clipping API: Clip While You Stream.

Run Three: One Caption Style Across a Back Catalogue

The third pattern is repetition with a house style, and it is where having the agent inside your editor earns its keep — your project files are already sitting next to it.

Read urls.txt in this folder. For each URL: 1. submit it to ClipSpeed with captionStyle "cinematic" 2. wait for the clips, then record the three highest-scoring
Write the results to clips.csv as url,title,score,download_url.
Don't publish anything.

What makes this work:

1. Cascade reads urls.txt with its own file tools — not ClipSpeedAI's. That is the composition point, and it is the thing that has no equivalent outside an agent: a remote clipping server and your local filesystem in a single plan, with no glue code between them.
2. submit_to_clipspeed per URL with the same captionStyle every time. Naming the style explicitly is what stops a back catalogue looking like it was cut by six different people.
3. check_clips per projectId as results land, ranking by the score each clip carries.
4. It writes clips.csv locally — a reviewable, sortable, version-controllable artifact, which a chat transcript is not.

Add creator_pack to the loop if you want more than raw clips: it returns per-clip suggested titles, hooks and posting times for a projectId, which is the difference between having files and having a posting queue. Run ten URLs before you run a hundred — the first batch is what tells you whether cinematic was the right call for this material.

MCP for Creators: Automating Video Without Code walks this pattern for people who would rather not think about CSV columns, and AI Agent Video Automation: End-to-End Workflows extends it past the point where the clips exist.

When It Breaks: Diagnose in This Order

Ordered by how cheap the check is, not by how likely you think each cause is. Working top to bottom takes less time than guessing.

Nothing appears in the panel after you edited the config. Windsurf loads MCP config at startup and on explicit refresh, not on save. Refresh or restart. If it is still absent, the file you edited is not the file the editor reads — go back through the settings panel.

The entry is listed but errors about an unknown or missing field. Your entry does not match your build's schema. Use the panel's add-server form to generate a valid entry and then edit it, rather than adjusting the URL or the key, neither of which is implicated.

The server connects and shows zero tools. Transport succeeded, authentication failed. In near enough every case the Authorization value is missing the Bearer prefix, or a copy-paste dragged in a newline, a smart quote, or a trailing space. Retype the value by hand: Bearer, one space, the key.

Every call returns 401. Check in this order: does the key still begin csai_live_ and carry its full 48 hex characters; is that key still active on the account (a revoked key has is_active false); and are you signed into the account you think you are. GET /auth/api-keys answers all three, and last_request_at will tell you whether the server is seeing your calls at all.

Certificate or connection errors rather than HTTP errors. That is the network, not the credential. A proxy or TLS-inspecting middlebox between you and api.clipspeed.ai produces exactly this, and no amount of key regeneration touches it.

Cascade discusses clipping instead of clipping. The model did not select the tool. Either the request was ambiguous or too many MCP servers are enabled and the tool list is crowded. Name the action concretely — "use ClipSpeedAI to submit this URL" — and turn off servers this session does not need.

check_clips returns nothing right after submitting. Not an error. Clipping is asynchronous and clips arrive progressively. Wait, then check again on a minutes-scale cadence.

A live session stops producing clips. check_livestream tells you which — monitoring means it is still running. Extend before the window runs out, not after you notice it stopped.