MCP Server
Transloadit MCP Server を使うと、エージェントクライアントから Transloadit のツールを直接呼び出せます。Assembly の作成と監視、Assembly Instructions の lint、Robot と Template の検出、結果のチャット表示に対応します。
Transloadit でエージェントができることの概要は、MCP 経由で使う Transloaditを参照してください。

接続方法
- URL で接続(推奨):
https://api2.transloadit.com/mcpをエージェントクライアントに追加し、ブラウザーでアクセスを承認します。インストールは不要で、キーをコピーする必要もありません。 - CI とヘッドレスクライアント: ブラウザーで承認できる人がいない環境では、Auth Key から発行した Bearer token を送信します。
- セルフホスト:
TRANSLOADIT_KEYとTRANSLOADIT_SECRETを使って、エージェントの近くでサーバーを自分で実行します。
2 つの接続方式
アプリが Transloadit アカウントにアクセスする方法は 2 つあります。どちらも各リクエストで Credential を送信しますが、誰が作成するか、何ができるか、どう無効化するかが異なります。
- OAuth(URL で接続):
https://api2.transloadit.com/mcpをアプリに貼り付け、1 つの Workspace に対する Transloadit の同意画面を承認します。アプリには自動更新され、個別に取り消せる限定アクセス(assemblies:read、assemblies:write、templates:read)が付与されます。コピーするものはなく、アプリは Connected appsに一覧表示されます。ChatGPT や Claude のようなホスト型チャットアプリではカスタムヘッダーを送れないため、この方式が必要です。 - Auth Key または Bearer token: Auth Key、またはそこから発行した Bearer token をツールにコピーします。キーを削除するまで、そのキーで許可された操作を実行でき、Connected apps には表示されません。自前のバックエンド、スクリプト、CI、セルフホストの MCP server、Zapier などの統合ではこちらが適しています。
| OAuth(URL で接続) | Auth Key または Bearer token | |
|---|---|---|
| 操作内容 | URL を 1 つ貼り付けて同意画面を承認 | キーまたは token をツールにコピー |
| アプリが取得するもの | 1 つの Workspace に対する自動更新される専用アクセス:assemblies:read、assemblies:write、templates:read | Auth Key が許可する範囲すべて |
| 確認場所 | Connected apps | Auth Keys |
| 無効化方法 | Connected apps でアプリを取り消す | Auth Key を削除する |
使い分け
- ChatGPT、Claude、Codex、Cursor、VS Code などで人がエージェントクライアントを接続する場合は、OAuth を使います。URL で接続を参照してください。
- 自分で実行するコードや、キーの入力を求めるツールには Auth Key または Bearer token を使います。CI とヘッドレスクライアントとセルフホストを参照してください。
URL で接続
ホスト型サーバーの URL は次のとおりです。
https://api2.transloadit.com/mcp
この URL を MCP クライアントに追加します。クライアントは Transloadit API を OAuth の認可サーバーとして検出し、Transloadit Console で同意ページを開いたあと、アクセス token と refresh token を保持します。Auth Secret がアカウント外に出ることはありません。
ホスト型エンドポイントでは、どのツールを実行する前でもサインインが必要です。これには Robot のドキュメントと lint も含まれます。MCP クライアントは、エンドポイントから要求されたときにだけ OAuth を開始するためです。アカウントなしで Robot のドキュメントと lint を使う場合は、サーバーを自分で実行してください。
同意ページ
接続すると、ブラウザーで同意ページが開きます。そこにはアプリ名、戻り先、要求している権限が表示されます。アプリに使用を許可する Workspace を選んで承認します。
承認すると、その Workspace に表示された権限だけを持つ専用の Auth Key が作成されます。説明欄にはアプリ名に続けて via OAuth と日付が入ります。MCP 接続で取得できるのは最大で assemblies:write、assemblies:read、templates:read です。同意ページには各アクセス token の有効期間も表示されます(MCP server では 1 週間)。アプリはこれを自動で更新します。アクセスを取り消すには、Console の
Connected appsを開いてください。承認済みの各アプリについて、権限と最終使用日時が一覧表示されます。ここで取り消すと、その場でアプリのアクセスが終了します。
Claude Code
claude mcp add --transport http transloadit https://api2.transloadit.com/mcp
次に、Claude Code で /mcp を実行し、transloadit を選んで認証します。あるいはシェルから
claude mcp login transloadit を実行してもかまいません。どちらでもブラウザーで同意ページが開きます。
claude -p のような非対話実行では、Transloadit のツールを明示的に許可します。
claude -p "List my Templates" \
--allowedTools 'mcp__transloadit__*' \
--output-format json
Claude.ai と Claude Desktop
Settings →
Connectors →
Add custom connectorに移動し、https://api2.transloadit.com/mcp を入力します。Claude は自身を Transloadit API に識別させ、同意ページを開きます。詳しくは
Claude のカスタムコネクターに関するドキュメントを参照してください。
ChatGPT
ChatGPT のプラグインディレクトリにある Transloaditを開き、Install pluginをクリックして同意ページを承認します。ChatGPT はチャットに添付したファイルを Transloadit に渡し、結果を結果ウィジェットに表示します。
URL で接続したい場合は、Settings → Apps & Connectors → Advancedに移動し、Developer modeを有効にして、上記 URL でアプリを作成します。認証方式は OAuth に設定します。
ディレクトリのプラグインは、レビュー済みの新しいバージョンを公開すると新しいツールを取得します。一方、developer mode のアプリは作成時点のツール一覧のスナップショットを保持します。そのため、こちらでツールを追加したあとに反映するには、ChatGPT でアプリの設定を開き、Refresh toolsをクリックしてください。
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"
}
}
}
VS Code / Copilot
たとえば .vscode/mcp.json のように、MCP 設定へサーバーを追加します。
{
"servers": {
"transloadit": {
"type": "http",
"url": "https://api2.transloadit.com/mcp"
}
}
}
ツール一覧
| ツール | アカウント要否 | OAuth scope | 注記 |
|---|---|---|---|
transloadit_lint_assembly_instructions | 不要 | なし | 読み取り専用 |
transloadit_list_robots | 不要 | なし | 読み取り専用 |
transloadit_get_robot_help | 不要 | なし | 読み取り専用 |
transloadit_create_assembly | 必要 | assemblies:write, templates:read | 破壊的操作、結果ウィジェット |
transloadit_get_assembly_status | 必要 | assemblies:read | 読み取り専用 |
transloadit_wait_for_assembly | 必要 | assemblies:read | 読み取り専用、結果ウィジェット |
transloadit_list_templates | 必要 | templates:read | 読み取り専用 |
transloadit_get_profile | 必要 | assemblies:read, templates:read | 読み取り専用 |
ホスト型エンドポイントでは、どのツールも実行前にサインインが必要です。「不要」と表示されたツールは、セルフホストのサーバーであればアカウントなしで使えます。
transloadit_create_assembly は、破壊的操作としてマークされている唯一のツールです。/s3/store のようなエクスポート Robot は、出力先のファイルを上書きできるため、クライアントから確認を求められることがあります。
transloadit_list_templates は include_builtin(all、latest、exclusively-all、exclusively-latest)と、任意の include_content に対応します。transloadit_get_profile は、現在の Credential の背後にある Workspace の ID を返し、Transloadit が判別できる場合はその名前も返します。また、まだ Assembly や Template が存在しない
Workspace については mcp_profile_unavailable を返します。
入力ファイル
transloadit_create_assembly は、次の方法でファイルを受け取れます。
- 公開 URL(
filesとkind: 'url'): サーバーがそれらをインポートまたはダウンロードします。URL と Template の挙動を参照してください。 - 小さなインラインファイル(
filesとkind: 'base64'): 実用的なのは小さいファイルに限られます。制限を参照してください。 - ChatGPT の添付ファイル(
attachments): ChatGPT はチャットに添付したファイルを自動で渡します。各ファイルはattachment_1、attachment_2などの名前の URL 入力になります。 - エージェントのサンドボックス内またはローカルマシン上にしか存在しないファイル:
expected_uploadsで Assembly を作成し、以下の説明どおりにエージェントへアップロードさせます。
ローカルファイルパスは、セルフホストサーバーも含めてツール入力として受け付けません。自分のマシンからアップロードする場合は、npx -y @transloadit/node upload も使えます。
エージェントのサンドボックス内のファイル
Claude.ai など一部のクライアントは、チャット添付を connector ツールへ渡しません。また、ツール引数での base64 はごく小さいファイルでしか実用になりません。その場合、エージェントは自身のサンドボックスからファイルをアップロードします。
-
transloadit_create_assemblyを呼び出し、処理の指示を渡してexpected_uploadsにファイル数を設定します(1 回の呼び出しで最大 100 ファイル)。この呼び出しはwait_for_completion: trueを指定していてもすぐに返ります。Assembly がそのアップロードを待機する状態になるためです。{ "instructions": { "steps": { ":original": { "robot": "/upload/handle" }, "resized": { "robot": "/image/resize", "use": ":original", "width": 200 } } }, "expected_uploads": 1 } -
upload_instructionsの各エントリーには、tus endpoint、tus metadata、そのまま実行できるcurlコマンドが含まれます。エージェントはFILEにファイルパスを設定し、そのコマンドを bash シェルで実行します。ファイルのアップロードが完了すると、201が出力されます。 -
Assembly URL を指定して
transloadit_wait_for_assemblyを呼び出します。
これらのコマンドには Credential は含まれませんが、Assembly URL は秘匿してください。これを知っている相手は、Assembly がアップロード待機中であればファイルを追加できるほか、状態と結果の読み取りやキャンセルもできます。
サンドボックスからは Transloadit への外向き HTTPS アクセスが必要です。Claude.ai では、Settings →
Capabilitiesを開き、コード実行のネットワーク送信を有効にして、追加の許可ドメインに
*.transloadit.com を追加します。結果をサンドボックスへダウンロードさせる場合は、*.transloadit.net も追加してください。
結果ウィジェット
transloadit_create_assembly と transloadit_wait_for_assembly は、MCP Apps リソース
ui://transloadit/assembly-result へリンクします。ChatGPT や Claude のように MCP Apps をサポートするクライアントでは、Assembly がチャット内にカードとして表示されます。その他のクライアントには、通常のツール出力として同じ結果が返ります。

