Transloadit MCP Server

@transloadit/mcp-server

@transloadit/node を基盤に構築された Transloadit MCP サーバー（Streamable HTTP + stdio）です。

URL で接続する（推奨）

ホスト型サーバーの URL は次のとおりです。

https://api2.transloadit.com/mcp

URL を使って MCP クライアントに追加してください。クライアントは API2 を OAuth 認可サーバーとして検出し、Transloadit Console のブラウザー同意ページを開いて、短期間有効なトークンとリフレッシュトークンを保持します。API キーが Workspace の外に出ることはありません。

ホスト型エンドポイントは、ツールの実行前にサインインを求めます。Robot のドキュメントとリンティングも対象です。これは、MCP クライアントがエンドポイントからチャレンジを受けた場合にのみ OAuth を開始するためです。Robot のドキュメントとリンティングではスコープは不要です。アカウントなしでこれらを使うには、サーバーを自分で実行してください（「セルフホスト」を参照）。

Claude Code

claude mcp add --transport http transloadit https://api2.transloadit.com/mcp
claude mcp login transloadit

非対話型の実行（たとえば claude -p）では、MCP ツールを明示的に許可してください。

claude -p "List templates" \
  --allowedTools mcp__transloadit__* \
  --output-format json

Claude.ai と Claude Desktop

Settings → Connectors → Add custom connector の順に選択し、https://api2.transloadit.com/mcp を入力します。Claude が API2 に自身を登録し、同意ページを開きます。

ChatGPT

Settings → Apps & Connectors → Advanced → Developer mode → Create の順に選択し、上記の URL を入力して、認証方式に OAuth を設定します。チャットに添付したファイルは attachments として transloadit_create_assembly に渡され、結果は Assembly result widget に表示されます。

ChatGPT と Codex のカタログ用プラグインマニフェスト（plugin.json、mcp.json、およびフォールバックの .codex-plugin/plugin.json）は、このパッケージディレクトリにあります。スキルファイルを同梱するのではなく、ホスト型サーバーと https://transloadit.com/.well-known/skills/index.json にある Agent Skills カタログを参照します。

Codex

codex mcp add transloadit --url https://api2.transloadit.com/mcp

Codex はすぐに同意ページを開きます。後で再度サインインするには、codex mcp login transloadit を実行してください。

または、~/.codex/config.toml に設定します。

[mcp_servers.transloadit]
url = "https://api2.transloadit.com/mcp"

Cursor

~/.cursor/mcp.json：

{
  "mcpServers": {
    "transloadit": {
      "url": "https://api2.transloadit.com/mcp"
    }
  }
}

MCP Inspector

npx @modelcontextprotocol/inspector --cli https://api2.transloadit.com/mcp

CI とヘッドレスエージェント

ブラウザーを利用できない環境では、Auth Key からベアラートークンを発行し、Authorization: Bearer <token> として渡します。

npx -y @transloadit/node auth token --aud mcp

信頼できる環境（バックエンド、CI、またはローカルシェル）でこのトークンを生成し、エージェントのランタイムに渡してください。次の方法で発行できます。

• CLI：npx -y @transloadit/node auth token --aud mcp
• API：POST https://api2.transloadit.com/token（キー／シークレットを使った HTTP Basic 認証）
• Node SDK：authKey と authSecret を指定して Transloadit をインスタンス化し、client.mintBearerToken({ aud: 'mcp' }) を呼び出します。

対話型 CLI セッションでは、npx -y @transloadit/node auth login（デバイスフロー）を実行し、保存された認証情報を再利用することもできます。

ベアラートークンは API2 リクエストにおける署名認証を満たします。署名チェックはキー／シークレットを使ったリクエストに適用されます。

セルフホスト

エージェントが実行される場所でサーバーを実行し、TRANSLOADIT_KEY と TRANSLOADIT_SECRET を設定すると、サーバーが API 認証を自動的に処理します。

インストール

