This server enables AI agents to create, manage, and download video transcodes, generate SRT subtitles, upload local files, and execute blueprint workflows via the FFmpeg Micro API.
Video Transcoding: Create transcode jobs from one or more inputs (gs:// or https://) using quality/resolution presets or raw FFmpeg options; output to MP4, WebM, or MOV. Monitor jobs (get status, list with filters, cancel), generate signed HTTPS download links (valid 10 minutes), and use a one-shot transcode_and_wait tool that polls until completion and returns the download URL.
Audio Transcription: Generate SRT subtitles via Whisper, with optional translation and language hints. Check job status and obtain a signed download URL for the SRT file.
Direct File Uploads: Two-step flow: request a presigned HTTPS URL, upload the file, then confirm to receive a gs:// URL and probe metadata (duration, format, codecs) for use as a transcode or transcription input.
Blueprint Workflows: Start pre-built workflows (captioning, resizing, watermarking, ads, etc.), monitor steps and multi-output URLs, poll until completion or pause, and resume paused caption‑video runs by supplying an approved SRT transcript.
Authentication: Supports OAuth or API key for flexible connection in various MCP clients.
Provides tools to interact with the FFmpeg Micro REST API for video transcoding, including creating, monitoring, canceling jobs, and uploading local files for processing.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@@ffmpeg-micro/mcp-server Transcode this video to 720p mp4."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server that lets AI agents — Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, and any other MCP-compatible client — create, monitor, and download video transcodes through the FFmpeg Micro REST API.
Exposes tools that map onto FFmpeg Micro's public API:
Tool | What it does |
| Create a transcode job from one or more input videos ( |
| Fetch the current state of a single job. |
| List jobs with optional |
| Cancel a pending or processing job. |
| Generate a 10-minute signed HTTPS URL for a completed job's output file. |
| Convenience: create a job, poll until it finishes, return the signed download URL in one call. |
| Step 1 of the direct-upload flow. Returns a presigned HTTPS URL that the host PUTs the file bytes to. |
| Step 2 of the direct-upload flow. Returns the final |
| Start a blueprint run — a pre-built video workflow (captioning, resizing, watermarking, ads, and more). |
| Fetch a blueprint run's status, step, and output URLs (multi-output blueprints return labeled |
| Convenience: start a blueprint run and poll until it completes, fails, or pauses for transcript review. |
| Resume a |
Blueprints are pre-built workflows behind POST /v1/blueprints/{slug}/runs. The tool descriptions document each blueprint's input fields. Notes:
Most blueprints run on the FFmpeg lane and meter plan compute minutes (no tokens). Generative blueprints (product-ad) charge tokens; a 402 insufficient_tokens response means the account needs a token pack (dashboard).
caption-video pauses in awaiting_review with the transcript (srt_text) so the agent can review/edit before rendering; resume with continue_blueprint_run.
Multi-output blueprints (listing-kit, hook-variants) return an outputs array of {label, url} — prefer it over output_url when present.
Output URLs are signed with a 10-minute TTL; re-fetch the run for fresh links.
The request_upload_url + confirm_upload pair lets an MCP host upload a local file to the FFmpeg Micro storage bucket without dealing with raw API keys or gs:// URLs:
Host calls request_upload_url with {filename, contentType, fileSize} → receives a short-lived presigned HTTPS URL.
Host PUTs the file bytes to that URL with the same Content-Type.
Host calls confirm_upload with {filename: <storage filename from step 1>, fileSize} → receives the final gs://... fileUrl.
Host passes that fileUrl to transcribe_audio / transcode_video / transcode_and_wait.
Related MCP server: Rendi MCP Server
Add this to your project's .mcp.json (or your MCP client's config):
{
"mcpServers": {
"ffmpeg-micro": {
"type": "http",
"url": "https://mcp.ffmpeg-micro.com"
}
}
}That's it. The first time your AI tool connects, it will open a browser window for you to sign in with your FFmpeg Micro account via OAuth. After you approve, the token is cached and you won't be asked again.
No API keys to copy, no environment variables to set.
The MCP server supports OAuth 2.1 with PKCE and dynamic client registration. Your MCP client handles the entire flow automatically:
Client discovers OAuth endpoints via /.well-known/oauth-authorization-server
Client registers itself dynamically
Browser opens for you to sign in and approve access
Token is exchanged and cached — subsequent connections are instant
This is the default when you use the config above with no headers or env block.
If you prefer to use an API key directly (e.g., for automation or CI), you can pass it as a Bearer token:
{
"mcpServers": {
"ffmpeg-micro": {
"type": "http",
"url": "https://mcp.ffmpeg-micro.com",
"headers": {
"Authorization": "Bearer your_api_key_here"
}
}
}
}Get your API key from the dashboard.
Runs the server as a local process using npx. Requires Node.js 22.14 or later.
{
"mcpServers": {
"ffmpeg-micro": {
"command": "npx",
"args": ["-y", "@ffmpeg-micro/mcp-server"],
"env": {
"FFMPEG_MICRO_API_KEY": "your_api_key_here"
}
}
}
}npx -y fetches the latest version each time. Any MCP client that supports stdio servers works with this config.
The HTTP config (OAuth) works with any MCP client that supports streamable HTTP transport:
Claude Code (CLI)
Claude Desktop
Cursor
Windsurf
VS Code (GitHub Copilot MCP)
The stdio config works with any MCP client that supports stdio transport.
Once connected, you can ask things like:
"Transcode this video to 720p MP4 and give me the download URL when it's done."
"Crop this landscape video to a square."
"Add a text overlay saying 'Episode 12' to my video."
"List my failed jobs from this week."
"Cancel job b5f5a9c0-9e33-4e77-8a5b-6a0c2cd9c0b3."
git clone https://github.com/javidjamae/ffmpeg-micro-mcp.git
cd ffmpeg-micro-mcp
./scripts/setup.shsetup.sh installs dependencies, builds, and wires up the git hooks.
Point your MCP client at the local build to iterate:
{
"mcpServers": {
"ffmpeg-micro-dev": {
"command": "node",
"args": ["/absolute/path/to/ffmpeg-micro-mcp/dist/index.js"],
"env": { "FFMPEG_MICRO_API_KEY": "…" }
}
}
}The MCP Inspector is the fastest way to iterate on tool schemas and responses:
npx @modelcontextprotocol/inspector node dist/index.jsTo run the HTTP server locally against a local API gateway:
FFMPEG_MICRO_API_URL=http://localhost:8081 npm run serveFFMPEG_MICRO_API_KEY=your_key npm run test:integrationIntegration tests hit the real FFmpeg Micro production API. They are read-only (no jobs are created).
Unit tests use a mocked fetch, so they prove tool registration + Zod schemas + URL paths but not that the wire shapes match what the gateway actually returns. Two smoke scripts exercise the full request_upload_url → PUT → confirm_upload flow against a real MCP server using a real API key. Run them in order — stdio first (fastest signal), then a deployed HTTP server before/after merge:
# 1. stdio (local dist build) — spawns dist/index.js as a subprocess
npm run build
FFMPEG_MICRO_API_KEY=your_key node scripts/smoke-upload-stdio.mjs <local-file>
# 2. HTTP (any deployed server — local `npm run serve`, Vercel preview, or prod)
FFMPEG_MICRO_API_KEY=your_key MCP_URL=https://mcp.ffmpeg-micro.com/ \
node scripts/smoke-upload-http.mjs <local-file>Both scripts hit the production API by default and consume billable minutes (the stdio script chains into transcribe_audio for an end-to-end check). Pass a small file like 15-second.mp3 to keep the cost negligible.
A third script smoke-tests the blueprint tools (run_blueprint + get_blueprint_run polled to completion on resize-format, then run_blueprint_and_wait on hook-variants to exercise multi-output). It uses FFmpeg-lane blueprints only, so it consumes plan compute minutes but no tokens:
npm run build
FFMPEG_MICRO_API_KEY=your_key node scripts/smoke-blueprints-stdio.mjsVercel preview deployments are gated by Deployment Protection by default. To exercise the HTTP smoke script against a preview URL, generate a Protection-Bypass-for-Automation token in the project's Vercel settings and pass it via VERCEL_BYPASS:
FFMPEG_MICRO_API_KEY=your_key \
MCP_URL=https://your-preview.vercel.app/ \
VERCEL_BYPASS=your_bypass_token \
node scripts/smoke-upload-http.mjs <local-file>The script sends the token as the x-vercel-protection-bypass header on every request. It does not send x-vercel-set-bypass-cookie: true — that variant triggers a 307 cookie-setting redirect on POST that the MCP SDK's StreamableHTTPClientTransport does not follow, so the request fails. The header alone returns 200 directly without the redirect dance.
Releases are published to npm via trusted publishing and to the MCP Registry as com.ffmpeg-micro/mcp-server, authenticated via an Ed25519 DNS TXT record on ffmpeg-micro.com. The corresponding private key lives in the MCP_PRIVATE_KEY GitHub Actions secret. The npm side uses OIDC trusted publishing, so no npm token is stored.
Releases are automated via Changesets. Contributors don't manually bump versions, tag commits, or run publish commands — they attach a changeset to their PR and the release pipeline handles the rest.
Every PR that changes shipped code must include a changeset. A CI check enforces this.
# While working on your PR:
npx changesetThe CLI prompts for bump type (major/minor/patch) and a short summary. It writes a markdown file under .changeset/ — commit that file with your PR.
Escape hatches for non-release PRs (docs, CI, internal refactor, test changes with no behavioral impact):
Add the no-changeset label to the PR, or
npx changeset --empty to explicitly declare "no release needed."
You don't manually cut releases. The pipeline does it:
PRs land on main with changeset files attached.
.github/workflows/release.yml runs on every push to main. When pending changesets exist, it opens (or updates) a chore(release): version packages PR authored by the action. That PR:
Runs changeset version to consume the pending changesets
Bumps package.json
Re-syncs server.json via scripts/sync-server-version.mjs
Appends entries to CHANGELOG.md
Commits the result to its own branch
Review and merge the Version Packages PR when you're ready to ship. You can let several changesets accumulate before merging — the PR updates itself as more land on main.
On merge, the release workflow runs again. This time there are no pending changesets, so changesets/action detects the version bump and:
npm publish (OIDC trusted publishing, with provenance attestation)
Creates the GitHub Release + git tag automatically
The workflow's final steps install mcp-publisher, authenticate via the DNS private key, and publish to the MCP Registry as com.ffmpeg-micro/mcp-server.
.github/workflows/release.yml still runs a version-parity check on every push to main. If package.json.version, server.json.version, and server.json.packages[0].version ever drift, the build fails loudly. Normally scripts/sync-server-version.mjs keeps them aligned, but the guard catches manual edits that missed the sync.
After the Version Packages PR is merged and the workflow is green:
npm view @ffmpeg-micro/mcp-server version
curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=com.ffmpeg-micro/mcp-server" | jq '.servers[] | {v: .server.version, isLatest: ._meta."io.modelcontextprotocol.registry/official".isLatest}'Suppose you're adding a new delete_transcode tool. Your PR flow:
git switch -c feat/delete-transcode
# ... make the code + test changes ...
npx changeset
# ? Which packages would you like to include? › @ffmpeg-micro/mcp-server
# ? Which type of change is this for @ffmpeg-micro/mcp-server? › minor
# ? Please enter a summary for this change › Add delete_transcode tool
git add .changeset/*.md src/ tests/
git commit -m "feat: add delete_transcode tool"
git push -u origin feat/delete-transcode
gh pr createCI runs three checks:
test — unit tests
check (Require changeset) — confirms .changeset/*.md is present
Vercel — preview deploy
After merge, the Version Packages PR either opens or updates itself to include your entry. Merge that when you're ready to ship.
Never edit version fields in server.json or package.json by hand. Changesets owns both — scripts/sync-server-version.mjs mirrors package.json into server.json. The CI drift guard fails the release if they diverge.
Never git tag a release manually. changesets/action creates the tag + GitHub Release as part of publish. Manual tags aren't picked up by the new workflow.
Never bypass the Require-changeset check by committing changes to .changeset/config.json or .changeset/README.md (those don't count). Use npx changeset, the no-changeset label, or npx changeset --empty.
package.json — source of truth for version. Also holds mcpName (required by the MCP Registry for npm package validation). Bumped by changeset version.
server.json — MCP Registry metadata. Version fields are auto-synced from package.json.
.changeset/config.json — Changesets configuration (public access, GitHub-aware changelog formatter).
.changeset/*.md — pending release notes waiting to be consumed by the next changeset version run.
scripts/sync-server-version.mjs — mirrors package.json version into server.json.
.github/workflows/release.yml — the publish pipeline (changesets/action + MCP Registry step).
.github/workflows/require-changeset.yml — enforces changeset presence on PRs.
Require changeset check fails on my PR — run npx changeset and commit the generated file. For docs-only / CI-only PRs, add the no-changeset label or npx changeset --empty.
CI fails at the version-sync guard step — server.json was edited manually. Locally: node scripts/sync-server-version.mjs, commit, push. The guard compares package.json.version, server.json.version, and server.json.packages[0].version.
changesets/action didn't open a Version Packages PR after my feature PR merged — check that your PR's .changeset/*.md file actually had content (non-empty front matter with a bump type and summary). Empty changesets signal "no release needed" and are intentionally ignored.
mcp-publisher publish fails with "package not found" — npm hasn't finished propagating the new version yet. The release workflow's Determine if MCP Registry publish is needed step retries npm view for up to ~50 seconds and backs off if the version still isn't live, deferring the registry publish to the next push to main (which self-heals the drift). If you see this in a manual run, just wait 30s and re-publish.
MCP Registry stuck a version behind npm — the Determine if MCP Registry publish is needed step skipped (or returned needed=false). Push any commit to main to trigger a re-run; the gate compares package.json ↔ npm ↔ registry and catches up automatically. If it keeps skipping, check the step's log output for which version each source reported.
mcp-publisher publish fails validation with "mcpName mismatch" — package.json mcpName must equal server.json name (both should be com.ffmpeg-micro/mcp-server).
mcp-publisher login dns fails with "public key mismatch" — the MCP_PRIVATE_KEY secret no longer matches the TXT record on ffmpeg-micro.com. Regenerate the keypair locally, update both the TXT record and the GitHub secret.
MIT — see LICENSE.
Cancel a queued or processing transcode job. Jobs that are already completed, failed, or cancelled cannot be cancelled and return an error.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Transcode job UUID to cancel |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full transparency burden. It discloses that cancellation only succeeds for queued/processing jobs and otherwise returns an error. However, it does not cover side effects, irreversibility, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. Essential information is front-loaded: what it does, when it works, and error cases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema), the description provides sufficient context for an AI agent to understand usage, valid states, and error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents the single parameter. The description does not add additional meaning beyond the schema (e.g., format constraints). Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool cancels a transcode job, specifying the resource (transcode job) and action (cancel). Distinguishes from siblings like transcode_video (create) and get_transcode (read) by focusing on cancellation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states valid states for cancellation (queued or processing) and explains when not to use (completed, failed, cancelled jobs return error). Provides clear context, though no alternative tools are explicitly mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Step 2 of the direct-upload flow. Call after PUTting the file bytes to the URL returned by request_upload_url. Returns the final gs://... fileUrl plus probe metadata (duration, format, codecs). Use the fileUrl directly as a media_url for transcribe_audio or as an inputs[].url for transcode_video.
| Name | Required | Description | Default |
|---|---|---|---|
| fileSize | Yes | File size in bytes — must match the size declared in `request_upload_url`. | |
| filename | Yes | Storage object name returned by `request_upload_url` (the `result.filename` field), NOT the original local filename. | |
| uploadId | No | Optional upload tracking ID, if the gateway returned one with the presigned URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes return values (fileUrl and probe metadata) but does not disclose validation behavior, error conditions, or side effects. With no annotations, a slightly higher bar would require mention of what happens if fileSize mismatch or other failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. Key information is front-loaded: 'Step 2 of the direct-upload flow.' Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains return values (fileUrl and probe metadata) and how to use them. Provides sufficient context for a two-step flow, linking to sibling tools. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all parameters with descriptions. The main description adds value by clarifying that 'filename' is the storage object name (not original local filename) and that 'fileSize must match the size declared in request_upload_url'. This goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as 'Step 2 of the direct-upload flow' and states its specific verb+resource ('confirm upload'). It distinguishes from sibling tools like request_upload_url by positioning it as the follow-up step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly specifies when to use ('after PUTting the file bytes to the URL returned by request_upload_url') and what to do with the result ('use the fileUrl as media_url for transcribe_audio or inputs[].url for transcode_video'). Lacks explicit when-not-to-use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a short-lived (10 minute) signed HTTPS URL for a completed transcode's output file. The job must be in completed status. Use this instead of the output_url field on the job object, which is a gs:// URL that HTTP clients cannot fetch directly.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Completed transcode job UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the URL is short-lived (10 minutes), is an HTTPS URL, and requires job to be completed. This provides useful behavioral context beyond schema. Could mention if the URL is single-use or reusable, but still strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three precise sentences, front-loaded with purpose, condition, and rationale. No redundant information. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (one param, no output schema, low complexity), the description covers purpose, condition, and alternative. Could be more explicit about return type, but overall adequate for an agent to decide to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, baseline is 3. Description adds meaningful context: explains why the id parameter is needed (completed transcode job) and justifies the tool's existence. This adds value beyond schema's basic type description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool generates a signed HTTPS URL for a completed transcode output file. The description uses specific verbs and resource ('generate a signed HTTPS URL for output file') and distinguishes it from sibling tools like get_transcode by focusing on download URL generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the tool should be used instead of the output_url field on the job object because it is a gs:// URL that HTTP clients cannot fetch directly. It also specifies the job must be in completed status, providing clear context for when to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the current state of a single transcode job by ID, including status (queued/processing/completed/failed) and output_url when completed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Transcode job UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden. It discloses the returned fields (status, output_url) but does not mention error behavior (e.g., non-existent ID), idempotency, or side effects. It lacks full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single 20-word sentence efficiently conveys the tool's purpose, action, and output. No unnecessary words, perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch operation with one parameter, the description covers the main output but omits response structure details (e.g., error format, full JSON example). Without output schema, more detail would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (id described as 'Transcode job UUID'). The description adds no meaning beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch'), the resource ('current state of a single transcode job'), and the specific data returned (status and output_url). This distinguishes it from siblings like list_transcodes (list all) or cancel_transcode (mutate).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context of sibling tools makes it clear that this tool is for fetching an individual job's state. However, it does not explicitly state when to use alternatives or provide exclusion cases, keeping it from a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the current state of a single transcribe job by ID, including status (queued/processing/completed/failed) and output_url when completed. Mirrors get_transcode but for SRT generation jobs created via transcribe_audio.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Transcribe job UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that output_url appears when completed and implies read-only nature with 'fetch'. It does not mention error handling, authorization needs, or rate limits, which reduces transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action and resource, no fluff. Every word contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch tool with one parameter and no output schema, the description covers the main output fields (status, output_url). It lacks details on other potential fields and does not guide usage relative to get_transcribe_download, but overall is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter described as 'Transcribe job UUID'. The description adds no further meaning beyond that, so it meets the baseline but does not compensate with extra detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Fetch' and resource 'state of a single transcribe job by ID', includes response details (status, output_url), and explicitly distinguishes from sibling tool get_transcode by noting it's for SRT generation jobs created via transcribe_audio.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides good context on when to use (to check state of a transcribe job) and acknowledges similarity to get_transcode for transcode jobs. However, it does not explicitly state when not to use or mention alternative tools like get_transcribe_download.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a short-lived (10 minute) signed HTTPS URL for a completed transcribe job's SRT file. The job must be in completed status. The returned URL can be dropped directly into a transcode's subtitles='<url>' filter to burn captions into a video.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Completed transcribe job UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It discloses the URL's short-lived duration (10 minutes) and file type (SRT). However, it does not mention rate limits, idempotency, or error behavior if the job is not completed, which are relevant for a generation endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences with no fluff. The first states the primary action and duration, the second sets precondition and a usage example. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema, no annotations), the description is complete enough. It covers purpose, precondition, and a practical integration tip. It lacks only minor behavioral details like error cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds context that the 'id' parameter corresponds to a completed transcribe job. The schema already describes the parameter as 'Completed transcribe job UUID', so the description provides marginal added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool 'Generate a short-lived signed HTTPS URL' for a completed transcribe job's SRT file, clearly distinguishing it from sibling tools like get_transcribe (which likely returns job metadata) and get_download_url (might be for other file types).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies the precondition that the job must be in 'completed' status, and provides a practical use case in a transcode filter. It does not explicitly state when not to use the tool or list alternatives, but the context is sufficiently clear for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List transcode jobs for the authenticated account, with optional filters for status and time range. Paginated (default page 1, limit 20).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-indexed page number | |
| limit | No | Page size (max 100) | |
| since | No | ISO timestamp — only return jobs created at/after this time | |
| until | No | ISO timestamp — only return jobs created at/before this time | |
| status | No | Filter by job status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses authentication requirement, pagination defaults, and optional filters, but lacks details on rate limits, ordering, or behavior when no results are returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise, front-loaded sentences with no wasted words, effectively conveying the tool's purpose and key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 5 optional parameters, the description adequately covers filters and pagination. Minor omission: ordering of results not mentioned, but overall complete for a list endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds pagination defaults and overall filter purpose, but does not elaborate on parameter format or semantics beyond what schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (list), resource (transcode jobs), scope (authenticated account), and mentions optional filters and pagination, distinguishing it from siblings like get_transcode or transcode_video.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing jobs with filters, but does not explicitly state when to use this tool versus alternatives like get_transcode or cancel_transcode, nor does it mention 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.
Step 1 of the direct-upload flow. Returns a short-lived presigned HTTPS URL that the caller PUTs the file bytes to (with the same Content-Type that was passed in). After the PUT succeeds, call confirm_upload with the same filename and fileSize to receive the final gs:// URL for use as a transcode/transcribe input. The presigned URL expires in ~15 minutes.
| Name | Required | Description | Default |
|---|---|---|---|
| fileSize | Yes | File size in bytes (positive integer). Max 1.9GB. | |
| filename | Yes | Original filename, e.g. 'webinar.m4a'. Used as the suffix of the storage object name. | |
| contentType | Yes | MIME type of the file (e.g. 'audio/mp4', 'video/mp4', 'image/png'). Must be a supported media type. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, description discloses key behaviors: short-lived presigned URL, PUT requirement with same Content-Type, expiry time. Could note error states but adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, logically structured steps. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains return type (presigned URL) and next step. Could specify exact return format but sufficient for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage; description adds context: filename as suffix, fileSize max 1.9GB, contentType must match PUT. Adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly identifies the tool as 'Step 1 of the direct-upload flow' returning a presigned URL, distinguishing it from sibling tools like 'confirm_upload'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explains the workflow (this step, then PUT, then confirm_upload) and mentions the URL expiry (~15 min), giving clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One-shot convenience tool: creates a transcode job, polls until it reaches a terminal state (completed/failed/cancelled) or the timeout expires, and returns the final job plus a signed download URL if completed. Use this when you want the full transcode in one step without managing polling yourself.
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes | One to ten input videos. Multiple inputs are concatenated in order. | |
| preset | No | Simple mode — quality/resolution presets. Ignored if `options` is provided. | |
| options | No | Advanced mode — raw FFmpeg options or virtual options. Overrides `preset`. | |
| outputFormat | Yes | Container format for the output file | |
| timeoutSeconds | No | Max time to wait for the job to complete, in seconds. Default 600 (10 min). Max 1800. | |
| pollIntervalSeconds | No | Polling interval in seconds. Default 3. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully explains the behavior: job creation, polling, timeout, and return of final job and download URL on completion. It could mention what happens on timeout or failure more explicitly, but overall it's transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey the purpose and usage. No redundant information, and key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core workflow and return value adequately. Given the complexity (6 params, nested objects, no output schema), it provides enough context for the agent to understand the tool's behavior and when to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add parameter details beyond the schema, which already contains detailed descriptions for each parameter including allowed values and constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it creates a transcode job, polls to completion, and returns the result with a download URL. It distinguishes itself from sibling tools like transcode_video and get_transcode by being a one-step convenience function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this when you want the full transcode in one step without managing polling yourself,' providing clear guidance on when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a video transcode job on FFmpeg Micro. Accepts one or more input videos (gs:// or https://) and an output format. Returns immediately with a queued job — use get_transcode, list_transcodes, or transcode_and_wait to follow progress.
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes | One to ten input videos. Multiple inputs are concatenated in order. | |
| preset | No | Simple mode — quality/resolution presets. Ignored if `options` is provided. | |
| options | No | Advanced mode — raw FFmpeg options or virtual options. Overrides `preset`. | |
| outputFormat | Yes | Container format for the output file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that the job is queued and immediate return, but lacks details on cost, failure handling, output storage lifetime, or any destructive/read-only nature. This is insufficient for a tool that creates resources.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and contains no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has nested parameters and creates async jobs with no output schema. The description mentions immediate return of a queued job but does not specify the response structure (e.g., job ID) or error handling. It also omits lifecycle details like temporary storage and expiration, leaving gaps for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is well-documented in the schema itself. The description adds no additional 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'video transcode job'. It specifies inputs (gs:// or https://) and output format, and distinguishes from siblings by mentioning related tools for tracking progress.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the tool returns immediately with a queued job and directs the user to use get_transcode, list_transcodes, or transcode_and_wait to follow progress. It implies asynchronous use versus synchronous with sibling transcode_and_wait. However, it does not explicitly state when not to use this tool or prerequisites like required permissions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate an SRT subtitle file from an audio or video URL using Whisper. Returns a queued job envelope immediately — poll with get_transcribe until status is completed, then fetch the signed SRT URL with get_transcribe_download. The SRT URL can be dropped directly into a transcode's subtitles='<url>' filter to burn captions into a video.
| Name | Required | Description | Default |
|---|---|---|---|
| task | No | 'transcribe' keeps the source language; 'translate' outputs English regardless of source. Defaults to 'transcribe'. | |
| language | No | Optional BCP-47 language hint (e.g. 'en', 'es'). Auto-detected when omitted. | |
| media_url | Yes | Audio or video URL to transcribe. gs://bucket/object (preferred, from the upload flow) or a public https:// URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses async nature (returns queued job envelope) and required polling. It doesn't cover error handling, rate limits, or file size constraints. Without annotations, this is good but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with primary action. No wasted words; every sentence provides essential workflow information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers the async process, polling workflow, download URL, and integration with transcode. Sufficient for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters. The description adds value by mentioning 'Whisper' and specifying preferred URL format (gs:// vs https://) beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates SRT subtitles from audio/video URL using Whisper. It distinguishes from sibling tools by detailing the polling and download process, and mentions integration with transcode.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit instructions on when to use the tool: poll with `get_transcribe` for completion, fetch download URL with `get_transcribe_download`, and use SRT URL in transcode's subtitles filter. This clearly differentiates usage from alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.3.1cancel_transcodeconfirm_uploadget_download_urlget_transcodeget_transcribeget_transcribe_downloadlist_transcodesrequest_upload_urltranscode_and_waittranscode_videotranscribe_audioMost tools have distinct purposes: transcode vs transcribe vs upload. The overlap between 'transcode_video' and 'transcode_and_wait' is clarified by description, and 'get_download_url' vs 'get_transcribe_download' are distinguished by resource type. Minor potential confusion between 'get_transcode' and 'get_transcribe' but their names indicate the difference.
Naming patterns are mixed: 'transcode_video', 'get_transcode', 'list_transcodes', 'cancel_transcode' follow verb_noun, but 'transcode_and_wait' uses a conjunction, and 'get_transcribe_download' breaks the pattern. Also 'request_upload_url' and 'confirm_upload' are not prefixed with 'upload'. Overall inconsistent.
11 tools is appropriate for the scope: covers transcode creation, monitoring, cancellation, convenience wrapper; transcribe creation and download; upload flow; and download URL generation. Neither too few nor too many for a focused MCP server.
The tool set covers core transcode and transcribe workflows but lacks listing and cancellation for transcribe jobs, while these exist for transcode. There is also no delete or update for completed jobs. Minor gaps that could hinder workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
FFmpeg as a service for AI agents: typed video editing tools, async jobs, downloadable outputs.
Video, audio, and image processing for AI agents: convert, transcribe, upscale - 150+ operations.
Transform video, audio and images, and generate media from prompts. FFmpeg, captions, models.
Hosted MCP tools for FFmpeg-style video and audio processing through FFMPEG API.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/javidjamae/ffmpeg-micro-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
