A
licenseB
qualityB
maintenanceAgent-native media processing: video encoding, image manipulation, document conversion, audio transcription, and more via 86+ cloud Robots.
7
73
MIT
Transcodely
Officialby transcodely
Transcodely is an MCP video pipeline server that lets you transcode, host, caption, inspect, and manage video jobs and presets — with no deletion or cancellation tools.
Create transcoding jobs from gs://, s3://, or https:// sources with configurable outputs, presets, codecs, resolutions, and quality tiers.
Ingest and host a remote https:// video in one call, producing an ABR ladder and a durable player link.
Generate AI captions/subtitles for hosted videos, idempotently per video+language.
Check job status, list jobs, and poll until completion.
Retrieve hosted video details, renditions, playback URLs, and measured output reports.
Get monthly usage and cost breakdowns (encoding, storage, egress, requests).
Manage custom encoding presets (create/update/list) and list platform presets.
View and manage ingest rules that turn storage events into jobs, including ingest event logs.
Set or clear a monthly spend limit (owner/admin only via OAuth; refused for API-key sessions).
Read-only tools dominate; no tool deletes, cancels, removes, or reads key material.
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/mcpProduct 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/mcpThen 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.
Related MCP server: Botverse
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.
Tool | Effect | What it does |
| creates work · billable | Create a transcoding job. |
| creates · free | Create a custom encoding preset for this app: a named, reusable bundle of encoding settings that create_job can reference by slug. |
| creates work · billable | Ingest a remote https:// video and host it in one call — this is the tool for "transcode and host this, give me a link". |
| creates work · billable | Generate AI captions (subtitles) for a hosted video by id (vid_...). |
| read | Fetch one ingest rule by id (ing_...): its origin, enabled state, filters, the job it submits, and its event/job counts. |
| read | Get a concise status snapshot for a transcoding job by id (job_...): overall status and progress, any error code/message, and per-output status/progress with errors. |
| read | Get the full measurement report for one job output (job_... plus out_...): what the produced file turned out to BE, measured from the written file, and the verdict of comparing that against what the job asked for. |
| read | Return hosting usage and cost for a billing month: videos encoded, encoding minutes, average storage, egress, request counts, and per-line and total cost in EUR. |
| read | Fetch a hosted video by id (vid_...): status, visibility, title, duration, poster image, encoded renditions (resolution, codec, bitrate, dimensions), and — once status is "ready" — a playback block. |
| read | List the storage deliveries this app's ingest rules received, newest first, with what became of each: the bucket and object key, the outcome (received, matched, created, skipped or failed), the REASON for a skip or failure, and the job id when one was created. |
| read | List this app's ingest rules: the standing instructions that turn an object landing in a storage origin into a transcoding job. |
| read | List transcoding jobs for the authenticated app, newest first. |
| read | List the encoding presets available to this app: the read-only ones the platform ships and the app's own custom ones. |
| overwrites a setting | Set or clear this app's monthly transcoding spend limit, in EUR. |
| overwrites a setting | Update a custom preset's settings by id (pst_...). |
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_presetandset_spend_limitcarrydestructiveHint: 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_urlandgenerate_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
"Transcode and host this video and give me a link: https://www.transcodely.com/videos/bbb-30s.mp4"
"Generate English captions for that video."
"What's the status of my last job?"
"Did that 1080p output actually come out as 1080p h264? Show me the measured report."
"I uploaded a file to my bucket and no job appeared — what happened?"
"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-mcpWithout 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:
Check | Command | Runs |
Vendored consistency — counts, annotations, the "nothing deletes" promise, manifest versions, the README naming every tool |
| every push and PR |
The bridge serves exactly the vendored surface, keyless calls guide |
| every push and PR |
The README table is regenerated from |
| every push and PR |
|
| when a token is available — see below |
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 testOr 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.
Available Tools
7 toolscreate_jobAInspect
Create a transcoding job. Reads a source video from a URL (gs://, s3://, or https://) and produces one or more output renditions. Outputs are written to a storage origin you own (pass output_origin_id); to produce a hosted, playable video instead, use create_video_from_url. Returns the job id, status, and a per-output pricing/status summary. Validation (codec x container compatibility, limits, required fields) is performed server-side and surfaced as a machine-readable error.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| preset | No | Preset applied to every output as a base (id like pst_xxx or slug like gaming_1080p_60_standard). Per-output fields override it. | |
| outputs | Yes | Output renditions to produce (1-10). | |
| metadata | No | Arbitrary string key/value pairs echoed back on the job. | |
| priority | No | Scheduling priority: economy, standard (default), or premium. Does not affect cost. | |
| input_url | Yes | Source video to transcode. Supported schemes: gs:// (Google Cloud Storage), s3:// (S3-compatible), https://. | |
| webhook_url | No | HTTPS endpoint to receive job lifecycle webhook events (job.completed, job.failed, ...). | |
| output_origin_id | No | Storage origin (ori_...) to write outputs to. Required unless the job targets managed hosting; a job without it is rejected with output_origin_id required. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| object | Yes | |
| status | Yes | |
| outputs | Yes | |
| currency | Yes | |
| video_id | No | |
| created_at | Yes | |
| total_estimated_cost | No |
TDQS
A4.4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide destructiveHint=false and a title, so the description carries the behavioral burden. It adds useful context: outputs go to a user-owned origin, validation is server-side, errors are machine-readable, and the response includes job id, status, and per-output pricing/status. It stops short of explicitly stating asynchronous job behavior, but the notion of a job plus webhook events implies it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each earning its place: what the job does, where outputs go, how to choose the alternative tool, and what the caller receives. Front-loaded with the core purpose and free of fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, nested output objects, and an output schema, the description covers the essential operational context: input schemes, destination requirement, alternative path, return summary, and error behavior. The output schema handles return values, and the schema handles parameter details. A brief note on asynchronous execution would make it fully complete, but the current text is strong.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents every parameter thoroughly. The description reinforces key semantics like supported URL schemes and output_origin_id being required, but does not add new meaning beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a transcoding job') and clearly distinguishes itself from the sibling create_video_from_url by contrasting storage-origin outputs with hosted playable videos. The description also names the input source and output behavior, making the tool's scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use create_video_from_url when a hosted, playable video is desired instead of outputs written to a storage origin. This gives the agent a clear decision rule between two similar creation tools. It also notes that output_origin_id is required for this path, which guides correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_video_from_urlAInspect
Ingest a remote https:// video and host it in one call — this is the tool for "transcode and host this, give me a link". Downloads the URL, transcodes it into an adaptive streaming ladder, and returns a hosted video (vid_...) with status "processing". The URL must be publicly reachable over http(s); private/internal targets are rejected (SSRF protection). Visibility follows the app's hosting default, "unlisted" when the app has not set one (playable by anyone with the link, not listed publicly). Enables managed hosting for the app on first use — a one-way change, after which hosted storage and egress bill at the standard rates. To finish the job: poll get_video with the returned id every ~10s until status is "ready" (typically under a few minutes for a short clip), then give the user playback.player_url — that is the durable, clickable link.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Publicly reachable https:// source video to ingest. Private/internal hosts are rejected (SSRF protection). | |
| tags | No | Freeform tags to attach to the video. | |
| title | No | Display title for the hosted video. | |
| preset | No | Preset (id like pst_xxx or slug) driving the transcode. Omit to use the app's default adaptive ladder. | |
| visibility | No | Access level: public, unlisted, or private. Omit to use the app's hosting default visibility (unlisted if the app has not set one). | |
| description | No | Longer description for the hosted video. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| tags | No | |
| title | No | |
| job_id | No | |
| object | Yes | |
| status | Yes | |
| playback | No | Where to watch this video. Present once status is "ready"; absent while it is still processing. Contains player_url (durable page to hand a human, public/unlisted only) and hls_url with expires_at (short-lived manifest for your own player). |
| ready_at | No | |
| created_at | Yes | |
| poster_url | No | |
| renditions | Yes | |
| visibility | Yes | |
| description | No | |
| encoding_cost | No | |
| duration_seconds | No | |
| output_storage_prefix | No |
TDQS
A4.4/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses important behavioral traits: SSRF protection rejects private/internal URLs, the video starts in 'processing' status, visibility defaults to 'unlisted' if unset, and first use enables managed hosting — a one-way change with billing implications. This is valuable side-effect transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then explains limitations, side effects, and the follow-up flow. It is longer than strictly necessary and somewhat redundant with the schema, but each sentence carries useful operational information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with six parameters, an output schema, and impactful side effects, the description is complete: it covers the workflow, prerequisites, security constraints, status lifecycle, billing implications, and how to obtain the final playback link. The output schema handles return-shape details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all 6 parameters with 100% coverage. The description adds some context around defaults like visibility and preset behavior, but largely repeats what the schema says rather than providing substantial new parameter-level meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a specific verb and resource: ingest a remote https:// video, transcode it, and host it in one call. It explicitly labels itself as the tool for 'transcode and host this, give me a link', distinguishing it from siblings like create_job and get_video.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear when-to-use context, including the specific use case and the required precondition that the URL be publicly reachable. It also explains the follow-up workflow with get_video, but it does not explicitly contrast itself with sibling tools like create_job or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
generate_captionsAIdempotentInspect
Generate AI captions (subtitles) for a hosted video by id (vid_...). Creates a billable captions job: speech is transcribed into a WebVTT subtitle track in the given language (default "auto" to detect the spoken language), attached to the video when the job completes. Billed per source minute; the fee is only charged when a caption track is actually delivered. Idempotent per video+language: repeating the call returns the existing job instead of creating and billing a new one.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | ISO 639-2 language code for the captions (e.g. eng, spa, bul). Defaults to "auto" to detect the spoken language. | |
| video_id | Yes | Hosted video id to caption (vid_...). |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| job_id | No | |
| status | No | |
| language | No | |
| video_id | No |
TDQS
A4.5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the annotations: it creates a billable job, billing is per source minute and only charged on delivery, the track is attached on completion, and the operation is idempotent per video+language. This is excellent disclosure of side effects and cost implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-structured: main purpose first, then billing, then idempotency. Every sentence adds distinct value without redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for correct invocation: it identifies required input, default behavior, output attachment, billing conditions, and idempotency. With annotations and an output schema present, nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents video_id and language. The description reinforces the language default and auto-detection behavior, but doesn't add much new parameter-level meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Generate') and resource ('AI captions for a hosted video by id'), and differentiates from siblings by specifying the WebVTT subtitle track output and billable captions job nature. This makes it easy to distinguish from generic tools like create_job or get_video.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly establishes when to use the tool: to generate subtitles for a hosted video identified by vid_..., with language auto-detection. It doesn't explicitly name alternatives or state when-not-to-use, but the usage context is unambiguous and sufficiently distinct from the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_job_statusARead-onlyInspect
Get a concise status snapshot for a transcoding job by id (job_...): overall status and progress, any error code/message, and per-output status/progress with errors. Lighter than the full job record — use it to poll a job to completion.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Job id to inspect (job_...). |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| status | Yes | |
| outputs | Yes | |
| progress | Yes | |
| created_at | Yes | |
| error_code | No | |
| started_at | No | |
| completed_at | No | |
| error_message | No |
TDQS
A4.3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, and the description builds on that by disclosing the response scope — a lightweight snapshot with overall and per-output status/progress plus error details — and the efficiency rationale for repeated polling calls. This adds behavioral context beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences carry the entire payload: the first states purpose and return contents, the second states the usage pattern and tradeoff versus the full record. There is no filler and no repetition of structured schema data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one required parameter, 100% schema coverage, an output schema documenting return values, and annotations covering the read-only safety profile, the description has very little to compensate for. It supplies the one missing piece — when to use the tool (polling to completion) — making the definition complete for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the id parameter is already documented in the input schema as 'Job id to inspect (job_...).' The description only repeats the same job_... format in prose, adding no new semantic meaning beyond what the schema already provides. Baseline 3 is appropriate since the schema carries the full burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource — 'Get a concise status snapshot for a transcoding job by id (job_...)' — and itemizes the returned contents (overall status, progress, error code/message, per-output status/progress with errors). It differentiates from siblings by noting it is 'lighter than the full job record,' which clearly separates it from a full-record getter like get_video and from list_jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit use case: 'use it to poll a job to completion,' and frames it against the heavier full job record, which tells the agent when this tool is the right choice. However, it never names the alternative sibling that should be selected when the full record is needed, so the when-not comparison remains implicit rather than fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_usageARead-onlyInspect
Return hosting usage and cost for a billing month: videos encoded, encoding minutes, average storage, egress, request counts, and per-line and total cost in EUR. Defaults to the current month; pass month as "YYYY-MM" for a specific period.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| month | No | Billing month as "YYYY-MM" (e.g. 2026-07). Defaults to the current UTC month. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| daily | Yes | |
| currency | Yes | |
| egress_gb | Yes | |
| total_cost | Yes | |
| egress_cost | Yes | |
| storage_cost | Yes | |
| billing_month | Yes | |
| encoding_cost | Yes | |
| videos_hosted | Yes | |
| storage_gb_avg | Yes | |
| total_requests | Yes | |
| videos_encoded | Yes | |
| encoding_minutes | Yes |
TDQS
A3.9/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as readOnlyHint=true, so the safety profile is covered. The description adds the default-to-current-month behavior and lists the returned cost metrics, but much of this overlaps with the parameter schema and output schema, providing little new behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the purpose, then the metrics list and the parameter behavior. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional parameter and an output schema present, the description covers the default behavior and period format. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the month parameter is fully described with format and default. The description reiterates the same format and default, adding no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Return') and resource ('hosting usage and cost for a billing month'), enumerates the exact metrics returned, and is clearly distinct from all sibling tools, which concern jobs, videos, and captions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case (retrieving billing usage/cost) and explains the month parameter's default behavior. However, it does not explicitly name alternatives or state conditions for when not to use it, leaving tool-selection guidance only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_videoARead-onlyInspect
Fetch a hosted video by id (vid_...): status, visibility, title, duration, poster image, encoded renditions (resolution, codec, bitrate, dimensions), and — once status is "ready" — a playback block. Poll this until status is "ready" (statuses: uploading, processing, ready, error); no playback block is present before then. playback.player_url is the durable player page to hand a human, and is issued for public and unlisted videos only — private videos are not served by the player page and get playback.hls_url instead, a signed manifest for your own player that stops working at playback.expires_at (re-fetch with get_video rather than storing it).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Hosted video id to fetch (vid_...). |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| tags | No | |
| title | No | |
| job_id | No | |
| object | Yes | |
| status | Yes | |
| playback | No | Where to watch this video. Present once status is "ready"; absent while it is still processing. Contains player_url (durable page to hand a human, public/unlisted only) and hls_url with expires_at (short-lived manifest for your own player). |
| ready_at | No | |
| created_at | Yes | |
| poster_url | No | |
| renditions | Yes | |
| visibility | Yes | |
| description | No | |
| encoding_cost | No | |
| duration_seconds | No | |
| output_storage_prefix | No |
TDQS
A4.5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description richly discloses behavior: no playback block before ready, statuses (uploading, processing, ready, error), player_url only for public/unlisted videos, signed manifest behavior, expiry, and the need to re-fetch rather than store. This is exactly the kind of context that prevents incorrect agent assumptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three information-dense sentences are front-loaded with the core purpose and result summary, then move into polling behavior and playback semantics. Every clause adds decision-relevant information; nothing is redundant or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the presence of an output schema, the description is complete: it covers status polling, playback availability, visibility rules, URL durability, expiry, and the correct re-fetch behavior. An agent has enough context to invoke and interpret the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes the single parameter id and its vid_... format, so description coverage is 100%. The description reinforces the format but does not add meaning beyond the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: "Fetch a hosted video by id" and then enumerates exactly what is returned (status, visibility, title, duration, poster, renditions, playback block). This clearly differentiates it from siblings like create_video_from_url, get_job_status, and list_jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the agent when to call this tool, especially the polling workflow: "Poll this until status is 'ready'." It also explains the status lifecycle. It does not explicitly name alternatives or exclusion conditions, but the usage context is clear enough that the agent knows this is the fetch-by-id tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_jobsARead-onlyInspect
List transcoding jobs for the authenticated app, newest first. Optionally filter by status. Returns compact rows (id, status, progress, input_url, cost, timestamps) plus next_cursor for pagination; pass it back as cursor to fetch the next page.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum jobs to return (1-100). Defaults to 20. | |
| cursor | No | Pagination cursor from a previous response's next_cursor. Omit for the first page. | |
| status | No | Filter by job status: pending, probing, processing, completed, failed, canceled, partial, or awaiting_confirmation. Omit for all statuses. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| jobs | Yes | |
| next_cursor | No | |
| total_count | Yes |
TDQS
A4.1/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds useful behavioral context: newest-first ordering, compact field selection, and pagination via next_cursor/cursor. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place: the main action is front-loaded, and return shape plus pagination are covered in one compact follow-up sentence. No filler or redundant restating of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list operation with a 100%-covered schema and an output schema present, this description is complete. It explains ordering, filtering, returned fields, and pagination flow—everything an agent needs to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so limit, cursor, and status are already fully documented in the input schema. The description only restates the cursor round-trip and status filtering, adding no substantial new parameter-level meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: 'List transcoding jobs'. It adds distinguishing scope ('for the authenticated app'), ordering ('newest first'), filtering, and return shape, which separates it from siblings like get_job_status and get_video.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool's intended use is clear from the listing language and optional status filter, but the description never explicitly contrasts it with alternatives. An agent is not told to prefer get_job_status when only a single job's status is needed, which would sharpen routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
7 tool updates
v0.1.0- First observed
create_job - First observed
create_video_from_url - First observed
generate_captions - First observed
get_job_status - First observed
get_usage - First observed
get_video - First observed
list_jobs
TDQS
A4.2/5.0
Scored across 7 tools
Disambiguation5/5
Each tool targets a distinct resource and action: transcoding jobs, hosted videos, captions, and usage. create_job and create_video_from_url are explicitly cross-referenced to disambiguate output-to-own-storage from hosted playback, and get_job_status vs get_video cleanly separate job and video concerns.
Naming Consistency5/5
All tools use a consistent snake_case imperative verb_noun pattern: create_, get_, list_, generate_. Even create_video_from_url reads as create_video with a modifier, so the naming is predictable and easy to navigate.
Tool Count5/5
Seven tools is well-scoped for a video transcoding and hosting server. Each tool earns its place, covering job creation/status/listing, hosted video retrieval, captions, and usage without redundant or overlapping operations.
Completeness3/5
The core create-and-retrieve workflows are covered, plus captions and usage reporting. However, there is no way to delete or update hosted videos, cancel jobs, or remove captions, leaving notable lifecycle gaps for the managed resources.
Maintenance
ActivityMaintained
ResponsivenessNo issues
Related MCP Connectors
Video, audio, and image processing for AI agents: convert, transcribe, upscale - 150+ operations.
FFmpeg as a service for AI agents: typed video editing tools, async jobs, downloadable outputs.
15 media & data tools for AI agents: search, transcribe, subtitles, voiceover, translate & more.
Transcribe audio & video to text for AI agents: 100+ languages, speaker labels, webhooks.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP tools for video transcoding, document conversion, and multi-step pipelines — callable by any AI agent.12253 npm1MIT
- AlicenseAqualityDmaintenanceEnables AI agents to download, transcribe, and inspect video or audio URLs from YouTube, TikTok, X, and 1000+ other sites using server-side yt-dlp, residential proxies, and speech-to-text.929 npmMIT
- AlicenseAqualityBmaintenanceEnables AI agents to create, monitor, and download video transcodes through the FFmpeg Micro REST API.1174 npm1MIT