npm install @transloadit/mcp-server

Stdio

TRANSLOADIT_KEY=MY_AUTH_KEY TRANSLOADIT_SECRET=MY_SECRET_KEY npx -y @transloadit/mcp-server stdio

Auth Keys は 1 つの HMAC アルゴリズムで署名します。Console で「Allow signing Smart CDN URLs」（デフォルト）を有効にして作成したキーには sha256 が必要です。そのため、Console に表示されるキー用のスニペットのとおり、TRANSLOADIT_SIGNATURE_ALGORITHM=sha256 を追加してください。それ以外のキーでは、デフォルトの sha384 が使われます。一致しない場合は mcp_invalid_signature が返され、ヒントにそのキーで必要なアルゴリズムが示されます。

HTTP

TRANSLOADIT_KEY=MY_AUTH_KEY TRANSLOADIT_SECRET=MY_SECRET_KEY \
npx -y @transloadit/mcp-server http --host 127.0.0.1 --port 5723

HTTP モードを localhost 以外のホストにバインドする場合、TRANSLOADIT_MCP_TOKEN（またはホスト型モードの TRANSLOADIT_MCP_RESOURCE_METADATA_URL）が必要です。

Docker

docker run -i --rm \
  -e TRANSLOADIT_KEY=MY_AUTH_KEY \
  -e TRANSLOADIT_SECRET=MY_SECRET_KEY \
  ghcr.io/transloadit/mcp-server:latest

Docker 経由で HTTP モードを使う場合は、stdio のエントリーポイントを上書きし、ポートを公開して、トランスポートトークンを設定してください。0.0.0.0 へのバインドにはトークンが必要です。

export TRANSLOADIT_MCP_TOKEN="$(openssl rand -hex 32)"
docker run --rm \
  -e TRANSLOADIT_KEY=MY_AUTH_KEY \
  -e TRANSLOADIT_SECRET=MY_SECRET_KEY \
  -e TRANSLOADIT_MCP_TOKEN \
  -p 5723:5723 \
  --entrypoint transloadit-mcp \
  ghcr.io/transloadit/mcp-server:latest \
  http --host 0.0.0.0 --port 5723

TRANSLOADIT_MCP_TOKENの説明

TRANSLOADIT_MCP_TOKENは、セルフホスト型MCPトランスポートトークンです。API2ではなく、ご自身のHTTP MCPエンドポイント （npx -y @transloadit/mcp-server http）を保護します。

• 高エントロピーのシークレットを任意に設定してください。
• MCP クライアントからAuthorization: Bearer <TRANSLOADIT_MCP_TOKEN>として送信してください。
• /token経由で発行されるものではありません。
• https://api2.transloadit.com/mcpで使用するAPI2 Bearerトークンとは別のものです。

トークンを生成してから、HTTPモードを起動します。

export TRANSLOADIT_MCP_TOKEN="$(openssl rand -hex 32)"
npx -y @transloadit/mcp-server http --host 0.0.0.0 --port 5723

セルフホスト型クライアントのセットアップ

セルフホスト型を利用する場合、多くはMCPクライアントにサーバーを追加し、クライアントからstdioで起動します。

Claude Code

claude mcp add --transport stdio transloadit \
  --env TRANSLOADIT_KEY=... \
  --env TRANSLOADIT_SECRET=... \
  -- npx -y @transloadit/mcp-server stdio

Codex CLI

codex mcp add transloadit \
  --env TRANSLOADIT_KEY=... \
  --env TRANSLOADIT_SECRET=... \
  -- npx -y @transloadit/mcp-server stdio

~/.codex/config.tomlでツールを許可リストに追加します。

[mcp_servers.transloadit]
command = "npx"
args = ["-y", "@transloadit/mcp-server", "stdio"]
enabled_tools = ["transloadit_list_templates"]

Gemini CLI

gemini mcp add --scope user transloadit npx -y @transloadit/mcp-server stdio \
  --env TRANSLOADIT_KEY=... \
  --env TRANSLOADIT_SECRET=...

