Transcodely

Transcodely MCP Server

A video pipeline for AI agents, over the [Model Context Protocol](https://modelcontextprotocol.io) — with nothing on it that can delete your work.

Hand your agent a video URL and it comes back a playable link: transcoded into an ABR ladder, hosted, captioned if you ask. Then let it read back what it actually produced, what it cost, and why an upload did not become a job. No delete, no cancel, no key material. Connect with one OAuth click — no API key to create or paste.

• Server URL (streamable HTTP): https://mcp.transcodely.com/mcp
• Product page: https://www.transcodely.com/mcp
• Connect guide: https://www.transcodely.com/docs/guides/mcp
• Registry identifier: com.transcodely/mcp

This is the public home of the hosted server: connect instructions, the tool surface, and the registry manifest. The server itself is a hosted service — there is nothing to install or run.

Connect

Claude Code

claude mcp add --transport http transcodely https://mcp.transcodely.com/mcp

Then run /mcp inside Claude Code and pick Authenticate — your browser opens, you approve, and the tools are live. No Transcodely account yet? One is created for you during authorization.

claude.ai / Claude desktop — Settings → Connectors → Add custom connector → https://mcp.transcodely.com/mcp.

Cursor — add to ~/.cursor/mcp.json:

{

"mcpServers": { "transcodely": { "type": "http", "url": "https://mcp.transcodely.com/mcp" } } }

Any other client that supports remote MCP servers over streamable HTTP works the same way. For headless use (CI, server-side agents), attach a Transcodely API key as a bearer token instead — see the connect guide.

Tools (20)

Twenty tools: twelve only read, six create something — five of those start work you are billed for, and saving a preset is free — and two overwrite a setting that only affects work created after it. No tool on this surface deletes, cancels, removes or rotates anything.

*Generated from tools.json by npm run readme:gen — do not edit by hand. Read-only: 12. Writing: 8. Billable: 5.*

What the surface cannot do

The promise is narrow and literal, and it is checked rather than asserted: test/vendored.mjs re-derives it from tools.json on every CI run and fails if a future release adds a tool whose name begins with delete, cancel, remove, purge, rotate or destroy.

• Nothing is deleted or cancelled. No tool removes a video, a job, an output, a preset or a rule, and none stops work that is already queued or running. An agent that decides mid-task to "clean up" has no instrument for it.
• Nothing reads key or secret material. There is no tool for API keys, and the ingest tools deliberately withhold even the prefix-and-last-four hint the REST API exposes: a rule's inbound secret is shown once, at creation, and never by this server. A tool result lands in an agent transcript, so anything a transcript should not carry is not on the surface at all.
• Nothing reaches your organization. Members, plans, invoices, team settings and the admin surface have no tools.
• The overwriting pair only ever reaches forward. update_preset and set_spend_limit carry destructiveHint: true, which in the protocol means "replaces a value" rather than "additive" — not that anything is removed. A preset is read and expanded when a job is *created*, so editing one never reaches a job that already exists; lowering a spend limit blocks the *next* job and never stops one in flight.

Who can change the spend limit

set_spend_limit is the only tool with an authorization rule of its own, because it is the only one that moves money policy.

• It requires an organization owner or admin, signed in through the browser OAuth flow. That is the same membership check the REST API applies, plus one rule REST does not have.
• API-key sessions are refused outright — including the stdio bridge below, which authenticates with ak_…. The refusal says so in words rather than failing as a generic permission error. This surface is deliberately stricter than REST here: over REST, a key can manage its own app's limit.
• It reads the limit back instead of echoing what it was given: a limit set above a plan or platform ceiling stores fine and changes nothing, because the lower ceiling still binds. The result carries the previous and the new *effective* limit and the rung it comes from.

Auth and guardrails

• OAuth 2.1 with PKCE via browser consent; the server implements RFC 9728 Protected Resource Metadata and RFC 8707 resource indicators.
• Every tool call is scoped to one Transcodely app, resolved from the session, never from a tool argument. An agent cannot widen its own scope by passing a different id: a job, video, preset or rule belonging to another app reads back as *not found* rather than as a permission error, which would confirm it exists. Connect to https://mcp.transcodely.com/mcp/app_… to pin a specific app; the bare URL resolves to your organization's oldest active app.
• An ak_… key presented at a different app's URL is rejected outright.
• Every call writes the same audit trail as the equivalent REST call.
• The MCP server is free to connect. Five tools start billable work — create_job, create_video_from_url, generate_captions, generate_insights and generate_highlights — charged at the ordinary Transcodely rates. Every other tool is free to call, including the ones that write: saving a preset or setting a spend limit costs nothing. create_video_from_url deletes the original source file 7 days after the video is ready unless you pass retain_source; a retained source is billed as storage and appears on the invoice as "Retained source videos".

Try it

1. *"Transcode and host this video and give me a link: https://www.transcodely.com/videos/bbb-30s.mp4"*
2. *"Generate English captions for that video."*
3. *"Generate insights for that video, then cut highlight clips from it."*
4. *"What's the status of my last job?"*
5. *"Did that 1080p output actually come out as 1080p h264? Show me the measured report."*
6. *"I uploaded a file to my bucket and no job appeared — what happened?"*
7. *"How much have I spent on video this month, and which day cost the most?"*

Run locally (stdio bridge)

Remote-capable clients should connect straight to the hosted endpoint above — that's the one-click OAuth path. For stdio-only clients, sandboxes, and headless use, this repo is also a runnable bridge that serves the same tools over stdio and forwards calls to the hosted server:

# with an API key (create one in the Transcodely dashboard):

TRANSCODELY_API_KEY=ak_... npx github:transcodely/mcp

or via Docker:

docker build -t transcodely-mcp . docker run -i --rm -e TRANSCODELY_API_KEY=ak_... transcodely-mcp

Without TRANSCODELY_API_KEY the bridge still starts and answers introspection (initialize, tools/list); tool calls return an error pointing at the two auth paths. set_spend_limit is listed but always refused over this path — see the rule above.

How tools.json is kept honest

tools.json is generated, not written: it is the byte-exact stdout of the Transcodely API's own export, go run ./cmd/mcp --dump-tools, run in a checkout of the release pinned in api-pin.json. The README table above is generated from it in turn. Two checks hold that chain:

| Vendored consistency — counts, annotations, the "nothing deletes" promise, manifest versions, the R