ClipSpeedAI MCP for Codex CLI: HTTP Setup and Tool Reference

Codex CLI reaches ClipSpeedAI the way it reaches any remote MCP server: one HTTPS endpoint, one header, nothing installed locally. The endpoint is https://api.clipspeed.ai/mcp, it speaks streamable HTTP, and command-line clients authenticate with Authorization: Bearer <API_KEY>. Once that connection is live, ten ClipSpeedAI tools show up in Codex's tool list, and an agent can go from "find something recent worth clipping" to a private YouTube upload without you opening a browser tab.

Support tier for Codex CLI: COMPATIBLE. It uses the same transport and the same auth pattern as the clients ClipSpeedAI has verified end to end — Claude (claude.ai), Claude Code, Claude Desktop and Windsurf — but ClipSpeedAI has not run its own verification pass against Codex CLI. The server side is the same server side. The client side belongs to Codex.

That asymmetry shapes this page. It is exact about the parts ClipSpeedAI controls: the URL, the header, the key format, the ten tool names, the six caption template ids. It deliberately does not print a Codex CLI config file, because ClipSpeedAI does not own that format — guessing at someone else's key names is how you lose an evening to a typo that the vendor's own documentation would have settled in ten seconds. Where Codex's syntax is needed, this page describes the shape of the thing you are looking for and sends you to Codex's docs for the spelling.

Three Values Are Ours. The Rest Belongs to Codex.

Whatever Codex CLI's current mechanism for registering an MCP server looks like, it will need these three things and no more:

What you are hunting for in Codex CLI's documentation is: a way to declare an HTTP MCP server, a field that holds its URL, and a way to attach a fixed header to every request it sends. Fill those three slots with the values above. The file location, the section names, the header syntax, and whether servers are added by a subcommand or by hand-editing — all of that is Codex's, it changes on Codex's release schedule, and it is not ClipSpeedAI's to specify. Read their MCP documentation for the exact spelling.

One config block is safe to print, because ClipSpeedAI verified it end to end. This is the same three values expressed as a single command on a different client:

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

Keep that around even if Claude Code is not your daily driver. Same URL, same key, different client: if the key works there and fails in Codex, you have localised the fault to Codex-side syntax in about thirty seconds. ClipSpeedAI MCP for Claude Code: Complete Setup Guide walks that path properly.

After any edit, restart Codex CLI. MCP clients generally read their server configuration when the process starts, so an edit applied to a running session usually does nothing except confuse you.

What You Need in Place First

• A Codex CLI that already works. Confirm it completes an ordinary turn before you add an MCP server. Two unknowns at once turns a five-minute setup into an afternoon.
• A paid ClipSpeedAI account. No tier is free. One dollar, charged once, opens a three-day trial; leave it alone for those three days and it converts to whichever tier you picked. Starter is $15 a month, Pro $29, Ultra $49, each roughly halved if you pay for a year up front. Separately there is a single free demo run, capped to a source video shorter than half an hour — that is a taste of the output, not something an agent loop can live on.
• An API key, generated from your account. Format and lifecycle are covered a few sections down.
• Outbound HTTPS to api.clipspeed.ai. Corporate proxies, split-tunnel VPNs and egress allowlists are a common reason a server reads as configured and never connects.

Nothing needs installing for this path. There is no Node.js requirement, no local binary, no daemon. An npm package named clipspeed-mcp exists (v1.0.0, published 2026-07-10) but it is not part of the HTTP setup described here, and this page makes no claims about how it is built.

The Cheapest Possible First Call

Resist the urge to open with a real clipping job. A failed first job tells you almost nothing, because it could have failed at the config, the key, the network, the tool name, or the video. Walk up the ladder instead.

1. Is the server listed and connected? Use whatever command Codex CLI provides for showing configured MCP servers. "Present" is not the same as "connected" — look for the second one.
2. Did the tools load? Ask the agent to name the ClipSpeedAI tools it can call. You want ten. If you see fewer than ten, the connection did not complete — recheck the URL and the header before doing anything else.
3. Make one read-only call. Ask it to call list_templates and print the result. That exercises auth, transport, tool dispatch and response parsing in a single request, and it does not start any work.

A correct list_templates response comes back with six caption-style ids: karaoke, hormozi, beasty, fire, youshaei, cinematic. Seeing those six is your proof that the whole chain is real — the key is valid, the account is active, and Codex is talking to the right server.

What Codex Is Actually Doing on the Wire

If you have used MCP only as a checkbox in a client, the mental model that helps most is this: MCP gives a model the equivalent of --help for software it has never seen, in a form it can act on rather than read.