~/.gemini/settings.jsonでツールを許可リストに追加します。

{
  "mcpServers": {
    "transloadit": {
      "command": "npx",
      "args": ["-y", "@transloadit/mcp-server", "stdio"],
      "env": {
        "TRANSLOADIT_KEY": "...",
        "TRANSLOADIT_SECRET": "..."
      },
      "includeTools": ["transloadit_list_templates"]
    }
  }
}

Cursor

~/.cursor/mcp.json：

{
  "mcpServers": {
    "transloadit": {
      "command": "npx",
      "args": ["-y", "@transloadit/mcp-server", "stdio"],
      "env": {
        "TRANSLOADIT_KEY": "...",
        "TRANSLOADIT_SECRET": "..."
      }
    }
  }
}

OpenCode

~/.config/opencode/opencode.json：

{
  "mcp": {
    "transloadit": {
      "command": "npx",
      "args": ["-y", "@transloadit/mcp-server", "stdio"],
      "env": {
        "TRANSLOADIT_KEY": "...",
        "TRANSLOADIT_SECRET": "..."
      }
    }
  }
}

認証モデル

ホスト型（https://api2.transloadit.com/mcp）

• Bearerトークンなしのリクエストには、次の内容を含む401が返されます。 WWW-Authenticate: Bearer resource_metadata="https://api2.transloadit.com/.well-known/oauth-protected-resource/mcp"。 MCPクライアントはこのドキュメントを参照し、API2の認可サーバー（認可コード＋PKCE、 Dynamic Client RegistrationまたはClient ID Metadata Documents）にアクセスします。
• bareなGET /mcpもこれに含まれます。一部のクライアント（Codex）は、このプローブから認可サーバーを 検出するためです。そのため、ディレクトリのヘルスチェックには200ではなく401が返りますが、JSON本文には name、status、docsが含まれます。セルフホスト型および認証なしのデプロイでは、bareなGETに引き続き 200が返されます。
• Bearerトークン（OAuthまたは--aud mcpで発行されたもの）はAPI2に転送され、API2がすべての呼び出しで 検証します。拒否されたトークンや期限切れのトークンの場合、isErrorと _meta["mcp/www_authenticate"]を含むツール結果が返されるため、ChatGPTとClaudeは再接続を促します。
• 各ツールはsecuritySchemes（トップレベルと_meta内）を宣言します。ホスト型エンドポイントは 認証されていないリクエストすべてにチャレンジするため、すべてのツールがそこでoauth2を宣言します。 Robotドキュメントとリンティングツールはスコープを要求しません。
• セルフホスト型サーバーでキー／シークレットが拒否された場合や期限切れの場合は、OAuthチャレンジなしで mcp_credentials_rejectedとして報告されます。修正できるのはオペレーターだけだからです。
• ブラウザーからのリクエストは、ChatGPT、Claude、Transloadit、またはループバックのオリジンから送信する 必要があります。Originヘッダーのないリクエスト（CLI、サーバー）は制限されません。リストを変更するには allowedOriginsを設定してください。
• TRANSLOADIT_MCP_UPSTREAM_SECRETは、リレーされたaud=mcpトークンがホスト型サービスから届いたことを API2が確認できるよう、Transloadit自身のデプロイで設定されます。セルフホストには不要です。 認証済みの呼び出しはすべて失敗するため、ホスト型モードはこの値がないと起動しません。

セルフホスト型

• デフォルトでは、stdioとlocalhost HTTPにMCP認証は必要ありません。
• localhost以外のHTTPでは、TRANSLOADIT_MCP_TOKEN（ご自身で定義する静的シークレット）が必要です。
• Transloadit APIへのライブ呼び出しでは、次のいずれかを使用します。
  • MCPリクエストヘッダーから受け取るBearerトークン、または
  • TRANSLOADIT_KEY＋TRANSLOADIT_SECRET

