Сервер Model Context Protocol, который позволяет AI-агентам — Claude Code, Claude Desktop, Cursor, Windsurf, VS Code и любому другому MCP-совместимому клиенту — создавать, отслеживать и скачивать видеотранскоды через REST API FFmpeg Micro.
Предоставляет инструменты, соответствующие публичному API FFmpeg Micro:
Tool | Что делает |
| Создаёт задачу транскодирования из одного или нескольких входных видео ( |
| Получает текущее состояние одной задачи. |
| Выводит список задач с необязательными фильтрами |
| Отменяет ожидающую или выполняющуюся задачу. |
| Генерирует подписанный HTTPS-URL на 10 минут для выходного файла завершённой задачи. |
| Удобный хелпер: создаёт задачу, опрашивает до её завершения и возвращает подписанный URL для скачивания одним вызовом. |
| Шаг 1 процесса прямой загрузки. Возвращает предварительно подписанный HTTPS-URL, на который хост отправляет байты файла методом PUT. |
| Шаг 2 процесса прямой загрузки. Возвращает итоговый URL |
| Запускает выполнение blueprint — готовый видеопроцесс (субтитры, изменение размера, водяные знаки, реклама и многое другое). |
| Получает статус, шаг и URL выходных файлов выполнения blueprint (blueprints с несколькими выходами возвращают |
| Удобный хелпер: запускает выполнение blueprint и опрашивает до завершения, ошибки или паузы для проверки транскрипта. |
| Возобновляет выполнение |
Blueprints — это готовые процессы, лежащие в основе POST /v1/blueprints/{slug}/runs. В описаниях инструментов задокументированы поля ввода каждого blueprint. Примечания:
Большинство blueprints выполняются на FFmpeg-линии и учитываются в вычислительных минутах плана (без токенов). Генеративные blueprints (product-ad) списывают токены; ответ 402 insufficient_tokens означает, что на аккаунте нужен пакет токенов (дашборд).
caption-video останавливается в статусе awaiting_review вместе с транскриптом (srt_text), чтобы агент мог проверить или отредактировать его перед рендерингом; возобновление — через continue_blueprint_run.
Blueprints с несколькими выходами (listing-kit, hook-variants) возвращают массив outputs из {label, url} — при наличии отдавайте предпочтение ему, а не output_url.
URL выходных файлов подписаны с TTL 10 минут; повторно запросите выполнение, чтобы получить свежие ссылки.
Пара request_upload_url + confirm_upload позволяет MCP-хосту загружать локальный файл в storage-бакет FFmpeg Micro без необходимости работать с сырыми API-ключами или URL gs://:
Хост вызывает request_upload_url с параметрами {filename, contentType, fileSize} → получает короткоживущий предварительно подписанный HTTPS-URL.
Хост отправляет байты файла на этот URL методом PUT с тем же Content-Type.
Хост вызывает confirm_upload с параметрами {filename: <storage filename from step 1>, fileSize} → получает итоговый fileUrl вида gs://....
Хост передаёт этот fileUrl в transcribe_audio / transcode_video / transcode_and_wait.
Related MCP server: Rendi MCP Server
Добавьте это в .mcp.json вашего проекта (или в конфигурацию вашего MCP-клиента):
{
"mcpServers": {
"ffmpeg-micro": {
"type": "http",
"url": "https://mcp.ffmpeg-micro.com"
}
}
}Вот и всё. При первом подключении ваш AI-инструмент откроет окно браузера, чтобы вы вошли в свой аккаунт FFmpeg Micro через OAuth. После подтверждения токен кэшируется, и повторный вход не потребуется.
Никаких API-ключей для копирования и переменных окружения для настройки.
MCP-сервер поддерживает OAuth 2.1 с PKCE и динамической регистрацией клиента. Ваш MCP-клиент выполняет весь процесс автоматически:
Клиент обнаруживает OAuth-эндпоинты через /.well-known/oauth-authorization-server
Клиент динамически регистрирует себя
Открывается браузер для входа и подтверждения доступа
Токен обменивается и кэшируется — последующие подключения происходят мгновенно
Это поведение по умолчанию при использовании конфигурации выше без блока headers или env.
Если вы предпочитаете использовать API-ключ напрямую (например, для автоматизации или CI), передавайте его как Bearer-токен:
{
"mcpServers": {
"ffmpeg-micro": {
"type": "http",
"url": "https://mcp.ffmpeg-micro.com",
"headers": {
"Authorization": "Bearer your_api_key_here"
}
}
}
}Получите API-ключ в дашборде.
Запускает сервер как локальный процесс с помощью npx. Требуется Node.js 22.14 или новее.
{
"mcpServers": {
"ffmpeg-micro": {
"command": "npx",
"args": ["-y", "@ffmpeg-micro/mcp-server"],
"env": {
"FFMPEG_MICRO_API_KEY": "your_api_key_here"
}
}
}
}npx -y каждый раз загружает последнюю версию. С этой конфигурацией работает любой MCP-клиент, поддерживающий stdio-серверы.
HTTP-конфигурация (OAuth) работает с любым MCP-клиентом, поддерживающим транспорт Streamable HTTP:
Claude Code (CLI)
Claude Desktop
Cursor
Windsurf
VS Code (GitHub Copilot MCP)
stdio-конфигурация работает с любым MCP-клиентом, поддерживающим транспорт stdio.
После подключения можно задавать, например, такие запросы:
«Транскодируй это видео в MP4 720p и дай мне ссылку для скачивания, когда закончишь.»
«Обрежь это горизонтальное видео до квадрата.»
«Добавь на моё видео текстовую накладку с надписью „Эпизод 12“.»
«Покажи список моих неудачных задач за эту неделю.»
«Отмени задачу b5f5a9c0-9e33-4e77-8a5b-6a0c2cd9c0b3.»
git clone https://github.com/javidjamae/ffmpeg-micro-mcp.git
cd ffmpeg-micro-mcp
./scripts/setup.shsetup.sh устанавливает зависимости, собирает проект и настраивает git-хуки.
Укажите вашему MCP-клиенту на локальную сборку, чтобы итерироваться:
{
"mcpServers": {
"ffmpeg-micro-dev": {
"command": "node",
"args": ["/absolute/path/to/ffmpeg-micro-mcp/dist/index.js"],
"env": { "FFMPEG_MICRO_API_KEY": "…" }
}
}
}MCP Inspector — самый быстрый способ итерироваться по схемам инструментов и ответам:
npx @modelcontextprotocol/inspector node dist/index.jsЧтобы запустить HTTP-сервер локально, направив его на локальный API-шлюз:
FFMPEG_MICRO_API_URL=http://localhost:8081 npm run serveFFMPEG_MICRO_API_KEY=your_key npm run test:integrationИнтеграционные тесты обращаются к реальному production API FFmpeg Micro. Они работают только на чтение (задачи не создаются).
Модульные тесты используют замоканный fetch, поэтому они проверяют регистрацию инструментов + схемы Zod + пути URL, но не то, что структуры данных на проводе совпадают с тем, что реально возвращает шлюз. Два смоук-скрипта прогоняют полный процесс request_upload_url → PUT → confirm_upload против реального MCP-сервера с реальным API-ключом. Запускайте их по порядку: сначала stdio (самый быстрый сигнал), затем развёрнутый HTTP-сервер до/после мёрджа:
# 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>Оба скрипта по умолчанию обращаются к production API и расходуют оплачиваемые минуты (stdio-скрипт дополнительно задействует transcribe_audio для сквозной проверки). Передавайте небольшой файл, например 15-second.mp3, чтобы стоимость была незначительной.
Третий скрипт смоук-тестирует инструменты blueprint (run_blueprint + get_blueprint_run с опросом до завершения на resize-format, затем run_blueprint_and_wait на hook-variants для проверки нескольких выходов). Он использует только blueprints на FFmpeg-линии, поэтому расходует вычислительные минуты плана, но не токены:
npm run build
FFMPEG_MICRO_API_KEY=your_key node scripts/smoke-blueprints-stdio.mjsПревью-развёртывания Vercel по умолчанию ограничены Deployment Protection. Чтобы прогнать HTTP-смоук-скрипт против превью-URL, создайте токен Protection-Bypass-for-Automation в настройках Vercel проекта и передайте его через 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>Скрипт отправляет токен в заголовке x-vercel-protection-bypass в каждом запросе. Он не отправляет x-vercel-set-bypass-cookie: true — этот вариант вызывает 307-редирект с установкой cookie на POST, который StreamableHTTPClientTransport из MCP SDK не обрабатывает, из-за чего запрос завершается ошибкой. Только заголовок возвращает 200 напрямую, без танцев с редиректами.
Релизы публикуются в npm через trusted publishing и в MCP Registry под именем com.ffmpeg-micro/mcp-server, с аутентификацией через Ed25519 DNS TXT-запись на ffmpeg-micro.com. Соответствующий закрытый ключ хранится в секрете MCP_PRIVATE_KEY GitHub Actions. Со стороны npm используется OIDC trusted publishing, поэтому npm-токен не хранится.
Релизы автоматизированы с помощью Changesets. Контрибьюторы не поднимают версии вручную, не ставят теги на коммиты и не запускают команды публикации — они прикрепляют changeset к своему PR, а остальное делает пайплайн релизов.
Каждый PR, изменяющий поставляемый код, должен включать changeset. Это обеспечивает CI-проверка.
# While working on your PR:
npx changesetCLI запросит тип обновления версии (major/minor/patch) и краткое описание. Он создаёт markdown-файл в каталоге .changeset/ — закоммитьте этот файл вместе с вашим PR.
Запасные варианты для PR без релиза (документация, CI, внутренний рефакторинг, изменения тестов без влияния на поведение):
Добавьте метку no-changeset к PR или
Выполните npx changeset --empty, чтобы явно указать: «релиз не нужен».
Вы не выпускаете релизы вручную. Это делает пайплайн:
PR с прикреплёнными changeset-файлами попадают в main.
.github/workflows/release.yml запускается при каждом пуше в main. Когда есть ожидающие changeset, он открывает (или обновляет) PR chore(release): version packages, созданный action. Этот PR:
Запускает changeset version, чтобы применить ожидающие changeset
Поднимает версию в package.json
Повторно синхронизирует server.json через scripts/sync-server-version.mjs
Добавляет записи в CHANGELOG.md
Коммитит результат в собственную ветку
Просмотрите и смёржите PR Version Packages, когда будете готовы к выпуску. Можно накопить несколько changeset перед мёрджем — PR обновляется сам по мере появления новых изменений в main.
После мёрджа пайплайн релизов запускается снова. На этот раз ожидающих changeset нет, поэтому changesets/action обнаруживает изменение версии и:
npm publish (OIDC trusted publishing с аттестацией происхождения)
Автоматически создаёт GitHub Release и git-тег
Финальные шаги воркфлоу устанавливают mcp-publisher, выполняют аутентификацию через DNS-приватный ключ и публикуют в MCP Registry под именем com.ffmpeg-micro/mcp-server.
.github/workflows/release.yml дополнительно выполняет проверку равенства версий при каждом пуше в main. Если package.json.version, server.json.version и server.json.packages[0].version когда-либо разойдутся, сборка завершится с явной ошибкой. Обычно scripts/sync-server-version.mjs поддерживает их в согласованном состоянии, но защита ловит ручные правки, пропустившие синхронизацию.
После мёрджа PR Version Packages, когда воркфлоу зелёный:
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}'Предположим, вы добавляете новый инструмент delete_transcode. Ваш процесс PR:
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 выполняет три проверки:
test — модульные тесты
check (Require changeset) — подтверждает наличие .changeset/*.md
Vercel — превью-развёртывание
После слияния Version Packages PR либо открывается, либо обновляется автоматически, чтобы включить вашу запись. Мержите его, когда будете готовы к релизу.
Никогда не редактируйте поля версий в server.json или package.json вручную. Changesets отвечает за оба файла — scripts/sync-server-version.mjs зеркалирует package.json в server.json. Защита от дрейфа в CI останавливает релиз, если они расходятся.
Никогда не создавайте git tag вручную. changesets/action создаёт тег и GitHub Release в рамках публикации. Вручную созданные теги новый workflow не подхватывает.
Никогда не обходите проверку Require-changeset, коммитя изменения в .changeset/config.json или .changeset/README.md (они не учитываются). Используйте npx changeset, метку no-changeset или npx changeset --empty.
package.json — источник истины для версии. Также содержит mcpName (обязателен для MCP Registry при валидации npm-пакета). Обновляется командой changeset version.
server.json — метаданные MCP Registry. Поля версий автоматически синхронизируются из package.json.
.changeset/config.json — конфигурация Changesets (публичный доступ, форматтер changelog с учётом GitHub).
.changeset/*.md — накопившиеся заметки о релизе, ожидающие обработки следующим запуском changeset version.
scripts/sync-server-version.mjs — зеркалирует версию из package.json в server.json.
.github/workflows/release.yml — конвейер публикации (changesets/action + шаг MCP Registry).
.github/workflows/require-changeset.yml — проверяет наличие changeset в PR.
Проверка Require changeset не проходит на моём PR — выполните npx changeset и закоммитьте сгенерированный файл. Для PR только с документацией / только для CI добавьте метку no-changeset или выполните npx changeset --empty.
CI падает на шаге контроля синхронизации версий — server.json был отредактирован вручную. Локально: node scripts/sync-server-version.mjs, закоммитьте, запушьте. Контроль сравнивает package.json.version, server.json.version и server.json.packages[0].version.
changesets/action не открыл Version Packages PR после слияния моего feature-PR — проверьте, что файл .changeset/*.md в вашем PR действительно содержал данные (непустой front matter с типом бампа и кратким описанием). Пустые changeset'ы означают «релиз не нужен» и намеренно игнорируются.
mcp-publisher publish падает с ошибкой "package not found" — npm ещё не завершил распространение новой версии. Шаг Determine if MCP Registry publish is needed в workflow релиза повторяет запрос npm view до ~50 секунд и отступает, если версия так и не стала доступной, откладывая публикацию в реестр до следующего пуша в main (что автоматически устраняет дрейф). Если вы видите это при ручном запуске, просто подождите 30 секунд и повторите публикацию.
MCP Registry застрял на одну версию позади npm — шаг Determine if MCP Registry publish is needed был пропущен (или вернул needed=false). Запушьте любой коммит в main, чтобы запустить повторный прогон; контроль сравнивает package.json ↔ npm ↔ registry и автоматически навёрстывает отставание. Если пропуск продолжается, посмотрите в логах шага, какую версию сообщил каждый источник.
mcp-publisher publish не проходит валидацию с ошибкой "mcpName mismatch" — mcpName в package.json должен совпадать с name в server.json (оба должны быть com.ffmpeg-micro/mcp-server).
mcp-publisher login dns падает с ошибкой "public key mismatch" — секрет MCP_PRIVATE_KEY больше не соответствует TXT-записи на ffmpeg-micro.com. Перегенерируйте пару ключей локально и обновите и TXT-запись, и секрет GitHub.
MIT — см. 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.
v0.3.1cancel_transcodeconfirm_uploadget_download_urlget_transcodeget_transcribeget_transcribe_downloadlist_transcodesrequest_upload_urltranscode_and_waittranscode_videotranscribe_audioScored across 11 tools
Most 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.
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.
