qencode

qencode-mcp

Qencode Transcoding API 用の Model Context Protocol（MCP）サーバーです。

MCP 対応の AI クライアント（Claude、Cursor、ChatGPT、Grok、Gemini）を Qencode アカウントに接続すると、トランスコードジョブの送信、監視、判断を代わりに行えます。

使用例

クライアントを接続したら（クライアントを接続するを参照）、エージェントに自然な英語で指示します。

https://example.com/input.mp4 を 1080/720/540/360 の HLS ラダーとしてトランスコードしてください。R2 バケットの videos/demo/ に保存してください。

エージェントは hls_abr レシピを選び、各レンディションのエンコードパラメーターを設定して、start_encode2_raw 経由で送信し、ジョブが完了するまでポーリングします。

前提条件

• 少なくとも 1 つのプロジェクトがある Qencode ポータルアカウント。ご利用の環境のポータルにサインインしてください：https://portal.qencode.com（本番環境）または https://portal-qa.qencode.com（QA）。OAuth の同意手順でプロジェクトを選択します。
• MCP 対応クライアント（Claude、Cursor、ChatGPT、Grok、Gemini、または任意のカスタムクライアント）。

クライアント設定にコピーする API キーはありません。認証はブラウザー経由の OAuth で行われます。

仕組み

このコネクターは標準の OAuth 2.1 を使用します。クライアント設定に API キーは必要ありません。初回使用時にクライアントがブラウザーを開き、Qencode ポータルアカウントにサインインして、プロジェクトを選択し、要求されたスコープを承認します。クライアントはトークンを保存します。以降の呼び出しは、トークンが期限切れになるまで認証操作なしで行われます。

認可時にクライアントが要求するスコープ（Protected Resource Metadata 経由で公開）：

スコープ	目的
openid	OIDC アイデンティティ
profile	表示名
email	アカウントのメールアドレス
offline_access	リフレッシュトークン
transcoding:read	get_job_status、list_jobs、ドキュメントツール
transcoding:write	transcode_video、start_encode2_raw

RS はトランスポート層で、アクセストークンに対して transcoding:read と transcoding:write を強制します。

Qencode API キーがポータルの外に出ることはありません。MCP サーバーは内部ポータルエンドポイント経由で、リクエストごとに有効期間の短いセッショントークンを生成します。

環境

同じコネクターが 2 つの環境にデプロイされています。それぞれドメイン、アカウント、プロジェクト、認証情報が異なります。接続するエンドポイントに対応するポータルにサインインしてください。

役割	本番環境	QA（テスト）
MCP エンドポイント（ここに接続）	https://mcp.qencode.com/mcp	https://mcp-qa.qencode.com/mcp
ポータル（サインイン／プロジェクト）	https://portal.qencode.com	https://portal-qa.qencode.com
認可サーバー	https://auth.qencode.com	https://auth-qa.qencode.com
Qencode API	https://api.qencode.com	https://api-qa.qencode.com

以下の手順では本番環境のエンドポイントを使用します。QA 環境でテストするには、QA の URL に差し替え、QA ポータルにサインインしてください。

クライアントを接続する

エンドポイント： https://mcp.qencode.com/mcp — 以下のすべてのクライアントで共通です。ブラウザーが開いたら、Qencode アカウントにサインインし、アクセスを承認してください。

QA（内部テスト）： https://mcp-qa.qencode.com/mcp を使用し、代わりに QA ポータルにサインインしてください。

クライアント	追加する場所	MCP URL／設定
Claude（チャット）	メッセージボックス → + → コネクター → コネクターを追加	https://mcp.qencode.com/mcp
Claude Code	ターミナル	claude mcp add --transport http qencode https://mcp.qencode.com/mcp
ChatGPT	アプリ → Qencode を検索 → 接続；または開発者モード → アプリを作成	コネクター URL：https://mcp.qencode.com/mcp
Gemini	~/.gemini/settings.json → mcpServers	"httpUrl": "https://mcp.qencode.com/mcp" — その後、CLI で /mcp auth qencode を実行します
Cursor	設定 → ツールと MCP → 新しい MCP サーバー（または ~/.cursor/mcp.json）	"url": "https://mcp.qencode.com/mcp" — 保存後に Cursor を再起動してください

Cursor（mcp.json）：

{
  "mcpServers": {
    "qencode": { "url": "https://mcp.qencode.com/mcp" }
  }
}

Gemini（settings.json）：

{
  "mcpServers": {
    "qencode": {
      "httpUrl": "https://mcp.qencode.com/mcp",
      "timeout": 30000,
      "trust": false
    }
  }
}

ヒント：接続する前に、ブラウザーで portal.qencode.com にサインインしておくと、OAuth がスムーズに進みます。

コネクターが提供する機能

ツール

トランスコードとジョブ