設定

環境変数

• TRANSLOADIT_KEY
• TRANSLOADIT_SECRET
• TRANSLOADIT_SIGNATURE_ALGORITHM（任意。sha1、sha256、sha384 のいずれか。デフォルトは sha384。 Auth Key と一致している必要があります）
• TRANSLOADIT_MCP_TOKEN
• TRANSLOADIT_MCP_RESOURCE_METADATA_URL（ホストモード：401 チャレンジで通知する保護対象リソースのメタデータ URL）
• TRANSLOADIT_MCP_UPSTREAM_SECRET（ホストモードのみ。Transloadit のデプロイメントによって設定され、転送されたベアラートークンとともに Transloadit-Mcp-Upstream として API2 に送信されます）
• TRANSLOADIT_MCP_RESULT_DOMAINS（任意。結果ウィジェットでプレビューの読み込みやリンクに使用できる、カンマ区切りのオリジン。https://tmp-us-east-1.transloadit.net のような完全一致、またはワイルドカードホストを指定します。デフォルトは https://*.transloadit.com,https://*.transloadit.net,https://*.r2.dev）
• TRANSLOADIT_MCP_WIDGET_DOMAIN（任意。デフォルトは https://transloadit.com。ChatGPT が結果ウィジェットを提供するオリジン。_meta["openai/widgetDomain"] として送信されます）
• TRANSLOADIT_MCP_CONSOLE_URL（任意。デフォルトは https://transloadit.com。ウィジェットのディープリンクに使用する Console のオリジン）
• TRANSLOADIT_ENDPOINT（任意。デフォルトは https://api2.transloadit.com）
• TRANSLOADIT_MCP_METRICS_PATH（任意。デフォルトは /metrics）
• TRANSLOADIT_MCP_METRICS_USER（任意）
• TRANSLOADIT_MCP_METRICS_PASSWORD（任意）

CLI フラグ

• npx -y @transloadit/mcp-server http --host 127.0.0.1 --port 5723
• npx -y @transloadit/mcp-server http --endpoint https://api2.transloadit.com
• npx -y @transloadit/mcp-server http --config path/to/config.json

JSON 設定では、allowedOrigins、resourceMetadataUrl、signatureAlgorithm、resultDomains、widgetDomain、consoleUrl など、createTransloaditMcpHttpHandler() と同じキーを指定できます。

ツール一覧

ツール	アカウント	OAuth スコープ	備考
transloadit_lint_assembly_instructions	不要	なし	読み取り専用
transloadit_list_robots	不要	なし	読み取り専用
transloadit_get_robot_help	不要	なし	読み取り専用
transloadit_create_assembly	必要	assemblies:write、templates:read	破壊的、オープンワールド（URL インポート）、ウィジェット
transloadit_get_assembly_status	必要	assemblies:read	読み取り専用
transloadit_wait_for_assembly	必要	assemblies:read	読み取り専用、結果ウィジェット
transloadit_list_templates	必要	templates:read	読み取り専用
transloadit_get_profile	必要	assemblies:read、templates:read	読み取り専用、_meta["openai/profile"]

すべてのツールには、title、readOnlyHint、destructiveHint、idempotentHint、openWorldHint のアノテーションが付与されています。破壊的な操作を行うのは transloadit_create_assembly のみです。/s3/store などのエクスポート用 Robots は、保存先のファイルを上書きする可能性があるため、ホスト側で確認を求める必要があります。

transloadit_lint_assembly_instructions は、結合済みの完全な指示をローカルで検証します。template_id で指定された Template は取得しません。リンティングの前に Template を解決し、Assembly またはリプレイによるオーバーライドを結合してください。たとえば、ocr_provider を継承する OCR Step の場合、このツールに渡す指示にそのプロバイダーを含める必要があります。 securitySchemes はサーバーの実行方法によって異なります。ホスト型（TRANSLOADIT_MCP_RESOURCE_METADATA_URL）では、上記のスコープを持つ oauth2 がすべてのツールに宣言されます。TRANSLOADIT_KEY と TRANSLOADIT_SECRET を保持するサーバーでは、すべてのツールに noauth が宣言されます。それ以外の場合、アカウントツールには oauth2、その他のツールには noauth が宣言されます。TRANSLOADIT_MCP_TOKEN と TRANSLOADIT_MCP_RESOURCE_METADATA_URL は併用できません。