When Codex CLI starts a session against api.clipspeed.ai/mcp, it opens the connection and asks the server what it can do. The reply is a catalogue. For each capability there is an identifier the model must spell exactly, a sentence describing when reaching for it is appropriate, and a JSON Schema stating what arguments it accepts. Codex hands that catalogue to the model as available actions. The model emits a choice; Codex performs the actual HTTP call; the server's answer comes back as structured content the model can reason over on the next turn. The model never sees your key, never opens a socket, and never parses HTML.

The reason this matters commercially rather than just aesthetically: before MCP, connecting a clipping engine to an agent meant somebody writing an adapter for that specific model and that specific harness. Every new client meant another adapter, and every schema change meant updating all of them. Under MCP the same ten definitions are consumed unchanged by Codex CLI, by Claude Code, by Claude Desktop. ClipSpeedAI ships one server, and you can carry a workflow between terminals without relearning anything except the config file. What Is MCP? Model Context Protocol Explained is the ground-up version of this. How MCP Servers Work: Architecture and Request Flow goes deeper into session negotiation and the call round trip.

Two comparisons are worth having in mind if you are deciding how to expose your own service. MCP vs REST API: When to Use Each covers when a protocol layer earns its keep over a plain HTTP interface. MCP vs Function Calling: What Actually Differs handles the more common confusion, which is that MCP is transport and discovery, not a replacement for the model's ability to call a function.

Dialed, Not Spawned — and Why That Means a Bearer Header

An MCP client reaches a server one of two ways. It either launches a process on your machine and talks to it over stdio, or it dials a URL over HTTP. Codex dials. ClipSpeedAI's server is remote and there is no local mode to switch into.

That follows from what the product does. Turning a long recording into scored, captioned, vertical clips means downloading it, transcribing it, scoring segments, reframing to 9:16 with speaker tracking, burning captions in, and encoding — repeatedly. None of that belongs inside a CLI subprocess on a laptop. Your agent sends a URL and receives structured results; the pipeline runs on ClipSpeedAI's side. Remote MCP vs Local MCP Servers maps out where that boundary usually falls.

Two practical consequences. Network reachability is a hard dependency: no route to api.clipspeed.ai means no tools at all, no matter how correct your config is. And the unit of retrieval is an identifier, not an open connection — check_clips takes a projectId, so asking for results is a separate call from starting the work.

Auth follows the same fork. GUI clients that can run a browser consent flow use OAuth: on claude.ai you add ClipSpeedAI as a connector, approve it, and no key ever lands in a file — ClipSpeedAI MCP for Claude (claude.ai): Complete Setup Guide covers that flow. Command-line and config-file clients, Codex CLI among them, send a static key in the Authorization header on every request. The generic trade-off is the familiar one: a browser-negotiated credential is managed for you by the client, while a static key is a string you are responsible for storing, scoping by habit, and replacing. MCP Authentication: OAuth and Bearer Keys compares the two properly. For a terminal, the static key is simply the option that works without a browser.

Keys: Format, Listing, and Revocation That Sticks

Generate a key at Account → API & Integrations → Generate API Key (the same thing the API exposes as POST /auth/api-keys).

The format is specific and worth knowing, because it makes keys recognisable in logs and diffs: csai_live_ followed by 48 hexadecimal characters. Those 48 characters are 24 random bytes rendered as hex. A key is displayed once, at creation. ClipSpeedAI stores only the first 18 characters for display purposes — the csai_live_ prefix plus the first eight hex characters, shown with an ellipsis — so there is no screen anywhere that will show you a full key again. Copy it when it appears or generate another one.

That 18-character detail is directly useful. Print exactly that much of whatever is in your environment and you can match a shell against a row in the dashboard without exposing the rest:

# Store the key in your shell profile, never in a repo
echo 'export CLIPSPEED_API_KEY="csai_live_<48 hex chars>"' >> ~/.zshrc
source ~/.zshrc # Print only the stored prefix — this is what the dashboard shows
echo "${CLIPSPEED_API_KEY:0:18}..."

GET /auth/api-keys lists your keys with their id, name, key_prefix, plan, rate_limit, requests_today, total_requests, last_request_at, is_active and created_at. Two of those fields turn key management from guesswork into observation. last_request_at tells you which key an agent is actually presenting — useful when you have one per machine and cannot remember which laptop you set up in March. is_active tells you whether a key is still valid at all, which is the first thing to check when every call starts failing.

Revocation is real, not advisory. DELETE /auth/api-keys/:id sets is_active to false and stamps revoked_at; the key stops working. That means the correct response to a suspected leak is to revoke the specific key, not to hope. Keys also carry a per-key rate_limit alongside running request counters, so a runaway agent on one machine is contained to the key it holds.

