Transloadit MCP Server

@transloadit/mcp-server

Transloadit MCP 服务（Streamable HTTP + stdio），基于 @transloadit/node 构建。

通过 URL 连接（推荐）

托管服务位于：

https://api2.transloadit.com/mcp

通过 URL 将其添加到 MCP 客户端。客户端会发现 API2 是 OAuth 授权服务器，在 Transloadit Console 中打开浏览器授权页面，并为你保留一个短期令牌和刷新令牌。API 密钥不会离开你的 Workspace。

托管端点会要求你先登录，之后才会运行任何工具，包括 Robot 文档和 lint 检查，因为 MCP 客户端只有在端点发起质询时才会启动 OAuth。Robot 文档和 lint 检查不需要任何权限范围。若要在没有账户的情况下使用这些功能，请自行运行服务（参见“可自托管”）。

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

设置 → 连接器 → 添加自定义连接器 → 输入 https://api2.transloadit.com/mcp。Claude 会向 API2 注册自身并打开授权页面。

ChatGPT

设置 → 应用和连接器 → 高级 → 开发者模式 → 创建，然后输入上方的 URL，并将身份验证设为 OAuth。在聊天中附加的文件会作为 attachments 交给 transloadit_create_assembly；结果会显示在 Assembly 结果小组件中。

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 和无头 Agent

如果无法使用浏览器，请从 Auth Key 生成一个 bearer token，并将其作为 Authorization: Bearer <token> 传递：

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

请在可信环境（后端、CI 或本地 shell）中生成此令牌，然后交给 Agent 运行时。可通过以下方式生成：

• CLI：npx -y @transloadit/node auth token --aud mcp
• API：POST https://api2.transloadit.com/token（使用 key/secret 进行 HTTP Basic Auth）
• Node SDK：使用 authKey + authSecret 实例化 Transloadit，然后调用 client.mintBearerToken({ aud: 'mcp' })

交互式 CLI 会话也可以运行 npx -y @transloadit/node auth login（设备流程），并重复使用已存储的凭据。

Bearer token 可满足 API2 请求的签名验证；签名检查适用于 key/secret 请求。

可自托管

在 Agent 运行的环境中运行服务，设置 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 Key 使用一种 HMAC 算法进行签名。在 Console 中创建且启用了“Allow signing Smart CDN URLs”（默认设置）的密钥需要使用 sha256，因此请添加 TRANSLOADIT_SIGNATURE_ALGORITHM=sha256，与 Console 为该密钥显示的代码片段一致。其他密钥使用默认值 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 传输令牌。它用于保护你自己的 HTTP MCP 端点 （npx -y @transloadit/mcp-server http），而非 API2。

• 自行设置为任意高熵密钥。
• 从 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、 动态客户端注册或客户端 ID 元数据文档）。
• 这也包括直接发送的 GET /mcp，因为某些客户端（Codex）会通过此请求探测授权服务器。 因此，目录健康检查会收到 401 而不是 200；JSON 响应正文仍包含 name、status 和 docs。 自托管和无需身份验证的部署中，直接发送的 GET 仍会返回 200。
• Bearer 令牌（OAuth 令牌或通过 --aud mcp 签发的令牌）会转发给 API2，由 API2 在每次调用时验证。 被拒绝或过期的令牌会返回带有 isError 和 _meta["mcp/www_authenticate"] 的工具结果， 从而提示 ChatGPT 和 Claude 重新连接。
• 每个工具都会声明 securitySchemes（顶层和 _meta 中）。由于托管端点会质询每个未经身份验证的请求， 因此所有工具都会在此处声明 oauth2；Robot 文档和 lint 工具不需要任何作用域。
• 在自托管服务上，被拒绝或过期的密钥/密文会报告为 mcp_credentials_rejected，而不会触发 OAuth 质询， 因为只有运营者才能解决此问题。
• 浏览器请求必须来自 ChatGPT、Claude、Transloadit 或环回源；不带 Origin 标头的请求（CLI、服务端） 不受限制。设置 allowedOrigins 可更改此列表。
• TRANSLOADIT_MCP_UPSTREAM_SECRET 由 Transloadit 自己的部署设置，以便 API2 判断经过转发的 aud=mcp 令牌是否来自托管服务；自托管时无需此项。托管模式若未设置此项则拒绝启动，因为每次经过身份验证的调用都会失败。