認証済みの tools/list が、結果に関するショートカット、説明、フィールドスキーマの参照元です。同期間隔で同期される alphalib Builtin マニフェスト には、レビュー済みのバージョン固定と一時的なフィールド除外が含まれます。MCP アダプターはこれらの ID からツール名とタイトルを生成し、@transloadit/zod/v4/builtinTemplates を通じてカタログスキーマを利用します。alphalib の同期により、別の MCP レジストリーを用意せずに、承認済みの追加、名前変更、削除、ゲートの変更が反映されます。

各ショートカットの説明は、API2 の担当者が Builtin 定義とともに作成する、ツールで使える summary で始まります。これは、読み込み後はクレデンシャルのカタログ概要、それ以外の場合は同期済みの mcpBuiltinTemplateSummaries であり、サーバーカードとカタログ取得前の tools/list で使用されます。カタログの長い description はツールのテキストではありません。単体の draft-07 fields_schema と content.fields のデフォルト値は、API2 の Template カタログから取得されます。デフォルト値は検証前にマージされ、JSON の型は保持されます。スキーマ注釈は保守的なものにとどめ、実行時の相互フィールド検証を正式なものとして扱います。契約が null または存在しない場合、そのショートカットは利用できません。汎用ツールの動作は従来どおりです。

マニフェストの一時的なレガシー VP8 webm ゲートは、api2#9960 がデプロイされ、検証されるまで維持されます。ソーシャル向けキャプションは後回しです。文字起こしの言語ヒントは音声を翻訳しません。

カタログの読み込みには、再試行なしで全体に3秒の期限が適用されます。認証済みのカタログが停止している間も、レビュー済みの名前は寛容なフィールド設定で検出可能です。ただし、各呼び出しでは引き続き最新の契約を取得して検証します。不正なスキーマや、デフォルト値に依存する合成スキーマも、寛容な検出設定を使用し、実行時にデフォルト値をマージしてから完全な検証を行います。transloadit_create_assembly と同じ fields とファイル／添付ファイル／アップロード／待機オプションを指定してください。サンドボックスファイルの場合は、expected_uploads を設定して返されたアップロードコマンドを実行し、その後 transloadit_wait_for_assembly を呼び出します。SDK には ドキュメント抽出レジストリーの修正 がすでに含まれています。

transloadit_list_templates は次をサポートします。

• include_builtin：all、latest、exclusively-all、exclusively-latest
• include_content：各テンプレート項目に解析済みの steps を含めます

Builtin 項目には、保守的な忠実度メタデータや、スキーマが宣言されていない古い Builtin に対する null も含め、fields_schema が変更されずに含まれます。Workspace Template にはこのプロパティは含まれません。

transloadit_get_profile は、現在のクレデンシャルに対応する Workspace の { id, name?, nickname? } を返します。これは、その Workspace 自身の Assemblies または Templates から取得されます。

結果ウィジェット