Naming discipline pays off here: one key per machine, named after the machine. Rotation then costs you one revoke and one config edit on one box, instead of an outage across every environment that shares a single key.

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, Grouped by the Job They Do

These names are exact. An agent that invents one gets an error, and the fix is always to put the real list in front of it. The arguments each tool accepts are advertised by the server itself when Codex connects — read that schema rather than trusting any prose description, including this one.

Finding something to cut

• discover_trending — finds the fastest-growing recent video in a niche to turn into shorts. It searches only videos published in roughly the last three weeks, which makes it a recency instrument rather than an archive search.

Starting work

• submit_to_clipspeed — drops a video URL, or a file, into ClipSpeed. This is the clip button.
• clip_livestream — live mode. Clips a stream in real time and returns a subscriptionId.

Reading state

• check_clips — for a projectId, returns the finished, scored, captioned 9:16 vertical clips, each with a title, a viral score and a download URL.
• check_livestream — polls a live session by subscriptionId. A status of monitoring means the stream is still live and still being clipped.

Steering a live session

• extend_livestream — extends an active session.
• stop_livestream — stops a session by subscriptionId. Clips already produced are kept and remain downloadable.

Dressing and shipping

• list_templates — lists the caption-style templates. Also the cheapest possible connectivity check.
• creator_pack — for a projectId, returns per-clip suggested titles, hooks and best posting times.
• publish_to_youtube — publishes a finished clip to YouTube. Takes a projectId, and optionally a clipId, a title and a privacyStatus. It defaults to private.

Notice the split between tools that start work and tools that read it. submit_to_clipspeed and clip_livestream hand back an identifier; check_clips and check_livestream take one. A tool call that blocked for the duration of a full render would sit past client timeouts and give the model nothing to think about in the meantime, so long-running work is conventionally split this way. MCP Tool Design: Writing Tools an Agent Can Actually Use gets into why that shape is worth copying if you are building your own server.

About the viral score: check_clips returns one per clip. This page will not tell you its range or where a good clip sits, because that is not documented here. Sort by it, compare clips within a project, and calibrate against your own eyes before you write a threshold into a prompt.

Six Caption Styles, One Argument

Caption styling is the one aesthetic choice the MCP surface exposes, and it is a closed set. list_templates returns exactly six ids:

karaoke
hormozi
beasty
fire
youshaei
cinematic

Pass the chosen id as captionStyle. That is the whole contract — there is no free-text style field and no font or colour parameter on this surface.

Two habits are worth forming. First, have the agent call list_templates before it submits anything in a session where style matters, rather than recalling an id from its own memory; the call is free and it prevents a plausible-sounding invented id from reaching the server. Second, for a batch, decide the style once and state it in the instruction. A channel where every third clip has different caption treatment reads as a channel that is not paying attention, and this is the cheapest possible place to be consistent.

Run One: A Three-Week Window, One Short, One Approval

The everyday loop, built around the constraint that makes discover_trending distinctive — it only looks at videos published in roughly the last three weeks. You are not searching a library. You are asking what has moved lately in a niche, which is exactly the question a shorts pipeline needs answered.

Call discover_trending for the GTA niche and tell me which
video you picked and why before you do anything else.
Then call list_templates and use the hormozi style.
Submit the video, poll check_clips, and show me every clip
with its title and viral score. Do not publish anything yet.

What runs, in order:

1. discover_trending returns recent, fast-growing candidates in that niche.
2. The agent states its pick. Making it announce the URL before submitting is the difference between a workflow you can audit and one you have to reconstruct afterwards.
3. list_templates, then submit_to_clipspeed with the source and the chosen captionStyle. You get back a project identifier.
4. check_clips, polled. Rendering takes real time on a long source. Tell the agent to wait between polls rather than spinning. That framing and captioning happens inside the pipeline; there is no separate step for you to call.
5. Optionally creator_pack on the same projectId for per-clip title suggestions, hooks and posting times — useful when you would rather compare three title options than write one from scratch.

Publishing gets its own turn:

Publish clips 2 and 4 with publish_to_youtube.
Leave privacyStatus at its default. Report the result
for each one separately.

publish_to_youtube defaults to private, which is a genuinely useful default for agent work: the clip lands on the channel, you review it in YouTube Studio, and going public stays a human action taken in a human interface. If you override privacyStatus in a prompt, you have removed that safety net on purpose — do it knowingly. AI Agent Video Automation: End-to-End Workflows takes this loop further.

Run Two: A Live Session You Poll Instead of Watch

This is the workflow that is genuinely painful by hand, because the manual version requires a human present for the whole broadcast with a finger on a clip button.