ツール	説明
transcode_video	ソース URL から 1 つ以上の出力先へのジョブを送信します。便利なラッパーで、指定されていない場合は encoder_version: 2（VMAF の場合は 1）を自動で追加します。
start_encode2_raw	直接指定するための手段です。Qencode API が期待する形式で、完全な query JSON をそのまま使用してジョブを送信します。
get_job_status	task_token によるジョブのステータスを一度だけ取得します。
get_job_status_detailed	各出力形式の進捗状況や出力の詳細を含む、完全かつ正確なジョブステータスです。
list_jobs	現在の会話の task_tokens を対象に、ジョブカードをインライン表示します。ステータスバッジ、フィルター、展開可能な行、出力 URL が含まれます。実行中のジョブがある間、カードは自動で更新されます。
fetch_job_result	分析ジョブが生成した結果ファイル（文字起こし、VMAF レポート、メタデータ、分類）の内容を読み取ります。
wait_for_job	非推奨です。すぐに応答して list_jobs を案内します。以前の会話で「ツールが見つかりません」と表示されないように残されています。
search_qencode_docs	レシピとリファレンスドキュメントの組み込みナレッジベースを検索します。
fetch_qencode_doc	qencode:// URI でナレッジベースのリソースの全内容を取得します（resources/read に相当するツールベースの機能です）。

再生

ツール	説明
open_player	再生可能な結果（プログレッシブ MP4／WebM または HLS／DASH マニフェスト）をインラインで表示します。サーバーは呼び出し元のホストのサンドボックスポリシーを適用するため、許可されるソースのオリジンはクライアントによって異なります。
refresh_jobs	ジョブカード専用のサイレントポーリングです。エージェントから直接呼び出すことを想定していません。カードの自動更新と更新ボタンを支えます。

メディアストレージ

Qencode Media Storage のバケット管理と取り込みを行います。トランスコードツールと同じ OAuth 許可を使用するため、追加のスコープや再同意は必要ありません。

ツール	説明
list_buckets	アカウントで利用できる Media Storage のバケットを一覧表示します。
create_bucket	新しいバケットを作成します。明示的なリクエストがあった場合にのみ呼び出されます。destination が指定されていないことを補うためには使用しません。
list_objects	バケットの内容を参照します。
get_download_url	既存のオブジェクトの、期限付きダウンロード URL を返します。
download_url_to_bucket	公開 URL からバケットへのサーバー側コピーを行います（トランスコードなしの取り込み）。

リソース

このサーバーには、レシピとリファレンスドキュメントからなるナレッジベースが付属しています。MCP リソースとして公開されているため、エージェントは必要なものだけを取得できます。主な URI は次のとおりです。

• qencode://docs/best-practices — エージェントが自動的に適用するコンポジションのデフォルト設定
• qencode://docs/storage — 保存先の互換性一覧（Qencode S3、R2、AWS S3、Azure、B2、FTP/SFTP）
• qencode://docs/error-codes — エラーコード → 原因 → 修正方法
• qencode://docs/gotchas — API の分かりにくい仕様
• qencode://schema/digest — start_encode2 の全属性リファレンス
• qencode://recipe/<slug> — 機能フローごとに用意されたレシピ：ai_detection、ai_upscaling、audio_outputs、callbacks、clip_trim、codec_av1、codec_lcevc、drm_aes128、drm_buydrm、drm_doverunner、drm_expressplay、drm_fairplay_ezdrm、drm_forensic_watermark、drm_playready_ezdrm、drm_widevine_ezdrm、hdr_to_sdr、hls_abr、incremental_abr、mp4_ladder、per_title_encoding、refresh_abr_playlist、reliability、repack、rotate_deinterlace、smart_crop、smart_thumbnail、speech_to_text、stitching、subtitles、thumbnails、video_intelligence、video_metadata、vmaf_quality、vr_360、vr_mode、watermark_logo、waveform

目的に合ったレシピ URI を見つけるには、search_qencode_docs を使用してください。

プロンプト（スラッシュコマンド）

MCP プロンプトを表示するクライアントでは、40 個の単発テンプレートを利用できます。それぞれのテンプレートは、対応する qencode://recipe/... リソースを読み込み、start_encode2_raw を使用して送信するようエージェントに指示します。

ABR／パッケージング： encode_hls_abr、encode_dash_abr、encode_mp4_ladder、encode_incremental_rung、encode_refreshing_playlist、remux_repack

コーデック／品質： encode_av1、encode_lcevc、tune_per_title、check_vmaf、ai_upscale_video、convert_hdr_to_sdr

音声／画像／テキスト： extract_audio、generate_thumbnails、generate_smart_thumbnails、generate_waveform、transcribe、add_subtitles

編集／フレーミング： trim_clip、rotate_video、deinterlace_video、enable_smart_crop、add_watermark、add_html_overlay

イマーシブ： enable_vr_mode、inject_360_metadata

分析： get_video_metadata、analyze_video、detect_ai_generated

プローブ／スティッチ： stitch_videos