transloadit_create_assembly と transloadit_wait_for_assembly は、MCP Apps リソース ui://transloadit/assembly-result（_meta.ui.resourceUri、および _meta["openai/outputTemplate"]）にリンクします。 MCP Apps に対応するホストでは、各ステップの結果が画像、動画、音声のプレビュー、 ダウンロードリンク、「コンソールで開く」リンク、「テンプレートとして保存」ショートカットとともに表示されます。MCP Apps の 2026-01-26 プロトコル（appInfo を含む ui/initialize）に対応し、ChatGPT の window.openai も読み取ります。 CSP では https://*.transloadit.com、https://*.transloadit.net、https://*.r2.dev （結果バケット）が許可されています。TRANSLOADIT_MCP_RESULT_DOMAINS または resultDomains でリストを上書きできます。 ChatGPT ではウィジェットが使用する正確なホストが必要なため、結果バケットが分かっているデプロイでは、ワイルドカードではなくオリジンとして指定してください。ウィジェットからリンクを開くには、ChatGPT に redirect_domains も必要です。サーバーは結果のオリジンとコンソールのオリジンをここに送信します。ChatGPT は _meta["openai/widgetDomain"]（TRANSLOADIT_MCP_WIDGET_DOMAIN）で指定されたオリジンからウィジェットを配信します。Claude はサーバー URL から値を導出し、それ以外を拒否するため、ui.domain は未設定のままにします。

入力ファイル

export type InputFile =
  | {
      kind: 'base64'
      field: string
      base64: string
      filename: string
      contentType?: string
    }
  | {
      kind: 'url'
      field: string
      url: string
      filename?: string
      contentType?: string
    }

チャットファイルを添付するホスト（ChatGPT）は、_meta["openai/fileParams"] の宣言に従って、ファイルを代わりに attachments として渡します。

type Attachment = {
  download_url: string
  file_id: string
  mime_type?: string
  file_name?: string
}

各添付ファイルは URL 入力（attachment_1、attachment_2、…）となり、以下の URL の規則に従います。

ローカルまたはサンドボックス内にしか存在しないファイル

ファイルがローカルまたはサンドボックス内にしか存在しない場合は、expected_uploads を指定して transloadit_create_assembly を呼び出し、返された upload_instructions を実行します。これには、サンドボックスから Transloadit へのアウトバウンド HTTPS 接続が必要です（Claude.ai の場合：Settings → code execution network access で接続を許可してください）。Claude.ai などのホストはチャットの添付ファイルをコネクタツールに渡しません。また、ツール引数の base64 はごく小さなファイル以外には実用的ではないため、エージェントがファイルを直接アップロードします。

1. 指示と expected_uploads: 1（ファイルごとに 1 件、1 回の呼び出しにつき最大 100 件）を指定して transloadit_create_assembly を呼び出します。Assembly はアップロードを待機するようになるため、wait_for_completion: true を指定しても、呼び出しはすぐに戻ります。
2. 各 upload_instructions エントリには、tus エンドポイント、tus メタデータ（assembly_url、fieldname）、すぐに実行できる curl コマンドが含まれています。FILE にファイルのパスを設定し、bash シェルで実行してください。ファイルのアップロードが完了すると 201 が出力されます（tus の作成とアップロードを 1 回のリクエストで行います）。
3. Assembly URL を指定して transloadit_wait_for_assembly を呼び出します。

assembly_url と expected_uploads（Assembly の作成時点で想定されているすべてのアップロード）を指定して transloadit_create_assembly を呼び出すと、既存の Assembly が引き続き待機しているアップロード用の upload_instructions が提供されます。

コマンドに認証情報は含まれません。Assembly URL のみがアクセス権限となり、アップロードを待機している間、その Assembly にファイルを追加できます。

制限事項

これらの制限は、インラインの JSON／base64 ペイロードに適用されます。より大きなファイルには、公開 URL を使用するか、npx -y @transloadit/node upload を使って ご自身のマシンからアップロードしてください。

• ホスト型のデフォルトのリクエストボディ上限：1 MiB
• ホスト型の maxBase64Bytes：デコード後 512,000 バイト
• セルフホスト型のデフォルトのリクエストボディ上限：10 MiB

maxRequestBodyBytes（ハンドラーオプションまたは JSON 設定キー）を設定して、ボディの上限を変更できます。上限を超える リクエストには HTTP 413 が返され、バッファリングされません。独自のボディパーサーをインストールする Express アプリでは、そこで上限を設定してください。