自托管

• 默认情况下，stdio 和本地主机 HTTP 无需 MCP 身份验证。
• 非本地主机 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 的部署设置；与转发的 bearer token 一起作为 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 配置接受与 createTransloaditMcpHttpHandler() 相同的键，包括 allowedOrigins、resourceMetadataUrl、signatureAlgorithm、resultDomains、widgetDomain 和 consoleUrl。

工具概览

工具	账户	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 等导出 Robot 可能会覆盖目标位置的文件，因此宿主应在执行前确认。

transloadit_lint_assembly_instructions 会在本地验证完整且已合并的指令。它不会获取 template_id 指定的 Template：请先解析 Template，并合并任何 Assembly 或重放覆盖项，再进行检查。例如，继承 ocr_provider 的 OCR Step 必须在传给此工具的指令中包含该 provider。 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 注册表。

每个快捷方式的描述都以工具可直接使用的 summary 开头，这是 API2 作者在 Builtin 定义旁提供的内容：读取凭据的目录摘要；否则则使用同步的 mcpBuiltinTemplateSummaries，服务器卡片和目录读取前的 tools/list 会使用该内容。目录中较长的 description 不会作为工具文本。独立的 draft-07 fields_schema 和 content.fields 默认值来自 API2 的 Template 目录。默认值会在验证前合并，并保留 JSON 类型；保守的架构注解不会取代运行时的跨字段验证。如果契约为 null 或缺失，该快捷方式将不可用。通用工具保持现有行为。

清单中的临时旧版 VP8 webm 门控会保留，直到部署并验证 api2#9960。 社交媒体说明文字暂不支持。转录语言提示不会翻译语音。

目录读取的整体时限为三秒，不会重试。经过身份验证的目录不可用时，仍会以宽松字段公开经审核的名称；每次调用仍会获取并验证当前契约。格式错误或对默认值敏感的组合架构也会采用宽松发现方式，随后在执行时合并默认值并进行完整验证。 提供 fields，并使用与 transloadit_create_assembly 相同的文件／附件／上传／等待选项。对于沙盒文件，请设置 expected_uploads，运行返回的上传命令，然后调用 transloadit_wait_for_assembly。SDK 已包含 文档提取注册表修复。

transloadit_list_templates 支持：

• include_builtin：all、latest、exclusively-all、exclusively-latest
• include_content：在每个模板项中包含解析后的 steps

Builtin 项还会原样携带 fields_schema，包括保守保真度元数据；对于未声明架构的旧版 Builtin，该值为 null。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）。ui.domain 保持未设置，因为 Claude 会根据服务 URL 推导该值，并拒绝任何其他值。

输入文件

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；这需要沙盒能够通过 HTTPS 向 Transloadit 发出出站请求（Claude.ai：Settings → code execution network access 必须允许此操作）。Claude.ai 等宿主不会将聊天附件交给连接器工具，而在工具参数中使用 base64 对除极小文件之外的任何文件都不切实际，因此由 Agent 自行上传文件：

1. 使用你的指令和 expected_uploads: 1 调用 transloadit_create_assembly（每个文件一次，每次调用最多 100 个）。即使设置了 wait_for_completion: true，调用也会立即返回，因为此时 Assembly 正在等待这些上传。
2. 每个 upload_instructions 条目都包含 tus 端点、tus 元数据（assembly_url、fieldname）以及可直接运行的 curl 命令。将 FILE 设为文件路径，并在 bash shell 中运行该命令；文件上传完成后会输出 201（tus 创建并上传，只需一个请求）。
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，因此可以安全重试。下载会在大约一秒后停止，并删除相应文件。

等待 Assembly