- ステータス: Completed、Processing、Waiting for uploads、Failedのような読みやすいラベルで表示されます。失敗した Assembly では、エラーメッセージとコードも表示されます。Assembly の実行中は、完了すると結果ファイルが表示される旨の注記が出ます。
- Assembly ID: Console 内の Assembly へのリンクです。
- Template ショートカット: Save as Template を押すと、Assembly の instructions を元にした新しい Template が Console で開きます。失敗した Assembly、まだアップロード待機中の Assembly、またはステータスを読み取れなかった Assembly では表示されません。
- 結果: 複数の Step がそれぞれ 1 つまたは 2 つのファイルを生成した場合、すべての結果は 1 つのグリッドにまとめられ、各カードに生成元の Step 名が表示されます。それ以外の場合は、各 Step ごとに Robot とファイル数を含む独自セクションが作られます。カードにはファイル名、寸法とサイズ(または MIME type)、プレビュー、ダウンロードボタンが表示されます。画像と動画のプレビューは読み込み中もサイズを維持し、動画はインライン再生されます。
- 音声: 各音声ファイルは、プレーヤー付きの全幅行として表示されます。
- アップロード: アップロードしたファイルは、下部の Uploaded files 行に折りたたまれます。
- 長い結果: 1 つの Step では最大 8 ファイル、カード全体では最大 12 ファイルまで表示します。残りは Show N more の後ろに折りたたまれます。カードの高さはクライアントが許す高さ、または 720 ピクセルまでに制限され、スクロール可能です。下に何件あるかを示すフェードも表示されます。
- テーマ: カードはクライアントのライトテーマまたはダークテーマに従います。
CI とヘッドレスクライアント
CI job、サーバー、エージェントランタイムのように、ブラウザーでアクセスを承認できる人がいない環境では、Auth Key から Bearer token を発行し、Authorization: Bearer <token> として送信します。
npx -y @transloadit/node auth token --aud mcp
この token は信頼できる環境(バックエンド、CI、またはローカルシェル)で生成し、その後でエージェントランタイムに渡します。発行方法は次のとおりです。
- CLI:
npx -y @transloadit/node auth token --aud mcp - API:
POST /token - Node.js SDK:
authKeyとauthSecretでTransloaditをインスタンス化し、その後client.mintBearerToken({ aud: 'mcp' })を呼び出します
トークンの使用
API リクエストでは、トークンを Authorization: Bearer <access_token> として渡してください。有効な Bearer トークンでリクエストが認証されると、API2 は
Signature Authentication が満たされているとみなし、Signature の検証をスキップします。Signature Authentication が必須となるのは、キー/シークレットを使用するリクエストのみです。スコープのチェックは引き続き適用されます。デフォルトの api2 オーディエンスは通常の API2 エンドポイントで受け入れられ、デフォルトで 21,600 秒間有効です。mcp オーディエンスは MCP サーバーで受け入れられ、MCP サーバーはサービス認証情報を使用してこれを API2 に中継します。通常の API2 エンドポイントに直接提示された場合は拒否され、デフォルトで 604,800 秒間有効です。レスポンスの expires_in の値を正としてください。
bearer token はバージョン管理や共有設定に入れないでください。実際の token をコミットする代わりに、クライアントのシークレットストレージや環境変数サポートを使います。
Bearer token を使う Claude Code
Claude Code のプロジェクト .mcp.json では、この remote-server エントリーを使います。HTTP transport の値は http です。Claude Code を起動する環境で、発行済み API2 token を TRANSLOADIT_API2_BEARER_TOKEN に設定します。以下の設定では、その変数が実行時に展開されます。詳しくは Claude Code MCP のドキュメントを参照してください。
{
"mcpServers": {
"transloadit": {
"type": "http",
"url": "https://api2.transloadit.com/mcp",
"headers": {
"Authorization": "Bearer ${TRANSLOADIT_API2_BEARER_TOKEN}"
}
}
}
}
リモート MCP server 向けにリクエストヘッダーを設定できる他のクライアントでも、同じ
Authorization ヘッダーを使えます。
セルフホスト
エージェントが動作する場所でサーバーを実行し、TRANSLOADIT_KEY と
TRANSLOADIT_SECRET を設定します。これでサーバーが API 呼び出しの認証を自動処理します。
Stdio
TRANSLOADIT_KEY=MY_AUTH_KEY TRANSLOADIT_SECRET=MY_SECRET_KEY npx -y @transloadit/mcp-server stdio
ほとんどのクライアントは、サーバーを自動で起動します。たとえば Claude Code では次のとおりです。
claude mcp add --transport stdio transloadit \
--env TRANSLOADIT_KEY=MY_AUTH_KEY \
--env TRANSLOADIT_SECRET=MY_SECRET_KEY \
-- npx -y @transloadit/mcp-server stdio
Codex では次のとおりです。
codex mcp add transloadit \
--env TRANSLOADIT_KEY=MY_AUTH_KEY \
--env TRANSLOADIT_SECRET=MY_SECRET_KEY \
-- npx -y @transloadit/mcp-server stdio
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 モードの既定パスは /mcp です。
HTTP モードを localhost 以外のホストにバインドする場合は、MCP リクエストに Bearer 認証を必須にするため TRANSLOADIT_MCP_TOKEN を設定してください。
Docker
docker run -i --rm \
-e TRANSLOADIT_KEY=MY_AUTH_KEY \
-e TRANSLOADIT_SECRET=MY_SECRET_KEY \
ghcr.io/transloadit/mcp-server:latest
このイメージは stdio モードで起動します。HTTP モードでは entrypoint を上書きし、ポートを公開します。0.0.0.0 にバインドするには
TRANSLOADIT_MCP_TOKENが必要で、クライアントはそれを
Authorization: Bearer <TRANSLOADIT_MCP_TOKEN> として送信します。
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
Signature アルゴリズム
TRANSLOADIT_SIGNATURE_ALGORITHM には、Auth Key で設定されているアルゴリズムを指定します。キーに対する Console のスニペットにその値が表示されます。Console で
Allow signing Smart CDN URLs を有効にして作成したキー(既定値)では sha256 が使われ、サーバーの既定値は
sha384 です。一致しない場合は mcp_invalid_signature で失敗し、ヒントにはそのキーが必要とするアルゴリズム名が表示されます。
TRANSLOADIT_MCP_TOKEN の説明
TRANSLOADIT_MCP_TOKEN は、セルフホスト MCP の transport token です。保護対象は API2 ではなく、自分の HTTP MCP endpoint(npx -y @transloadit/mcp-server http)です。
- 高エントロピーのシークレットを自分で設定します。
- MCP クライアントから
Authorization: Bearer <TRANSLOADIT_MCP_TOKEN>として送信します。 - これは
/tokenでは発行されません。 https://api2.transloadit.com/mcpに使う API2 Bearer token とは別物です。
1 つ生成してから、HTTP モードを開始します。
export TRANSLOADIT_MCP_TOKEN="$(openssl rand -hex 32)"
npx -y @transloadit/mcp-server http --host 0.0.0.0 --port 5723
結果ウィジェットの設定
結果ウィジェットは、https://*.transloadit.com、https://*.transloadit.net、https://*.r2.dev からプレビューを読み込むことがあります。この一覧は、TRANSLOADIT_MCP_RESULT_DOMAINS(カンマ区切りの origin)で上書きできます。Console へのリンク先は https://transloadit.com で、これは
TRANSLOADIT_MCP_CONSOLE_URL で変更できます。
制限
次の制限は、インライン JSON と base64 ペイロードに適用されます。
- ホスト型リクエストボディ上限: 1 MiB
maxBase64Bytes: ホスト型、セルフホストともに復号後 512,000 バイト- セルフホストの既定リクエストボディ上限: 10 MiB(
maxRequestBodyBytesで設定可能)
サーバーがダウンロードする URL 入力(アップロードを想定する Template 向け)は、1 回の呼び出しあたり合計 1 GiB、各ダウンロード 10 分までに制限されます。より大きいファイルでは、公開 URL を
/http/import Step と組み合わせて使うか、エージェントのサンドボックスからアップロードするか、npx -y @transloadit/node upload で自分のマシンからアップロードしてください。
URL と Template の挙動
URL 入力では、サーバーが対象の instructions または Template に基づいて安全な経路を選択します。
/http/importStep が存在する場合、その Step のurlを設定または上書きします。- Template がアップロードを想定している場合(
:originalまたは/upload/handle)、サーバーはファイルをダウンロードしてから tus でアップロードします。これらのダウンロードには公開 HTTP(S) URL が必要です。プライベートネットワーク上の宛先は、プライベートアドレスへのリダイレクトを含めて拒否されます。 - Template がファイル入力を受け取らない場合、URL 入力は警告付きで無視されます。
- Template が Step の上書きを禁止し、
/http/importのみをサポートする場合、URL 入力は拒否されます。
メトリクスと server card
HTTP デプロイには次のものが含まれます。
GET /metricsの Prometheus メトリクス(既定)TRANSLOADIT_MCP_METRICS_USERとTRANSLOADIT_MCP_METRICS_PASSWORDによる任意のメトリクス認証/.well-known/mcp/server-card.jsonの公開 MCP server card。すべてのツールと、そのアノテーションおよびセキュリティスキームが一覧表示されます
metricsPath のカスタマイズ、メトリクスの無効化(metricsPath: false)、CORS やホスト制限の設定は、HTTP/Express server のオプションで行えます。
/ai/chat で MCP を使う
/ai/chat は、環境から到達できる任意の MCP server を呼び出せます。
Transloadit がホストする MCP server では、次を使えます。
{
"mcp_servers": [
{
"type": "http",
"url": "https://api2.transloadit.com/mcp",
"auth": "transloadit"
}
]
}
auth: "transloadit" を使うと、API2 は対象となる Transloadit ホスト型 MCP URL に対して、scope 付きの短命 Bearer token を自動発行して注入できます。すでに
Authorization を mcp_servers[].headers 内で指定している場合、API2 はそれを変更しません。