テンプレートがアップロードを想定している場合にサーバーがダウンロードする URL 入力は、リダイレクトを含め、呼び出しごとに合計 1 GiB、 ダウンロードごとに 10 分までです。これらの上限を変更するには、maxUrlDownloadBytes と urlDownloadTimeoutMs を設定してください。ホスト型 エンドポイントでは、ダウンロードを開始する前に、呼び出し元のトークンが API2 で検証されます。ダウンロード時間は以下の待機時間の上限に 含まれます。時間内に完了しない場合、Assembly は作成されず、呼び出しは mcp_preparation_timeout を返すため、安全に再試行できます。 ダウンロードはその約 1 秒後に停止され、ファイルは削除されます。

Assembly の待機

MCP ホストは、実行時間が長すぎるツール呼び出し（ChatGPT では約 1 分後）を中断し、再試行することがあります。その場合、2 つ目の Assembly が作成されます。そこで、 transloadit_create_assembly、Builtin のショートカット、および transloadit_wait_for_assembly は、より大きな wait_timeout_ms／timeout_ms が指定されていても、最大 45 秒まで待機します。この上限に達すると、呼び出しは現在のステータスの Assembly を返します（最後のステータス読み取りや処理の遅い作成リクエストには、さらに最大 5 秒かかることがあるため、 この分だけホストの上限より短い時間に設定してください）。返される Assembly には running: true と mcp_assembly_still_running 通知が含まれます。アップロードと処理は 続行され、transloadit_wait_for_assembly または transloadit_get_assembly_status でその後の状況を確認できます。上限を変更するには、 maxWaitMs（オプションまたは JSON 設定キー）または TRANSLOADIT_MCP_MAX_WAIT_MS を設定してください。

URL 入力とテンプレートの動作

URL 入力の動作は、テンプレート／指示によって異なります。

• /http/import Step がある場合、MCP はその Step の url を設定または上書きします。
• テンプレートがアップロード（:original または /upload/handle）を想定している場合、MCP は tus 経由でダウンロードしてからアップロードします。 これらのダウンロードで使用できるのは、公開 HTTP(S) URL のみです。プライベートネットワークのアドレスへのリダイレクトを含め、プライベートネットワークを 宛先とする URL は拒否されます。
• テンプレートが入力ファイルを受け取らない場合、URL 入力は無視され、警告が返されます。
• allow_steps_override=false で /http/import のみが動作する場合、URL 入力は拒否されます。

caption-video、convert-to-pdf、encode-video、extract-text、 prepare-image、remove-background、transcribe、video-covers の Builtin ショートカットは、呼び出しのすべてのファイルと添付ファイルが URL の場合 （caption-video では 1 件、その他では最大 10 件）、URL を template_id と並べて API2 に input_url として送信します。これにより、Transloadit がファイルを直接取得するため、Assembly はすぐに作成され、大きなファイルによって MCP サーバーがダウンロードしたり、処理が滞ったりすることはありません。API2 は URL（またはリダイレクトと Content-Disposition）を基にファイル名を付けるため、ホストの添付ファイルなど、ファイル名を指定された入力では、引き続き上記のダウンロード手順が使用されます。また、URL と base64 ファイルまたはサンドボックスのアップロードを混在させる呼び出し、upload_behavior: 'none' を指定した呼び出し、API2 が拒否する URL（空白、|、${…}、4096 文字超）も同様です。API2 がリクエストの input_url を拒否した場合、そのエラーが通常どおり返されます。対象となる Builtin の一覧は alphalib の Builtin マニフェストを参照してください。

ローカルとホスト型のファイルアクセス

• MCP はセルフホスト環境とホスト型環境のどちらでも、base64 と URL の入力を受け付けます。ローカルファイルシステムの パスはツールの入力としてサポートされていません。
• 移行： これまで kind: 'path' を送信していたクライアントは、base64、公的な URL、 またはローカル CLI アップロードに切り替える必要があります。これは stdio とセルフホスト型サーバーにも適用されます。
• 公開 url 入力、小さな base64 ペイロードを使用するか、 npx -y @transloadit/node upload でローカルからアップロードします。
• expected_uploads を使用すると、帯域外の tus アップロードに備えて Assembly を開いたままにできます。

