AIエージェント（Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、その他MCP互換クライアント）が、FFmpeg Micro REST APIを通じて動画トランスコードの作成・監視・ダウンロードを実行できるようにするModel Context Protocolサーバーです。
FFmpeg Microの公開APIに対応するツールを公開します：
ツール | 機能 |
| 1つ以上の入力動画（ |
| 単一ジョブの現在の状態を取得します。 |
| ジョブを一覧表示します。オプションで |
| 保留中または処理中のジョブをキャンセルします。 |
| 完了したジョブの出力ファイルに対する有効期限10分の署名付きHTTPS URLを生成します。 |
| 便利ツール：ジョブを作成して完了までポーリングし、署名付きダウンロードURLを1回の呼び出しで返します。 |
| 直接アップロードの流れのステップ1。ホストがファイルのバイト列をPUTするための署名付きHTTPS URLを返します。 |
| 直接アップロードの流れのステップ2。最終的な |
| ブループリント実行を開始します。事前構築済みの動画ワークフロー（字幕付け、リサイズ、ウォーターマーク、広告など）です。 |
| ブループリント実行のステータス、ステップ、出力URLを取得します（複数出力のブループリントはラベル付きの |
| 便利ツール：ブループリント実行を開始し、完了・失敗・文字起こしレビューの一時停止までポーリングします。 |
|
|
ブループリントは POST /v1/blueprints/{slug}/runs の背後にある事前構築済みワークフローです。各ブループリントの入力フィールドはツールの説明に記載されています。注意点：
ほとんどのブループリントはFFmpegレーンで実行され、プランのコンピュート時間を消費します（トークンは消費しません）。生成系ブループリント（product-ad）はトークンを消費します。402 insufficient_tokens レスポンスは、アカウントにトークンパックが必要であることを意味します（ダッシュボード）。
caption-video は awaiting_review で一時停止し、文字起こし（srt_text）を返すため、エージェントはレンダリング前にレビュー・編集できます。continue_blueprint_run で再開します。
複数出力のブループリント（listing-kit、hook-variants）は outputs 配列として {label, url} を返します。存在する場合は output_url よりもこちらを優先してください。
出力URLは有効期限10分で署名されています。新しいリンクを取得するには実行を再取得してください。
request_upload_url + confirm_upload のペアにより、MCPホストは生のAPIキーや gs:// URLを扱うことなく、ローカルファイルをFFmpeg Microのストレージバケットにアップロードできます：
ホストが {filename, contentType, fileSize} を指定して request_upload_url を呼び出します → 有効期限の短い署名付きHTTPS URLを受け取ります。
ホストは同じ Content-Type でファイルのバイト列をそのURLにPUTします。
ホストが {filename: <ステップ1で受け取ったストレージファイル名>, fileSize} を指定して confirm_upload を呼び出します → 最終的な gs://... の fileUrl を受け取ります。
ホストはその 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ツールが初めて接続すると、ブラウザウィンドウが開き、OAuth経由でFFmpeg Microアカウントにサインインします。承認後、トークンはキャッシュされ、再度求められることはありません。
APIキーのコピーも、環境変数の設定も不要です。
MCPサーバーはPKCEと動的クライアント登録を備えたOAuth 2.1をサポートしています。MCPクライアントがフロー全体を自動的に処理します：
クライアントが /.well-known/oauth-authorization-server 経由でOAuthエンドポイントを検出します
クライアントが動的に自身を登録します
ブラウザが開き、サインインしてアクセスを承認します
トークンが交換されキャッシュされます。以降の接続は即座に行われます
これは、上記の設定で 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 は毎回最新版を取得します。stdioサーバーをサポートするすべてのMCPクライアントがこの設定で動作します。
HTTP設定（OAuth）は、ストリーミング可能なHTTPトランスポートをサポートするすべてのMCPクライアントで動作します：
Claude Code（CLI）
Claude Desktop
Cursor
Windsurf
VS Code（GitHub Copilot MCP）
stdio設定は、stdioトランスポートをサポートするすべてのMCPクライアントで動作します。
接続すると、次のような依頼ができます：
「この動画を720p MP4にトランスコードして、完了したらダウンロードURLを教えて。」
「この横長の動画を正方形にクロップして。」
「動画に『エピソード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ローカルAPIゲートウェイに対してHTTPサーバーをローカルで実行するには：
FFMPEG_MICRO_API_URL=http://localhost:8081 npm run serveFFMPEG_MICRO_API_KEY=your_key npm run test:integration統合テストは実際のFFmpeg Micro本番APIにアクセスします。読み取り専用です（ジョブは作成されません）。
ユニットテストはモックされた fetch を使用するため、ツールの登録・Zodスキーマ・URLパスは検証されますが、ワイヤー形式がゲートウェイが実際に返すものと一致するかは検証されません。2つのスモークスクリプトが、実際のAPIキーを使用して実際のMCPサーバーに対して request_upload_url → PUT → confirm_upload の完全なフローを実行します。順番に実行してください。まず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>両スクリプトはデフォルトで本番APIにアクセスし、課金対象の分数を消費します（stdioスクリプトは transcribe_audio に連鎖してエンドツーエンドの確認を行います）。15-second.mp3 のような小さなファイルを渡すことで、コストをほぼ無視できる程度に抑えられます。
3つ目のスクリプトはブループリントツールのスモークテストを行います（run_blueprint + get_blueprint_run を resize-format で完了までポーリングし、その後 run_blueprint_and_wait を hook-variants で実行して複数出力を検証します）。FFmpegレーンのブループリントのみを使用するため、プランのコンピュート時間は消費しますがトークンは消費しません：
npm run build
FFMPEG_MICRO_API_KEY=your_key node scripts/smoke-blueprints-stdio.mjsVercelプレビューデプロイは、デフォルトでDeployment Protectionによって保護されています。プレビューURLに対してHTTPスモークスクリプトを実行するには、プロジェクトのVercel設定でProtection-Bypass-for-Automationトークンを生成し、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 は送信しません。そのバリアントはPOSTでクッキー設定用の307リダイレクトをトリガーし、MCP SDKの StreamableHTTPClientTransport がリダイレクトに追従しないため、リクエストが失敗します。ヘッダー単独では、リダイレクトによる追加の往復なしで直接200が返ります。
リリースはトラステッドパブリッシング経由でnpmに公開され、com.ffmpeg-micro/mcp-server としてMCPレジストリにも公開されます。認証は ffmpeg-micro.com 上のEd25519 DNS TXTレコードを介して行われます。対応する秘密鍵は MCP_PRIVATE_KEY GitHub Actionsシークレットに保存されています。npm側はOIDCトラステッドパブリッシングを使用するため、npmトークンは保存されません。
リリースはChangesetsで自動化されています。コントリビューターは手動でバージョンを上げたり、コミットにタグを付けたり、公開コマンドを実行したりする必要はありません。PRにchangesetを添付するだけで、リリースパイプラインが残りを処理します。
出荷コードを変更するすべてのPRにはchangesetを含める必要があります。CIチェックがこれを強制します。
# While working on your PR:
npx changesetCLIがバンプ種別（major/minor/patch）と短い概要を求めます。.changeset/ の下にMarkdownファイルが書き込まれるので、そのファイルをPRにコミットしてください。
リリースを伴わないPR向けの回避策（ドキュメント、CI、内部リファクタリング、動作に影響のないテスト変更）：
PRに no-changeset ラベルを追加する、または
npx changeset --empty を実行して「リリース不要」を明示的に宣言する。
手動でリリースを作成する必要はありません。パイプラインが行います：
changesetファイルを添付したPRが main にマージされます。
.github/workflows/release.yml が main へのプッシュのたびに実行されます。保留中のchangesetが存在する場合、アクションによって作成（または更新）された chore(release): version packages PRが開かれます。そのPRは：
保留中のchangesetを消費するために changeset version を実行
package.json をバンプ
scripts/sync-server-version.mjs で server.json を再同期
CHANGELOG.md にエントリを追記
結果を自身のブランチにコミット
出荷する準備ができたらVersion Packages PRをレビューしてマージします。複数のchangesetを蓄積してからマージすることもできます。main にさらにマージされるたびにPRは自動更新されます。
マージ時にリリースワークフローが再度実行されます。今回は保留中のchangesetがないため、changesets/action がバージョンバンプを検出して：
npm publish（OIDCトラステッドパブリッシング、来歴証明付き）
GitHub Releaseとgitタグを自動的に作成
ワークフローの最終ステップで mcp-publisher をインストールし、DNS秘密鍵で認証して、com.ffmpeg-micro/mcp-server としてMCPレジストリに公開します。
.github/workflows/release.yml は main へのプッシュのたびにバージョン一致チェックを実行します。package.json.version、server.json.version、server.json.packages[0].version がずれた場合、ビルドは明確に失敗します。通常は scripts/sync-server-version.mjs がこれらを一致させ続けますが、ガードは同期を忘れた手動編集を検出します。
Version Packages PRがマージされ、ワークフローが成功したら：
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は3つのチェックを実行します：
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 は publish の一部としてタグと GitHub Release を作成します。手動のタグは新しいワークフローでは認識されません。
Require-changeset チェックを迂回しないでください。 .changeset/config.json や .changeset/README.md への変更をコミットしても、それらはカウントされません。npx changeset、no-changeset ラベル、または npx changeset --empty を使用してください。
package.json — バージョンの信頼できる情報源。MCP Registry が npm パッケージの検証に必要とする mcpName も保持します。changeset version によってバージョンが更新されます。
server.json — MCP Registry のメタデータ。バージョンフィールドは package.json から自動的に同期されます。
.changeset/config.json — Changesets の設定（公開アクセス、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 — PR に changeset が存在することを強制します。
自分の PR で Require changeset チェックが失敗する — npx changeset を実行し、生成されたファイルをコミットしてください。ドキュメントのみ / CI のみの PR の場合は、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 を比較します。
機能 PR のマージ後に changesets/action が Version Packages PR を開かなかった — PR の .changeset/*.md ファイルに実際にコンテンツ（バンプタイプとサマリーを含む空でない front matter）があったか確認してください。空の changeset は「リリース不要」を示し、意図的に無視されます。
mcp-publisher publish が "package not found" で失敗する — npm が新しいバージョンの伝播をまだ完了していません。リリースワークフローの Determine if MCP Registry publish is needed ステップは npm view を最大約 50 秒間再試行し、それでもバージョンが公開されていない場合はバックオフして、レジストリへの公開を次の main へのプッシュまで延期します（そのプッシュによりドリフトが自己修復されます）。手動実行でこれが発生した場合は、30 秒待って再公開してください。
MCP Registry が npm より 1 バージョン遅れている — Determine if MCP Registry publish is needed ステップがスキップされた（または needed=false を返した）ためです。main に任意のコミットをプッシュして再実行をトリガーしてください。ゲートは package.json ↔ npm ↔ レジストリを比較し、自動的に追いつきます。それでもスキップされる場合は、ステップのログ出力で各ソースが報告したバージョンを確認してください。
mcp-publisher publish が "mcpName mismatch" で検証に失敗する — package.json の mcpName は server.json の name と一致している必要があります（両方とも com.ffmpeg-micro/mcp-server であるべきです）。
mcp-publisher login dns が "public key mismatch" で失敗する — MCP_PRIVATE_KEY シークレットが ffmpeg-micro.com の TXT レコードと一致しなくなっています。ローカルで鍵ペアを再生成し、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.
