Building an MCP Server: Making a Video Editor Safe for Other People's AI Agents

What it took to let outside AI agents safely edit a production video editor: OAuth for MCP clients, optimistic concurrency, two-call billing, jobs and responses written for a model.

Share

Giving an outside AI agent write access to a production video editor is either a feature people love or a queue of overwritten edits and surprise charges. The difference is what sits between the agent and the API.

At PuppyDog, where I work, we recently shipped an MCP server that lets Claude, ChatGPT, Cursor and Claude Code create and edit narrated product videos. It exposes more than 50 tools that change shared documents, spend credits and start jobs that run for minutes. The protocol layer was the small part. This post is about the rest.

The Problem

Each video has Versions, and each Version is an ordered list of clips with scripts, voice, zooms and overlays. People edit them in a browser editor that already has its own AI agent. The goal was simple: anything a user can do in the editor, their AI app can do too. The new caller made that hard in four ways:

  • Impatience. It fires dozens of calls a minute and repeats any that look like they failed.
  • Blindness. It can't see the screen. It only knows what the tools return.
  • Credulity. It believes what it reads, so an ambiguous response becomes a confident wrong action.
  • Company. A teammate may be editing the same Version in the browser at the same time.

Add multiple tenants and real money, and most of the design follows from those four facts.

The Solution: One Engine, Five Safeguards

The MCP server is a thin protocol layer in its own container. It checks the caller's token, filters the tool list for the workspace, rate-limits, writes an audit record and forwards each call to the main backend, which owns everything stateful: OAuth, the edit engine, billing and jobs. The MCP tools wrap the same functions the editor's own agent already used, so there is one implementation of “trim a clip”, and a fix lands everywhere at once.

A thin MCP layer in front of the engine the editor already usesBackendMCP clientClaude, ChatGPT, Cursor or Claude CodeMCP serverThin protocol layer in its own containerChecks tokens · filters tools · rate limitsWrites an audit record for every callJobs and billingEstimates, confirmation tokensJob state, long-poll statusMCP API + edit engineSame tools as the editor agentRevision-checked writesOAuth 2.1 serverDiscovery, client registrationPKCE, rotating refresh tokensWorkersRender, text-to-speech, visionReport back as jobs endBrowser editorPolls while the tab is visibleSaves local changes firstMCP over HTTP, bearer tokentool callsbrowser sign-intoken checkpolls for changesdispatch
How a request travels

1. Authorization

MCP clients discover and register themselves, so there's no per-client integration code. An unauthenticated call gets a 401 pointing at Protected Resource Metadata (RFC 9728). That leads to the authorization server's metadata (RFC 8414), Dynamic Client Registration (RFC 7591) and a browser sign-in with PKCE (RFC 7636). The user picks one workspace and approves scopes such as videos:edit. The client gets a short-lived access token and a rotating refresh token, both bound to that workspace and to the server's URL.

Third-party clients never get a first-party session, and every token is checked with the authorization server on every call, so revoking a connection takes effect immediately. The lesson from the first dev deployment: the address clients connect to, the resource URL the server advertises and the token audience must be the same string. Get the audience wrong and sign-in succeeds, then the first tool call fails with invalid_token.

2. Concurrency

Every Version carries a revision number, and every edit must name the revision it read. A mismatch returns VERSION_CHANGED with an instruction to read the video again. The browser editor uses the same guard. The counter is scoped on purpose: recording effects live outside the clip list, so editing them doesn't bump it. Writes that don't depend on each other shouldn't invalidate each other.

Edits go through the editor's own save path, so they show up in its history. Every edit returns a change ID, and undo is refused if a later change touched the same clips, instead of guessing at a merge. An open editor polls for outside changes while its tab is visible, saves its own work first and asks the user to reload on a real conflict.

3. Billing

Every paid tool takes two calls. The first returns an estimate and a confirmation token and changes nothing. The second repeats the call with the token, which works once and expires after ten minutes. Retries are the subtle part: a client that times out will resend the same token, and the right answer is the job the first call started, not “already used”. That takes explicit states, not a plain nonce.

Fan-out is bounded and atomic. A script edit re-narrates up to 20 clips in one call and is charged as one action. If credits run out or the Version changes midway, nothing is saved and nothing is charged.

4. Long-Running Work

Anything that can take more than about ten seconds returns a job ID, and get_job long-polls for up to 20 seconds. A job ends done, failed (with whether credits were charged) or waiting on the user. That last state lets an agent pause to ask a question or show a plan before spending anything.

Timeouts need the same care. At first, backend calls timed out after ten seconds, and slow ones returned “unavailable, may have been saved” while the backend went on to save the edit anyway. The model had no change ID to undo and no idea what had happened. Timeouts should return state, not guesses.

5. Responses Written for a Model

The model acts on every word, and most of these rules came from watching it:

  • Facts, not orders. A test prompt asking Claude to post a video to YouTube exposed an ambiguous render description. It now says it makes an MP4 and posts nothing anywhere.
  • Say when nothing happened. Edit tools that returned a normal summary for a no-op led the model to report success. They now answer “Nothing changed”.
  • Treat user content as untrusted. Scripts and overlay text are flattened and capped in the text part of a result.
  • Errors name the next step. VERSION_CHANGED comes with “read the video again”, not just “conflict”.

One gotcha: clients cache the tool list, so testing a wording fix starts with a reconnect.

Testing: An LLM as One of the Runners

Three layers, each catching what the one below it can't.

LayerWhat it coversLatest result
Automated suitesBackend regression across every MCP phase and billing contract; the MCP server; the editor231 backend suites, 572 MCP server tests (three clean runs in a row) and 1,766 editor tests, all passing
Local end-to-endA real MCP server and backend driven through connect, create, edit and render63 of 63 checks; no token material in either log
LLM acceptanceClaude, connected through the real connector, runs a written plan against a local stack61 of 68 steps pass; 5 not applicable or not yet available; 2 under investigation, likely environment-specific

The last layer is the interesting one. Claude, connected through the real connector, works through a 68-step plan written for a model. It marks each step pass, fail or blocked and cites job and change IDs as evidence. Some steps test comprehension, such as quoting a tool's description word for word to prove what the client actually loaded. It found bugs the unit tests had missed, including PDF pages coming back out of order, and every wording problem above.

How It Was Built

Most of the code was written with Claude Code across three repositories: the backend, the MCP server and the editor. A few habits made that work:

  • One workstream per session. Implementation, the test plan, follow-ups and infrastructure each had their own context.
  • Subagents for bounded jobs. One removed 70 import cycles flagged by a new check, without adding a single exception.
  • Guardrails on every change. Lint, cycle checks and mutation testing ran on everything, and CI failures were fixed back on the branch.
  • Humans own the judgment calls. Agents asked before changing any test that encoded old behaviour.

Security hardening shipped first, before any outside client could connect.

Future Implications

The mental model that held up best: the model is the API's primary user, and the tool descriptions and responses are its entire interface. It can't see the screen, so the text is the screen.

Two predictions I'm fairly confident about. MCP servers will be judged less on how many tools they expose and more on how unambiguous their responses are. And running acceptance plans through a model will become a normal step in shipping any API that agents call, because a model is the only reviewer that reads tool descriptions the way the real caller does.

The server is in beta now. If you're building one, I'd be glad to compare notes.