再開の動作

assembly_url が指定されている場合、MCP は Assembly のステータス（tus_uploads + uploads）を使ってアップロードを再開します。これには、安定したフィールド名とファイルのメタデータ（filename + size）が必要です。 アップロードを再開するには、同じ base64 または公開 URL の入力を再送信します。元の指示が省略されていても、URL 入力はダウンロードされて アップロードされます。再開によって既存の Assembly の Steps が変更されることはありません。ファイルの内容、フィールド名、ファイル名は 変更しないでください。これは tus アップロードを再開するものです。/http/import で実行した URL インポートは再送信する必要がありません。

Assembly ID は32文字の16進数である必要があります。Assembly URL は、Transloadit ホストまたは明示的に設定された API オリジンを参照し、 認証情報、クエリパラメーター、フラグメントを含んではなりません。MCP は ID を抽出し、設定済みの API エンドポイント経由で Assembly を解決します。呼び出し元から提供された Assembly URL を直接取得することはありません。MCP は Assembly の redirect_url を含め、API レスポンスのリダイレクトを追跡しません。カスタムエンドポイントでは開発用にローカルオリジンを使用できますが、 これによってプライベートネットワーク上の URL からファイルをダウンロードできるようにはなりません。

メトリクスとサーバーカード

• Prometheus メトリクスはデフォルトで GET /metrics から取得できます。
• TRANSLOADIT_MCP_METRICS_PATH または metricsPath で設定します。
• metricsPath: false で無効にできます。
• メトリクスのベーシック認証は、TRANSLOADIT_MCP_METRICS_USER + TRANSLOADIT_MCP_METRICS_PASSWORD または metricsAuth で任意に設定できます。
• 公開ディスカバリーの /.well-known/mcp/server-card.json は tools: ["dynamic"] を宣言します。 認証済みの tools/list では、すべてのツール、スキーマ、アノテーション、セキュリティスキームが提供されます。 ホスト型カードでは OAuth リソースメタデータの URL も公開されます。

MCP とスキル／CLI の使い分け

• 埋め込みランタイムでの実行（アップロード、Assembly、ポーリング、結果取得）には MCP を使用します。
• 人間が操作する単発のワークフロー（セットアップ、スキャフォールディング、ローカル自動化）にはスキル／CLI を使用します。

これらはガイドラインであり、厳密なルールではありません。両方を使うチームも多くあります。

MCP クライアントを検証する

公開済みの MCP サーバーとインストール済みの CLI（Claude Code、Codex CLI、 Gemini CLI）を使用して、ローカルでスモークテストを実行します。TRANSLOADIT_KEY + TRANSLOADIT_SECRET と、有効な CLI 認証が必要です。

node scripts/verify-mcp-clients.ts

コマンドのタイムアウトを変更するには、MCP_VERIFY_TIMEOUT_MS を設定します。

ドキュメント

• ウェブサイトのドキュメント：https://transloadit.com/docs/sdks/mcp-server/
• API トークンのドキュメント：https://transloadit.com/docs/api/token-post/

コントリビューション

前提条件

• Node.js 22+
• Corepack が有効な Yarn 4

依存関係をインストールする

リポジトリのルートから実行します。

corepack yarn install

変更を検証する

corepack yarn --cwd packages/mcp-server check

e2e テストを実行する

test:e2e の実行には、環境内に有効な Transloadit 認証情報が必要です。

corepack yarn --cwd packages/mcp-server test:e2e

変更を提出する

• 動作を変更する場合は、テストを追加または更新します。
• ユーザー向けの動作について、README とウェブサイトのドキュメントの内容を一致させます。
• transloadit/node-sdk で PR を作成します。