Start a live session on this stream with clip_livestream and
tell me the subscriptionId it returns. Check it with check_livestream every 10 minutes. While the
status is still monitoring and the session is close to ending,
call extend_livestream — at most twice, then stop. When the stream is over, call stop_livestream, then pull the
clips and rank them by viral score.

The mechanics: clip_livestream returns a subscriptionId and clipping begins while the broadcast is still running. check_livestream takes that id; a monitoring status means the stream is live and being clipped, which is your signal to keep going. extend_livestream extends a session that is still active — it is not a resurrection tool, so the call has to land before the session ends. stop_livestream closes it cleanly, and clips already produced are kept and remain downloadable afterwards.

The cap on extensions is the important line in that prompt. An agent told to extend whenever the stream is still live, with no ceiling, is an unbounded loop you have authorised in advance. State a maximum every time.

One caution: a live session and a recorded submission are different tool paths with different identifiers and different lifecycles. Do not assume that timing, polling cadence or behaviour you learned on one carries over to the other. Livestream Clipping API: Clip While You Stream is the dedicated treatment.

Run Three: A URL List, a Project Log, and a Second Session

Here is where a terminal client beats a web interface outright, because the agent already has a filesystem and a shell. Split the work into a submit pass and a collect pass.

Read urls.txt. For each line, call submit_to_clipspeed with
captionStyle "cinematic". Append the returned project id and
the source URL to projects.tsv, one per line, as you go.
Do not poll for completion. Stop and report if any
submission returns an error.

Then, later:

Read projects.tsv. For each project id, call check_clips.
Build a markdown table: source URL, status, clip count,
highest viral score. Mark anything still processing so I
can re-run this on just those rows.

The reason these are two prompts rather than one is structural: check_clips is keyed on a projectId, so retrieval is an independent call that does not have to happen in the same breath as submission. Write those ids to disk as they arrive. Conversational context is not durable storage, and an agent reconstructing an identifier from memory will produce something that looks like an id and is not one. How long a project stays retrievable is server-side behaviour that this page does not promise — confirm it against your own retention needs before you build a pipeline that depends on collecting results days later.

Two refinements. Pin captionStyle explicitly in the batch instruction rather than letting each submission drift. And once results are in, creator_pack on the highest-scoring projects gives you titles, hooks and posting times in one call instead of prompting for each piece separately. MCP for Video Editing and Clipping Workflows covers batch-shaped editing work in more depth.

Diagnostics, Cheapest First

Work down this list in order. Each step is cheaper than the one after it and rules out a whole class of cause.

1. Can you reach the host at all?

curl -sS -o /dev/null -w '%{http_code}\n' \ https://api.clipspeed.ai/mcp

Read this as a reachability probe and nothing more. Any HTTP status coming back — including a 4xx or a 405 — means DNS resolved, TLS completed and your request reached the server, which is all you are testing for. A hang, a connection refused, or a TLS error points at a proxy, a VPN split tunnel, or an egress rule, and no MCP configuration will fix that.

2. Did you restart Codex CLI? Server configuration is read at client startup. Quit the process fully and relaunch — a new tab inside the same running process is not a restart.

3. Is the header shaped correctly? The value is the literal word Bearer, one space, then the key. The recurring mistakes are a missing Bearer prefix, a trailing newline captured when the key was copied, and quotation marks pasted along with the value. Print the first 18 characters of what your config actually contains and compare it to the key_prefix shown in your account.

4. Is the key still active? Check the key list under Account → API & Integrations. If is_active is false the key was revoked and every request will fail regardless of how the client is configured. last_request_at also tells you whether requests are arriving at all — if it never advances, nothing is reaching the server with that key.

5. Does the same key work on a verified client? Configure Claude Code with the identical URL and key using the command above. If it works there and not in Codex, the fault is Codex-side syntax and you should compare your setup against Codex CLI's current MCP documentation rather than anything on this page.

6. Is the agent inventing tool names? Models produce plausible ones — get_clips, create_clip, upload_to_tiktok. None exist. Paste the real ten into the prompt and instruct the agent to use only those; this usually settles it.

7. Does a project seem stuck? Separate two cases. If check_clips reports a processing state, the work is running and long sources take time. If it errors or reports an unknown project, the identifier is wrong — go back to what submit_to_clipspeed actually returned instead of letting the agent regenerate it.

8. Confirm you are publishing from a project that finished, check the clipId refers to a clip that exists in that project, and read the error text the tool returns rather than inferring a cause.

9. Did a live session end before you expected? Sessions end, and extend_livestream only works while one is active. Once it has closed you start a new session; the interval in between is not recoverable. Clips already produced remain downloadable.