Transcodely MCP Server

A video pipeline for AI agents, over the Model Context Protocol — 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 (15)

Fifteen tools: nine only read, four create something — three 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: 9. Writing: 6. Billable: 3.

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. Three tools start billable work — create_job, create_video_from_url and generate_captions — 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.

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. "What's the status of my last job?"
4. "Did that 1080p output actually come out as 1080p h264? Show me the measured report."
5. "I uploaded a file to my bucket and no job appeared — what happened?"
6. "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:

To land a tool-surface change:

# 1. point api-pin.json's "ref" at the release you are vendoring
# 2. read a DETACHED WORKTREE at that tag — never the shared api checkout,
#    which other sessions commit to and which sits on master
git -C ~/git/transcodely/api worktree add --detach /tmp/api-pin v5.X.0
TRANSCODELY_API_PATH=/tmp/api-pin npm run tools:sync
npm run readme:gen
git -C ~/git/transcodely/api worktree remove /tmp/api-pin
# 3. bump the version in server.json + package.json, in the same commit
npm test

Or skip step 2 entirely: with API_REPO_TOKEN set and no TRANSCODELY_API_PATH, the script clones the pinned tag itself. That is the only mode that verifies the pin, so prefer it.

The honest limitation: transcodely/api is a private repository, so the parity job needs a read token in API_REPO_TOKEN and cannot run on a pull request from a fork. When the token is absent the script exits 78 and the job reports not armed rather than passing — it never claims a parity it did not check. The always-on checks above still catch the drift that has actually bitten here: an export that moved while the README, the manifest and the bridge kept the old numbers.

Manifest

server.json is the manifest published to the official MCP registry. Its version must be bumped for a republish to take effect — the registry serves the last published version's description, so a description edit with an unchanged version is invisible.