AI 클라이언트를 통해 Transloadit Robots를 사용하여 비디오, 오디오, 이미지 및 문서를 처리합니다.
다른 이름 transloadit/node-sdk, mcp-server, @transloadit/mcp-server
- 스타
- 73
- Tools
- 8
- 다운로드, 30일
- —
- 최신 버전
- 0.8.9
- 마지막 커밋
- 2026년 11월 15일
- 라이선스
- MIT
Transloadit Media Processing MCP란?
AI 클라이언트를 통해 Transloadit Robots를 사용하여 비디오, 오디오, 이미지 및 문서를 처리합니다. 8개 도구를 제공합니다. 예: transloadit_lint_assembly_instructions, transloadit_create_assembly, transloadit_get_assembly_status.
프로젝트 README에서 생성된 요약
Transloadit Media Processing MCP server 정보
Transloadit Media Processing은 개발자가 AI 클라이언트를 통해 복잡한 미디어 워크플로우를 관리할 수 있도록 지원합니다. Transloadit Robots를 활용하여 비디오, 오디오, 이미지 및 문서를 처리할 수 있습니다. 사용자는 Claude Desktop, ChatGPT, Cursor, Codex를 포함한 다양한 MCP 클라이언트를 통해 이러한 기능을 사용할 수 있습니다. 이 서버는 특정 URL을 통한 호스팅 버전과 stdio 또는 HTTP 전송 방식을 사용하는 self-hosted 옵션을 모두 지원합니다.
호스팅 서비스에 연결할 때는 OAuth를 사용하여 인증하므로 API 키가 워크스페이스 외부로 유출되지 않습니다. self-hosted 설정의 경우 TRANSLOADIT_KEY와 TRANSLOADIT_SECRET을 제공해야 합니다. 서버는 작업 실행을 위한 transloadit_create_assembly 및 사용 가능한 자동화 항목을 검사하기 위한 transloadit_list_robots와 같은 특정 도구를 제공합니다. 이 서버는 에이전트 워크플로우에 직접 통합되도록 설계되어 AI 모델이 미디어 변환을 트리거하고 assembly 결과를 가져올 수 있습니다.
활용 사례
- 1미디어 변환 자동화AI 에이전트가 새로운 assembly를 생성하여 복잡한 미디어 처리 작업을 트리거할 수 있습니다.
- 2자동화 로직 검증개발자는 서버를 사용하여 robot 지침이 올바르게 형식화되었는지 확인할 수 있습니다.
- 3사용 가능한 자동화 도구 탐색AI 클라이언트에 Transloadit 계정에서 사용 가능한 모든 robot 목록을 요청할 수 있습니다.
- 4headless 미디어 워크플로우 실행브라우저가 없는 환경에서 bearer token을 사용하여 자동화된 에이전트를 인증할 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
Transloadit Media Processing MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 Transloadit Media Processing MCP 설치
$ claude mcp add --env 'TRANSLOADIT_SECRET=<YOUR_TRANSLOADIT_SECRET>' --env 'TRANSLOADIT_KEY=<TRANSLOADIT_KEY>' mcp-server -- npx -y @transloadit/mcp-server stdioCursor에 Transloadit Media Processing MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@transloadit/mcp-server",
"stdio"
],
"env": {
"TRANSLOADIT_SECRET": "<YOUR_TRANSLOADIT_SECRET>",
"TRANSLOADIT_KEY": "<TRANSLOADIT_KEY>"
}
}
}
}VS Code에 Transloadit Media Processing MCP 설치
.vscode/mcp.json
{
"servers": {
"mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@transloadit/mcp-server",
"stdio"
],
"env": {
"TRANSLOADIT_SECRET": "<YOUR_TRANSLOADIT_SECRET>",
"TRANSLOADIT_KEY": "<TRANSLOADIT_KEY>"
}
}
}
}VS Code CLI에 Transloadit Media Processing MCP 설치
$ code --add-mcp '{"name":"mcp-server","type":"stdio","command":"npx","args":["-y","@transloadit/mcp-server","stdio"],"env":{"TRANSLOADIT_SECRET":"<YOUR_TRANSLOADIT_SECRET>","TRANSLOADIT_KEY":"<TRANSLOADIT_KEY>"}}'Claude Desktop에 Transloadit Media Processing MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@transloadit/mcp-server",
"stdio"
],
"env": {
"TRANSLOADIT_SECRET": "<YOUR_TRANSLOADIT_SECRET>",
"TRANSLOADIT_KEY": "<TRANSLOADIT_KEY>"
}
}
}
}Codex에 Transloadit Media Processing MCP 설치
$ codex mcp add mcp-server --env 'TRANSLOADIT_SECRET=<YOUR_TRANSLOADIT_SECRET>' --env 'TRANSLOADIT_KEY=<TRANSLOADIT_KEY>' -- npx -y @transloadit/mcp-server stdioCodex config.toml에 Transloadit Media Processing MCP 설치
~/.codex/config.toml
[mcp_servers.mcp-server] command = "npx" args = ["-y", "@transloadit/mcp-server", "stdio"] [mcp_servers.mcp-server.env] TRANSLOADIT_SECRET = "<YOUR_TRANSLOADIT_SECRET>" TRANSLOADIT_KEY = "<TRANSLOADIT_KEY>"
Gemini CLI에 Transloadit Media Processing MCP 설치
$ gemini mcp add -s user -e 'TRANSLOADIT_SECRET=<YOUR_TRANSLOADIT_SECRET>' -e 'TRANSLOADIT_KEY=<TRANSLOADIT_KEY>' mcp-server npx -- -y @transloadit/mcp-server stdioGemini settings.json에 Transloadit Media Processing MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@transloadit/mcp-server",
"stdio"
],
"env": {
"TRANSLOADIT_SECRET": "<YOUR_TRANSLOADIT_SECRET>",
"TRANSLOADIT_KEY": "<TRANSLOADIT_KEY>"
}
}
}
}HostedMCP가 2026년 11월 16일에 실행 확인
@transloadit/mcp-server 0.8.9을(를) 네트워크와 키가 없는 격리된 컨테이너에서 이 명령으로 실행했습니다. 응답하며 도구 8개를 보여 주었습니다.
Transloadit Media Processing MCP 도구 8
tools/list로 서버에서 직접 읽음transloadit_lint_assembly_instructions읽기 전용Lint complete, merged Assembly Instructions without creating an Assembly. Resolve template_id and merge any Template or replay overrides before calling; this tool does not fetch Templates. Returns structured issues.
transloadit_create_assembly작업Create an Assembly from instructions (Steps or a template_id), or resume one by assembly_url, optionally uploading files and waiting for completion. Files attached in the chat arrive under attachments; public URLs and small base64 payloads go under files. If a file exists only locally or in your sandbox, set expected_uploads and run each returned upload_instructions curl command there (it needs outbound HTTPS to Transloadit). Waiting stops after a server budget (45 seconds by default). Returns the Assembly with its result files; running: true means it is still processing, and next_steps say how to follow it instead of creating it again.
transloadit_get_assembly_status읽기 전용Fetch the current status and result files of an Assembly by assembly_url or assembly_id, without waiting.
transloadit_wait_for_assembly읽기 전용Polls until the Assembly completes, timeout_ms passes or the server budget (45 seconds by default) is spent. A result with running: true is still processing; call this again to keep following it.
transloadit_list_robots읽기 전용List Transloadit Robots, the processing units used in Assembly Steps, with short summaries. Filter by category or search text; page with cursor.
transloadit_get_robot_help읽기 전용Returns the summary, required and optional parameters and examples for one Robot (robot_name) or several (robot_names), for writing Assembly Steps.
transloadit_list_templates읽기 전용List Assembly Templates (owned and/or builtin). Tip: pass include_builtin: "exclusively-latest" to list builtins only.
transloadit_get_profile읽기 전용Returns a stable identifier and name for the Transloadit Workspace behind the current credentials, so hosts can tell connected accounts apart.
| transloadit_lint_assembly_instructions | Lint complete, merged Assembly Instructions without creating an Assembly. Resolve template_id and merge any Template or replay overrides before calling; this tool does not fetch Templates. Returns structured issues. | 읽기 전용 |
| transloadit_create_assembly | Create an Assembly from instructions (Steps or a template_id), or resume one by assembly_url, optionally uploading files and waiting for completion. Files attached in the chat arrive under attachments; public URLs and small base64 payloads go under files. If a file exists only locally or in your sandbox, set expected_uploads and run each returned upload_instructions curl command there (it needs outbound HTTPS to Transloadit). Waiting stops after a server budget (45 seconds by default). Returns the Assembly with its result files; running: true means it is still processing, and next_steps say how to follow it instead of creating it again. | 작업 |
| transloadit_get_assembly_status | Fetch the current status and result files of an Assembly by assembly_url or assembly_id, without waiting. | 읽기 전용 |
| transloadit_wait_for_assembly | Polls until the Assembly completes, timeout_ms passes or the server budget (45 seconds by default) is spent. A result with running: true is still processing; call this again to keep following it. | 읽기 전용 |
| transloadit_list_robots | List Transloadit Robots, the processing units used in Assembly Steps, with short summaries. Filter by category or search text; page with cursor. | 읽기 전용 |
| transloadit_get_robot_help | Returns the summary, required and optional parameters and examples for one Robot (robot_name) or several (robot_names), for writing Assembly Steps. | 읽기 전용 |
| transloadit_list_templates | List Assembly Templates (owned and/or builtin). Tip: pass include_builtin: "exclusively-latest" to list builtins only. | 읽기 전용 |
| transloadit_get_profile | Returns a stable identifier and name for the Transloadit Workspace behind the current credentials, so hosts can tell connected accounts apart. | 읽기 전용 |
구성
TRANSLOADIT_SECRET필수비밀Your Transloadit Auth Secret from https://transloadit.com/c/-/api-credentials
TRANSLOADIT_KEY필수Your Transloadit Auth Key from https://transloadit.com/c/-/api-credentials
TRANSLOADIT_MCP_TOKEN
| 이름 | 설명 | 유형 |
|---|---|---|
| TRANSLOADIT_SECRET | Your Transloadit Auth Secret from https://transloadit.com/c/-/api-credentials | 필수비밀 |
| TRANSLOADIT_KEY | Your Transloadit Auth Key from https://transloadit.com/c/-/api-credentials | 필수 |
| TRANSLOADIT_MCP_TOKEN | — |
자동 검사
2026년 11월 16일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능transloadit/node-sdk is public and reachablegithub.com/transloadit/node-sdk ↗통과
- 패키지가 이 저장소를 소스로 명시@transloadit/mcp-server names transloadit/node-sdk as sourcenpmjs.com/package/@transloadit/mcp-server ↗통과
- 빌드 출처(Sigstore 증명)Sigstore attestation for @transloadit/mcp-servernpmjs.com/package/@transloadit/mcp-server/v/0.8.9#provenance ↗통과
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-11-15github.com/transloadit/node-sdk ↗통과
- OpenSSF ScorecardOpenSSF Scorecard 4.4 / 10; weakest: Code-Review 0, Token-Permissions 0, CII-Best-Practices 0scorecard.dev/viewer/?uri=github.com/transloadit/node-sdk ↗부분 7/15
- 패키지 이름이 인기 패키지와 유사하지 않음No popular package one edit away from @transloadit/mcp-server통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음the package checked; no critical advisoryosv.dev ↗통과
- 모델에 대한 숨겨진 지침 없음8 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨No tool named like delete, drop or exec통과
- 원격 엔드포인트가 MCP 핸드셰이크에 응답HTTPS endpoint answered 401 (sign-in required)통과
README
GitHub에서 보기@transloadit/mcp-server
Transloadit MCP Server (Streamable HTTP + stdio), built on top of @transloadit/node.
Connect by URL (recommended)
The hosted server lives at:
https://api2.transloadit.com/mcp
Add it to your MCP client by URL. The client discovers API2 as the OAuth authorization server, opens a browser consent page in the Transloadit Console, and keeps a short-lived token plus refresh token for you. No API keys leave your Workspace.
The hosted endpoint asks you to sign in before any tool runs, Robot docs and linting included, because MCP clients only start OAuth when the endpoint challenges them. Robot docs and linting ask for no scopes. To use them without an account, run the server yourself (see Self-hosted).
Claude Code
claude mcp add --transport http transloadit https://api2.transloadit.com/mcp
claude mcp login transloadit
For non-interactive runs (for example claude -p), explicitly allow MCP tools:
claude -p "List templates" \
--allowedTools mcp__transloadit__* \
--output-format json
Claude.ai and Claude Desktop
Settings → Connectors → Add custom connector → enter https://api2.transloadit.com/mcp. Claude
registers itself with API2 and opens the consent page.
ChatGPT
Settings → Apps & Connectors → Advanced → Developer mode → Create, then enter the URL above with
authentication set to OAuth. Files you attach in the chat are handed to
transloadit_create_assembly as attachments; results render in the Assembly result widget.
The plugin manifest for the ChatGPT and Codex catalog (plugin.json, mcp.json and the
.codex-plugin/plugin.json fallback) lives in this package directory. It points at the hosted
server and at the Agent Skills catalog at https://transloadit.com/.well-known/skills/index.json
instead of bundling skill files.
Codex
codex mcp add transloadit --url https://api2.transloadit.com/mcp
Codex opens the consent page right away. To sign in again later, run
codex mcp login transloadit.
Or in ~/.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 and headless agents
Where no browser is available, mint a bearer token from an Auth Key and pass it as
Authorization: Bearer <token>:
npx -y @transloadit/node auth token --aud mcp
Generate this token in a trusted environment (backend, CI, or local shell), then hand it to the agent runtime. You can mint it via:
- CLI:
npx -y @transloadit/node auth token --aud mcp - API:
POST https://api2.transloadit.com/token(HTTP Basic Auth with key/secret) - Node SDK: instantiate
TransloaditwithauthKey+authSecret, then callclient.mintBearerToken({ aud: 'mcp' })
Interactive CLI sessions can also run npx -y @transloadit/node auth login (device flow) and reuse
the stored credentials.
Bearer tokens satisfy signature auth on API2 requests; signature checks apply to key/secret requests.
Self-hosted
Run the server where your agent runs, set TRANSLOADIT_KEY and TRANSLOADIT_SECRET, and the server
handles API auth automatically.
Install
npm install @transloadit/mcp-server
Stdio
TRANSLOADIT_KEY=MY_AUTH_KEY TRANSLOADIT_SECRET=MY_SECRET_KEY npx -y @transloadit/mcp-server stdio
Auth Keys sign with one HMAC algorithm. Keys created in the Console with "Allow signing Smart CDN
URLs" (the default) require sha256, so add TRANSLOADIT_SIGNATURE_ALGORITHM=sha256, as the
Console's snippet for the key shows. Other keys use the default sha384. A mismatch fails with
mcp_invalid_signature, and its hint names the algorithm the key requires.
HTTP
TRANSLOADIT_KEY=MY_AUTH_KEY TRANSLOADIT_SECRET=MY_SECRET_KEY \
npx -y @transloadit/mcp-server http --host 127.0.0.1 --port 5723
When binding HTTP mode to non-localhost hosts, TRANSLOADIT_MCP_TOKEN (or the hosted-mode
TRANSLOADIT_MCP_RESOURCE_METADATA_URL) is required.
Docker
docker run -i --rm \
-e TRANSLOADIT_KEY=MY_AUTH_KEY \
-e TRANSLOADIT_SECRET=MY_SECRET_KEY \
ghcr.io/transloadit/mcp-server:latest
For HTTP mode via Docker, override the stdio entrypoint, expose the port, and set a transport
token, which binding to 0.0.0.0 requires:
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 explained
TRANSLOADIT_MCP_TOKEN is a self-hosted MCP transport token. It protects your own HTTP MCP endpoint
(npx -y @transloadit/mcp-server http), not API2.
- Set it yourself to any high-entropy secret.
- Send it from your MCP client as
Authorization: Bearer <TRANSLOADIT_MCP_TOKEN>. - It is not minted via
/token. - It is separate from API2 Bearer tokens used for
https://api2.transloadit.com/mcp.
Generate one, then start HTTP mode:
export TRANSLOADIT_MCP_TOKEN="$(openssl rand -hex 32)"
npx -y @transloadit/mcp-server http --host 0.0.0.0 --port 5723
Self-hosted client setup
Most self-hosted users add the server to their MCP client and let the client start it via 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
Allowlist tools in ~/.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=...
Allowlist tools in ~/.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": "..."
}
}
}
}
Auth model
Hosted (https://api2.transloadit.com/mcp)
- Requests without a bearer token get
401withWWW-Authenticate: Bearer resource_metadata="https://api2.transloadit.com/.well-known/oauth-protected-resource/mcp". MCP clients follow that document to API2's authorization server (authorization code + PKCE, Dynamic Client Registration or Client ID Metadata Documents). - This includes a bare
GET /mcp, because some clients (Codex) discover the authorization server from that probe. Directory health checks therefore see401instead of200; the JSON body still carriesname,statusanddocs. Self-hosted and unauthenticated deployments keep answering the bareGETwith200. - Bearer tokens (OAuth or minted with
--aud mcp) are forwarded to API2, which verifies them on every call. A rejected or expired token yields a tool result withisErrorand_meta["mcp/www_authenticate"], so ChatGPT and Claude prompt you to reconnect. - Each tool declares
securitySchemes(top level and in_meta). Because the hosted endpoint challenges every unauthenticated request, all tools declareoauth2there; the Robot docs and linting tools ask for no scopes. - A rejected or expired key/secret on a self-hosted server is reported as
mcp_credentials_rejectedwithout an OAuth challenge, since only an operator can fix it. - Browser requests must come from ChatGPT, Claude, Transloadit or loopback origins; requests without
an
Originheader (CLIs, servers) are not restricted. SetallowedOriginsto change the list. TRANSLOADIT_MCP_UPSTREAM_SECRETis set by Transloadit's own deployment so API2 can tell that a relayedaud=mcptoken arrives from the hosted service; it is not needed for self-hosting. Hosted mode refuses to start without it, because every authenticated call would fail.
Self-hosted
- Stdio and localhost HTTP need no MCP auth by default.
- Non-localhost HTTP requires
TRANSLOADIT_MCP_TOKEN(a static secret you define). - Live Transloadit API calls use:
- incoming Bearer token from MCP request headers, or
TRANSLOADIT_KEY+TRANSLOADIT_SECRET.
Configuration
Environment variables
TRANSLOADIT_KEYTRANSLOADIT_SECRETTRANSLOADIT_SIGNATURE_ALGORITHM(optional,sha1,sha256orsha384, defaultsha384; must match the Auth Key)TRANSLOADIT_MCP_TOKENTRANSLOADIT_MCP_RESOURCE_METADATA_URL(hosted mode: protected-resource metadata URL to advertise in401challenges)TRANSLOADIT_MCP_UPSTREAM_SECRET(hosted mode only, set by Transloadit's deployment; sent to API2 asTransloadit-Mcp-Upstreamnext to forwarded bearer tokens)TRANSLOADIT_MCP_RESULT_DOMAINS(optional, comma-separated origins the result widget may load previews from and link to, either exact such ashttps://tmp-us-east-1.transloadit.netor with a wildcard host; defaulthttps://*.transloadit.com,https://*.transloadit.net,https://*.r2.dev)TRANSLOADIT_MCP_WIDGET_DOMAIN(optional, defaulthttps://transloadit.com; the origin ChatGPT serves the result widget from, sent as_meta["openai/widgetDomain"])TRANSLOADIT_MCP_CONSOLE_URL(optional, defaulthttps://transloadit.com; Console origin for widget deep links)TRANSLOADIT_ENDPOINT(optional, defaulthttps://api2.transloadit.com)TRANSLOADIT_MCP_METRICS_PATH(optional, default/metrics)TRANSLOADIT_MCP_METRICS_USER(optional)TRANSLOADIT_MCP_METRICS_PASSWORD(optional)
CLI flags
npx -y @transloadit/mcp-server http --host 127.0.0.1 --port 5723npx -y @transloadit/mcp-server http --endpoint https://api2.transloadit.comnpx -y @transloadit/mcp-server http --config path/to/config.json
The JSON config accepts the same keys as createTransloaditMcpHttpHandler(), including
allowedOrigins, resourceMetadataUrl, signatureAlgorithm, resultDomains, widgetDomain and
consoleUrl.
Tool surface
| Tool | Account | OAuth scopes | Notes |
|---|---|---|---|
transloadit_lint_assembly_instructions |
no | none | read-only |
transloadit_list_robots |
no | none | read-only |
transloadit_get_robot_help |
no | none | read-only |
transloadit_create_assembly |
yes | assemblies:write, templates:read |
destructive, open-world (URL imports), widget |
transloadit_get_assembly_status |
yes | assemblies:read |
read-only |
transloadit_wait_for_assembly |
yes | assemblies:read |
read-only, result widget |
transloadit_list_templates |
yes | templates:read |
read-only |
transloadit_get_profile |
yes | assemblies:read, templates:read |
read-only, _meta["openai/profile"] |
Every tool carries title, readOnlyHint, destructiveHint, idempotentHint and
openWorldHint annotations. transloadit_create_assembly is the only destructive one: export
Robots such as /s3/store can overwrite files at their destination, so hosts should confirm it.
transloadit_lint_assembly_instructions validates complete, merged instructions locally. It does
not fetch the Template named by template_id: resolve the Template and merge any Assembly or
replay overrides before linting. For example, an OCR Step that inherits ocr_provider must
include that provider in the instructions passed to this tool.
securitySchemes depend on how the server runs: hosted (TRANSLOADIT_MCP_RESOURCE_METADATA_URL)
declares oauth2 with the scopes above for every tool; a server holding TRANSLOADIT_KEY and
TRANSLOADIT_SECRET declares noauth everywhere; otherwise the account tools declare oauth2 and
the others noauth. TRANSLOADIT_MCP_TOKEN and TRANSLOADIT_MCP_RESOURCE_METADATA_URL cannot be
combined.
Authenticated tools/list is the reference for outcome shortcuts, descriptions and field schemas.
The synced alphalib Builtin manifest supplies
reviewed version pins and temporary field exclusions. The MCP adapter derives tool names and
titles from those IDs and consumes the catalog schema through @transloadit/zod/v4/builtinTemplates.
An alphalib sync carries approved additions, renames, removals and gate changes without another
MCP registry.
Each shortcut’s description starts with the tool-ready summary API2 authors beside the Builtin
definition: the credential’s catalog summary once read, and otherwise the synced
mcpBuiltinTemplateSummaries, which the server card and pre-catalog tools/list use. The long
catalog description is not tool text. Standalone draft-07 fields_schema and content.fields
defaults come from API2’s Template catalog. Defaults merge before validation, preserving JSON types; conservative schema
annotations leave runtime cross-field validation authoritative. A null or absent contract makes
that shortcut unavailable. Generic tools keep their existing behavior.
The manifest’s temporary legacy VP8 webm gate remains until
api2#9960 is deployed and verified.
Social captions are deferred. Transcription language hints do not translate speech.
Catalog reads have a three-second overall deadline without retries. During an authenticated
catalog outage the reviewed names remain discoverable with permissive fields; each call still
fetches and validates the current contract. Malformed or default-sensitive composed schemas also
use permissive discovery, followed by full validation after merging defaults at execution.
Supply fields and the same files/attachments/upload/wait options as transloadit_create_assembly.
For a sandbox file, set expected_uploads, run the returned upload command, then call
transloadit_wait_for_assembly. The SDK already includes the
document extraction registry fix.
transloadit_list_templates supports:
include_builtin:all,latest,exclusively-all,exclusively-latestinclude_content: include parsedstepsin each template item
Builtin items also carry fields_schema unchanged, including conservative-fidelity metadata
and null for older Builtins without a declared schema. Workspace Templates omit that property.
transloadit_get_profile returns { id, name?, nickname? } for the Workspace behind the current
credentials, derived from the Workspace's own Assemblies or Templates.
Result widget
transloadit_create_assembly and transloadit_wait_for_assembly link the MCP Apps resource
ui://transloadit/assembly-result (_meta.ui.resourceUri, also _meta["openai/outputTemplate"]).
Hosts that support MCP Apps render each Step's results with image, video and audio previews,
download links, an "Open in Console" link and a "Save as Template" shortcut. It speaks the MCP Apps
2026-01-26 protocol (ui/initialize with appInfo) and also reads ChatGPT's window.openai.
Its CSP allows https://*.transloadit.com, https://*.transloadit.net and https://*.r2.dev
(result buckets); override the list with TRANSLOADIT_MCP_RESULT_DOMAINS or resultDomains.
ChatGPT asks for the exact hosts a widget uses, so a deployment that knows its result buckets
should list them as origins instead of wildcards. ChatGPT also needs redirect_domains to open
links from the widget: the server sends the result origins plus the Console origin there. ChatGPT
serves the widget from the origin in _meta["openai/widgetDomain"]
(TRANSLOADIT_MCP_WIDGET_DOMAIN). ui.domain stays unset, because Claude derives that value from
the server URL and rejects any other.
Input files
export type InputFile =
| {
kind: 'base64'
field: string
base64: string
filename: string
contentType?: string
}
| {
kind: 'url'
field: string
url: string
filename?: string
contentType?: string
}
Hosts that attach chat files (ChatGPT) pass them under attachments instead, as declared by
_meta["openai/fileParams"]:
type Attachment = {
download_url: string
file_id: string
mime_type?: string
file_name?: string
}
Each attachment becomes a URL input (attachment_1, attachment_2, …) and follows the URL rules
below.
Files that exist only locally or in your sandbox
If the file exists only locally or in your sandbox, call transloadit_create_assembly with
expected_uploads and run the returned upload_instructions; this needs outbound HTTPS from the
sandbox to Transloadit (Claude.ai: Settings → code execution network access must allow it). Hosts
such as Claude.ai do not hand chat attachments to connector tools, and base64 in tool arguments is
impractical for anything but tiny files, so the agent uploads the file itself:
- Call
transloadit_create_assemblywith your instructions andexpected_uploads: 1(one per file, at most 100 per call). The call returns right away, even withwait_for_completion: true, because the Assembly now waits for those uploads. - Each
upload_instructionsentry has the tus endpoint, the tus metadata (assembly_url,fieldname) and a ready-to-runcurlcommand. SetFILEto the file's path and run it in a bash shell; it prints201once the file is uploaded (tus creation-with-upload, one request). - Call
transloadit_wait_for_assemblywith the Assembly URL.
Calling transloadit_create_assembly with assembly_url and expected_uploads (all uploads the
Assembly expects, as at creation) hands out upload_instructions for the uploads an existing
Assembly still waits for.
The commands contain no credentials: the Assembly URL is the only capability, and it lets the holder add files to that one Assembly while it waits for uploads.
Limits
These limits apply to inline JSON/base64 payloads. For larger files, use a public URL or upload from
your own machine with npx -y @transloadit/node upload.
- Hosted default request body limit: 1 MiB
- Hosted
maxBase64Bytes: 512,000 decoded bytes - Self-hosted default request body limit: 10 MiB
Set maxRequestBodyBytes (handler option or JSON config key) to change the body limit; larger
requests get HTTP 413 and are not buffered. Express apps that install their own body parser set
its limit there.
URL inputs that the server downloads (for templates that expect uploads) are capped at 1 GiB in
total per call and 10 minutes per download, redirects included; set maxUrlDownloadBytes and
urlDownloadTimeoutMs to change that. On the hosted
endpoint the caller's token is checked with API2 before anything is downloaded. Downloads count
toward the wait budget below: when they do not finish in time, no Assembly is created and the call
returns mcp_preparation_timeout, so a retry is safe. The download is stopped about a second
later and its file removed.
Waiting for Assemblies
MCP hosts abandon tool calls that run too long (ChatGPT after about a minute) and may retry them,
which would create a second Assembly. transloadit_create_assembly, the Builtin shortcuts and
transloadit_wait_for_assembly therefore wait at most 45 seconds, even with a larger
wait_timeout_ms/timeout_ms. When that budget is spent, the call returns the Assembly with its
current status (a last status read or a slow creation request may take up to 5 seconds more, so
keep the budget that far below the host's limit), running: true and an mcp_assembly_still_running notice; uploads and processing
continue, and transloadit_wait_for_assembly or transloadit_get_assembly_status follow it. Set
maxWaitMs (option or JSON config key) or TRANSLOADIT_MCP_MAX_WAIT_MS to change the budget.
URL inputs and template behavior
For URL inputs, behavior depends on the template/instructions:
- If an
/http/importStep exists, MCP sets/overrides that Step'surl. - If the template expects uploads (
:originalor/upload/handle), MCP downloads then uploads via tus. These downloads require public HTTP(S) URLs; private-network targets are rejected, including redirects to private addresses. - If the template does not take input files, URL inputs are ignored and a warning is returned.
- If
allow_steps_override=falseand only/http/importwould work, URL inputs are rejected.
The Builtin shortcuts for caption-video, convert-to-pdf, encode-video, extract-text,
prepare-image, remove-background, transcribe and video-covers send URLs to API2 as
input_url next to template_id when every file
and attachment of the call is a URL (up to 10, one for caption-video). Transloadit then fetches
the files itself, so the Assembly exists at once and nothing is downloaded by the MCP server or held
up by a large file. API2 names the files after their URLs (or redirects and Content-Disposition),
so inputs given a file name, such as host attachments, keep the download path above, as do calls
that mix URLs with base64 files or sandbox uploads, calls with upload_behavior: 'none', and URLs
that API2 would refuse (whitespace, |, ${…}, over 4096 characters). If API2 refuses
input_url for the request, its error is returned like any other. The eligible Builtins are listed
in the alphalib Builtin manifest.
Local vs hosted file access
- MCP accepts base64 and URL inputs in both self-hosted and hosted deployments. Local filesystem paths are not supported as tool inputs.
- Migration: clients that previously sent
kind: 'path'must switch to base64, a public URL, or a local CLI upload. This also applies to stdio and self-hosted servers. - Use public
urlinputs, smallbase64payloads, or upload locally withnpx -y @transloadit/node upload. - Use
expected_uploadsto keep an Assembly open for out-of-band tus uploads.
Transloadit Media Processing MCP 질문
Transloadit Media Processing MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add --env 'TRANSLOADIT_SECRET=<YOUR_TRANSLOADIT_SECRET>' --env 'TRANSLOADIT_KEY=<TRANSLOADIT_KEY>' mcp-server -- npx -y @transloadit/mcp-server stdio를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
Transloadit Media Processing MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
Transloadit Media Processing MCP는 어떤 도구를 제공하나요?
8개 도구를 제공합니다. 예: transloadit_lint_assembly_instructions, transloadit_create_assembly, transloadit_get_assembly_status, transloadit_wait_for_assembly, transloadit_list_robots.
CI 또는 headless 에이전트의 인증 방식은 어떻게 되나요?
브라우저가 없는 환경에서는 Auth Key로부터 bearer token을 생성하여 Authorization 헤더를 통해 전달할 수 있습니다.