本番環境向けフック： enable_callbacks、enable_reliability

DRM： encode_aes128_hls、encode_widevine_ezdrm、encode_playready_ezdrm、encode_fairplay_ezdrm、encode_drm_buydrm、encode_drm_expressplay、encode_drm_doverunner、encode_forensic_watermark

ソース URL のルール

transcode_video と start_encode2_raw では、https://、http://、s3://、tus: スキームの source 値を受け付けます。FTP/SFTP およびプライベート URL／メタデータ URL は、ツール境界で拒否されます（SSRF 防御）。制限事項については docs/security/THREAT_MODEL.md を参照してください。

セキュリティ

認証方式は OAuth 2.1 のみです。静的な API キーを使用するモードはありません。Qencode API キーがポータルの外に出ることはありません。サーバーは、内部ポータルエンドポイントを介して、リクエストごとに新しい短期間有効のセッショントークンを生成します。ソース URL はツール境界で検証されます（SSRF 防御についてはソース URL のルールを参照してください）。

脅威モデルと攻撃的なテストの網羅範囲については、docs/security/THREAT_MODEL.mdを参照してください。

開発

uv venv && uv pip install -e ".[dev]"
NO_NETWORK=1 pytest -q              # offline L1 + L2 + L5 (~900 tests)
pytest -m protocol                # MCP wire conformance only
pytest -m unit                    # per-tool logic (FakeQencode)
pytest -m security                # OWASP MCP Top 10 adversarial suite

プロトコルテストは完全にオフラインで実行されます（Authorization Server、ポータル、Qencode API をモック）。CI は Jenkins ジョブ mcp_automated_tests（Jenkinsfile.manual）で実行されます。各レイヤーを手動で選択できるほか、L3 の夜間 cron と L4 の週次 cron があります。

サポート対象の MCP プロトコルバージョン

クライアントは initialize でバージョンをネゴシエートします。このサーバーは、主要バージョンとして MCP 2025-11-25 を対象としています。JSON-RPC のバッチ処理の動作は以前のリビジョンで異なるため、CI では 2025-06-18 に対する適合性テストも実行します。基盤となる SDK がネゴシエートする範囲を超えて、2025-03-26 以前のワイヤーセマンティクスをサポートするとは表明していません。

バージョン	サポート状況	備考
2025-11-25	主要バージョン	Streamable HTTP、使用時の再開可能な SSE
2025-06-18	CI マトリックス	2025 年半ばのクライアント向け回帰防止策
2025-03-26	対象外	バッチ処理のセマンティクスが 2025-06-18 と異なります

ディレクトリの掲載（Glama）

ユーザーがインストールするコネクターは、上記のホスト型エンドポイントです。 Glama Servers / awesome-mcp-servers のスコアリング専用として、このリポジトリには qencode-mcp-inspect（stdio、ダミーの環境変数、 tools/call は拒否）も含まれています。これはサポート対象のクライアントトランスポートではありません。詳細は docs/glama-release.md を参照してください。

関連ドキュメント

• ローカルサーバー／環境変数：docs/local-development.md
• テストレイヤー（L1～L5）：docs/testing.md および tests/README.md
• ライブ QA／PROD 環境に対する L3 テスト：tests/integration/README.md
• L4 エージェント評価：evals/README.md
• リリース前チェック：docs/release-checklist.md

バージョニングポリシー

このコネクターは、MCP インターフェース（ツール、プロンプト、リソース、OAuth スコープ、サポート対象のプロトコルバージョン）に適用される SemVer に従います。Qencode HTTP API の変更は対象外です（それはコネクターではなく、API 自体の責任です）。

• MAJOR — インターフェースに破壊的変更を加える場合：ツール／プロンプト／リソースの削除または名前変更、任意だった引数の必須化、再同意を必要とする OAuth スコープの追加または厳格化、あるいはサポート対象の MCP プロトコルバージョンの削除。
• MINOR — 後方互換性のある追加：新しいツール／プロンプト／リソース、新しい任意引数、または新たにサポートされるプロトコルバージョン。
• PATCH — インターフェースの形状に変更がない場合：ツール／プロンプトの説明文の言い換え、ナレッジベース／ドキュメントの更新、バグ修正。

インターフェースの変更は、tests/protocol/ にあるスナップショットテストで保護されています。インターフェースを変更する場合は、スナップショットを再生成し（python scripts/regen_tools_snapshot.py）、同じ PR でバージョンを更新してください。pyproject.toml、src/qencode_mcp/__init__.py、server.json、新しい CHANGELOG.md のエントリーがすべて一致している必要があります。

リンク

• 変更履歴：CHANGELOG.md
• OAuth 2.1 認可サーバー仕様：docs/oauth-spec.md
• Qencode ポータル：https://portal.qencode.com（本番環境） · https://portal-qa.qencode.com（QA）
• Qencode API リファレンス：https://docs.qencode.com/api-reference/transcoding