MCP 主机可能会放弃运行时间过长的工具调用（ChatGPT 大约在一分钟后），并可能重试，从而创建第二个 Assembly。因此，即使 wait_timeout_ms/timeout_ms 设置得更大，transloadit_create_assembly、内置快捷方式和 transloadit_wait_for_assembly 的等待时间也最多为 45 秒。等待时限用完时，调用会返回当前状态的 Assembly（最后一次状态读取或较慢的创建请求可能还需最多 5 秒，因此请确保等待时限比主机限制至少短这么多），并带有 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 步骤，MCP 会设置/覆盖该步骤的 url。
• 如果模板需要上传文件（:original 或 /upload/handle），MCP 会先下载文件，再通过 tus 上传。这些下载要求 URL 使用公共 HTTP(S) 地址；私有网络目标会被拒绝，包括重定向到私有地址的情况。
• 如果模板不接收输入文件，则会忽略 URL 输入并返回警告。
• 如果 allow_steps_override=false 且只有 /http/import 才能处理，则会拒绝 URL 输入。

对于 caption-video、convert-to-pdf、encode-video、extract-text、 prepare-image、remove-background、transcribe 和 video-covers 这些内置快捷方式，当调用中的每个文件和附件都是 URL 时（最多 10 个；caption-video 为 1 个），会将 URL 作为 input_url 与 template_id 一并发送给 API2。随后由 Transloadit 自行获取文件，因此 Assembly 会立即创建，MCP 服务无需下载文件，也不会因大文件而延迟。API2 会根据 URL（或重定向及 Content-Disposition）为文件命名，因此，具有文件名的输入（例如主机附件）仍会使用上述下载流程；混合使用 URL 与 base64 文件或沙盒上传的调用、使用 upload_behavior: 'none' 的调用，以及 API2 会拒绝的 URL（包含空白字符、|、${…} 或超过 4096 个字符）也会使用上述流程。如果 API2 拒绝该请求中的 input_url，则会像其他错误一样返回其错误。符合条件的内置工具列于 alphalib 内置清单。

本地与托管文件访问

• 在可自托管和托管部署中，MCP 都接受 base64 和 URL 输入。不支持将本地文件系统路径用作工具输入。
• 迁移： 之前发送 kind: 'path' 的客户端必须改用 base64、公共 URL 或本地 CLI 上传。stdio 和可自托管服务也适用此规则。
• 使用公共 url 输入、小型 base64 负载，或通过 npx -y @transloadit/node upload 在本地上传。
• 使用 expected_uploads，以便 Assembly 保持打开状态，等待带外 tus 上传。

恢复行为

如果提供了 assembly_url，MCP 会根据 Assembly 状态（tus_uploads + uploads）恢复上传。这要求字段名称和文件元数据（filename + size）保持稳定。重新提交相同的 base64 或公共 URL 输入即可恢复上传。即使省略了原始指令，URL 输入也会被下载并上传；恢复操作不会修改现有 Assembly 的 Steps。文件内容、字段名称和文件名必须保持不变。 此操作会恢复 tus 上传；通过 /http/import 执行的 URL 导入无需重新提交。

Assembly ID 必须包含 32 个十六进制字符。Assembly URL 必须指向 Transloadit 主机或明确配置的 API 源站，且不得包含凭据、查询参数或片段。MCP 会提取 ID，并通过已配置的 API 端点解析 Assembly；绝不会直接获取调用方提供的 Assembly URL。MCP 不会跟随 API 响应重定向，包括 Assembly 的 redirect_url。自定义端点可在开发时使用本地源站，但这不会启用对私有网络 URL 的文件下载。

指标和服务卡片

• 默认通过 GET /metrics 提供 Prometheus 指标。
• 通过 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 与 skills/CLI

• 将 MCP 用于嵌入式运行时执行（上传、Assemblies、轮询、结果）。
• 将 skills/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

运行端到端测试

test:e2e 需要环境中配置有效的 Transloadit 凭据。

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

提交更改

• 如果行为发生变化，请添加或更新测试。
• 确保 README 与网站文档中的面向用户行为保持一致。
• 在 transloadit/node-sdk 中创建 PR。