AI Agents
AI coding agents such as Claude Code, OpenAI Codex, and Cursor can connect to Transloadit and use 96 current Robots to upload, encode, and transform files. Agents can combine the MCP server for runtime tool access, reusable Agent Skills for human-directed workflows, and llms.txt for documentation context. The CLI provides a separate automation path for humans and CI.
Start from your project
Paste this prompt into your coding agent from the project root. It makes the agent inspect your stack before choosing an SDK, MCP, or skills, and keeps the first change reviewable:
Set up the smallest safe Transloadit integration for this repository.
1. Inspect the project’s language, runtime, package manager, existing upload/media code, tests, and agent configuration before changing files.
2. Choose the narrowest integration that fits: an official SDK for application code, MCP for agent-executed runtime tools, the CLI (npx -y @transloadit/node) for scripts and CI jobs, and Agent Skills for repeatable workflow guidance. Reuse an existing integration when present.
3. Before editing, summarize what you found, which path you chose, and the files and commands you expect to change. Use the project’s existing package manager.
4. For interactive hosted MCP, add the hosted URL https://api2.transloadit.com/mcp to the client configuration without any token or key, and have the user approve browser OAuth. For CI or headless hosted MCP, mint an mcp-audience Bearer token at run time in a trusted environment, mint a new one when it expires, and supply it through secret storage or an environment variable.
5. Use TRANSLOADIT_KEY and TRANSLOADIT_SECRET only in a trusted server, CLI, CI, or self-hosted MCP process. When signing with an Auth Key, match its signature algorithm: for the Node CLI or self-hosted MCP, set TRANSLOADIT_SIGNATURE_ALGORITHM; in Node SDK code, pass the signatureAlgorithm option. Console keys with Smart CDN signing on (the default) use sha256; the Console’s snippet for the key shows the value.
6. Never expose TRANSLOADIT_SECRET to browser, mobile, or other client code. Give client code a public Auth Key and a Template ID; for production, generate the params and signature on a trusted backend with Signature Authentication. Use unsigned client params only with test credentials.
7. Never hardcode, print, commit, or overwrite credentials, including minted Bearer tokens. Keep secrets out of committed MCP configuration. If required credentials are unavailable, scaffold placeholders and stop before account operations.
8. Create one minimal, typed workflow and validate its Assembly Instructions. Prefer an existing small media fixture. Without an account, validate inline instructions locally with npx -y @transloadit/node assemblies lint --steps <file>. Linting against a Template ID needs credentials. Do not create an account, change a plan, or modify production Templates.
9. Run the repository’s checks. If authenticated Transloadit access (an approved hosted MCP connection or credentials in a trusted process) and a suitable fixture are available and the user has authorized a live test, run one Assembly, wait for completion, and report its Assembly ID, status, and result URL. Otherwise, report the exact command or MCP tool call the maintainer can run. Credentials or an approved connection alone do not authorize a live run.
10. Summarize every changed file, verification result, and any remaining manual step.
The expected outcome is a small repository change, not merely a generated code sample. Review the agent’s proposed credential boundary before allowing a live Assembly.
What the agent should select
| Project signal | Starting point |
|---|---|
| Node.js, Python, Ruby, PHP, Go, Java, Android, or iOS application | The matching official SDK |
| Agent needs to lint instructions, inspect docs, or execute Assemblies | MCP server |
| Build scripts, CI jobs, shell pipelines, or account-free linting | CLI |
| Team wants a reusable, version-controlled workflow | Agent Skills |
| No runtime integration is needed yet | llms.txt and Markdown documentation pages |
MCP server
The Model Context Protocol (MCP) gives agents direct runtime access to Transloadit tools.

There are three ways to connect. Pick the first one that fits your client:
| Client | Connect with | Credentials |
|---|---|---|
| Interactive agent client, such as Claude, ChatGPT, Codex, or Cursor | Hosted URL | Approve OAuth in your browser |
| CI job or headless agent runtime | Hosted URL with a Bearer token | Token minted from an Auth Key |
| Agent that should run the server itself | Self-hosted stdio | None for docs and linting; Auth Key for Assemblies |
Connect by URL
Add the hosted MCP URL to your MCP client:
https://api2.transloadit.com/mcp
Approve OAuth access in your browser and choose the Workspace the client may use. There is no local server to install and no Auth Key or Secret to copy. Approving creates a dedicated Auth Key for the app, limited to the permissions shown; revoke access under Connected apps.
The hosted server asks you to sign in before any tool runs, including Robot documentation and linting. To use those without an account, run the server self-hosted.
CI and headless clients
Where nobody can approve access in a browser, send a token with the mcp audience to the hosted
endpoint as Authorization: Bearer <token>. Mint it in a trusted environment that holds an Auth Key
and Secret (TRANSLOADIT_KEY and TRANSLOADIT_SECRET for the CLI):
npx -y @transloadit/node auth token --aud mcp
The command prints JSON. Capture only its access_token value and pass it to the agent runtime
through secret storage or an environment variable; do not echo the response to logs or the agent
transcript.
- Expiry: tokens expire after the returned
expires_ininterval (one week by default for MCP). Mint one per job or session, and mint a new one if the work outlasts that interval. - Scope: use
--scopeto narrow access; otherwise the token inherits the Auth Key’s scopes. - Revocation: delete the Auth Key a token was minted from to cut off access before it expires. Use a dedicated Auth Key for CI.
See CI and headless clients for client configuration examples.
Self-hosted stdio
Configure the server as a stdio command in your MCP client; most clients launch it for you. Robot documentation and linting work without an account:
npx -y @transloadit/mcp-server stdio
For account operations such as creating Assemblies, supply TRANSLOADIT_KEY and
TRANSLOADIT_SECRET through the server process’s environment, and set
TRANSLOADIT_SIGNATURE_ALGORITHM to match the Auth Key. Keys created in the Console with Smart CDN
signing on (the default) use sha256, while the server defaults to sha384; the Console’s snippet
for the key shows which value to set. See
signature algorithm configuration.
The stdio process holds these credentials on the agent’s machine, so use a dedicated Auth Key with only the scopes it needs, and keep credentials out of committed MCP configuration files.
For client config examples (Claude, Cursor, VS Code/Copilot), auth details, tool docs, limits, and hosted vs self-hosted behavior, see the MCP Server documentation.
Automation paths
Transloadit agent tooling combines execution tools with workflow guidance and documentation context. The CLI and MCP execute workflows; Agent Skills and llms.txt help agents use those tools:
- CLI: use
@transloadit/nodewhen a human or CI job needs a repeatable command to create an Assembly, wait for completion, and collect results. - MCP: expose Transloadit tools to embedded or hosted agents. The agent can inspect Robot docs,
lint Assembly Instructions, create Assemblies, and follow status updates. For files passed directly
to
transloadit_create_assembly, use public URLs, small inline files, or attachments the client passes through. Uploading local or sandbox files through the returned upload command requires a shell; see supported inputs. - Agent Skills: keep team-specific media workflow playbooks in version control for agents that already have useful tools, such as terminal access, MCP, the CLI, or SDKs. Skills tell the agent which Templates, verification steps, and fallbacks to use, but do not grant new capabilities by themselves.
- llms.txt: give any LLM a current map of Transloadit products, solutions, integrations, developer resources, and learning content before it proposes an Assembly.
Use hosted MCP with browser OAuth when a person connects an interactive agent client. For unattended
automation, keep credentials in a trusted environment: send an mcp-audience Bearer token to hosted
MCP, or supply an Auth Key and Secret to self-hosted stdio, the CLI, or your own backend.
Agent Skills
Agent Skills are markdown files (SKILL.md) that teach agents how to
accomplish tasks step by step.

In practical terms, an MCP server is an API surface an agent can call at runtime (via a local or hosted MCP process), while skills are version-controlled playbooks that tell an agent what to do, in what order, and how to verify it. Skills do not add new tool access by themselves. They codify how you want the agent to use the tools available in your environment (MCP, CLI, SDKs) in a consistent way.
- Use MCP for embedded, repeatable execution (Assembly creation, polling, results).
- Use skills as reusable, human-directed playbooks for tasks such as setup, scaffolding, templates, and migrations.
They also complement each other. A skill can standardize a workflow and then instruct the agent to use MCP (or a local CLI fallback) for the actual execution.
Install with the Skills CLI
npx skills add transloadit/skills
This installs all 19 Transloadit skills into your project:
- docs-transloadit-robots
Offline lookup for Transloadit Robots and their parameter docs/examples via the
transloaditCLI. Use to draft or validatestepsJSON without guessing robot names/params. - integrate-asset-delivery-with-transloadit-smartcdn-in-nextjs
Add server-side Transloadit Smart CDN URL signing for an explicitly configured asset to a Next.js App Router project.
- integrate-uppy-transloadit-s3-uploading-to-nextjs
Add Uppy Dashboard + Transloadit uploads to a Next.js (App Router) app, with server-side signature generation and optional /s3/store export.
- transform-build-mosaic-collage-with-transloadit
One-off justified mosaic photo collage (N local images -> single image) using the official
@transloadit/nodeCLI. Uses the/image/mergeRobot'smosaiceffect to build a justified tiled layout with center-cropped photos, and downloads the result to an explicit output path via--output. - transform-build-polaroid-collage-with-transloadit
One-off polaroid-stack photo collage (N local images -> single image) using the official
@transloadit/nodeCLI. Uses the/image/mergeRobot'spolaroid-stackeffect and downloads the result to an explicit output path via--output. - transform-caption-video-with-transloadit
Add plain burned captions to a local video and download the captioned video plus SRT cues using the caption-video Builtin and the official Transloadit CLI.
- transform-capture-webpage-with-transloadit
Capture a public webpage or local HTML as an image or PDF using the capture-webpage Builtin and the official Transloadit CLI.
- transform-convert-markdown-to-pdf-with-transloadit
Convert a local Office document, HTML, Markdown or text file to PDF using the convert-to-pdf Builtin and the official Transloadit CLI. Includes the existing Markdown-to-PDF workflow.
- transform-describe-image-with-transloadit
One-off image description using the official
@transloadit/nodeCLI. Useimage describe --fields labelsfor object-style labels, orimage describe --for wordpressfor structured alt text, title, caption, and description JSON. - transform-encode-hls-video-with-transloadit
One-off HLS encoding (local video -> HLS renditions + playlist) using Transloadit via the
transloaditCLI. Prefer builtin templates (builtin/encode-hls-video@latest) and download outputs locally via-o. - transform-encode-video-with-transloadit
Encode a local video for web playback as MP4 or WebM using the encode-video Builtin and the official Transloadit CLI.
- transform-extract-text-with-transloadit
Extract readable text or JSON from local PDFs, scans, photos and Office documents using the extract-text Builtin and the official Transloadit CLI.
- transform-generate-image-with-transloadit
One-off image generation (prompt -> image file) using Transloadit via the
transloaditCLI. Preferimage generatefor text-only and input-guided generation, and use--outputwhen you need a deterministic path. - transform-make-video-covers-with-transloadit
Make cover images from a local video, using regular frames, exact offsets or smart selection through the video-covers Builtin and the official Transloadit CLI.
- transform-prepare-image-with-transloadit
Prepare local images for a website with orientation correction, resizing, compression and format conversion using the prepare-image Builtin and the official Transloadit CLI.
- transform-remove-background-with-transloadit
Remove a local photo's background and download a transparent PNG using the remove-background Builtin and the official Transloadit CLI.
- transform-transcribe-audio-with-transloadit
Transcribe local audio or video to text, timestamped JSON, SRT or WebVTT using the transcribe Builtin and the official Transloadit CLI.
- transform-upscale-image-with-transloadit
One-off AI image upscaling (local image -> upscaled image) using Transloadit via the
transloaditCLI. Prefer theimage upscaleintent and use--outputfor a deterministic path. - transloadit
Main entry-point skill for Transloadit. Route to the right
integrate-*,transform-*, ordocs-*skill, and prefer executing vianpx -y @transloadit/node ...(CLI) for deterministic behavior.
Auto-discovery
The skills catalog is also discoverable at transloadit.com/.well-known/skills/index.json, following the Agent Skills Discovery RFC. This means you can also install with:
npx skills add https://transloadit.com
Manual installation
Clone or symlink the transloadit/skills repo into your agent's skills directory:
| Agent | Path |
|---|---|
| Claude Code | .claude/skills/ |
| OpenAI Codex | .codex/skills/ |
| Gemini CLI | .gemini/skills/ |
| Cursor | .cursor/skills/ |
| Windsurf | .codeium/windsurf/skills/ |
llms.txt
Transloadit publishes an llms.txt file, a compact, site-wide routing index following the llms.txt standard. It covers products and services, solutions, integrations, media and task indexes, developer and learning resources, and support.
For Robot-specific discovery, use /docs/robots/llms.txt. The legacy
llms-full.txt compatibility file includes complete Robot parameter schemas inline,
but it is large. Prefer llms.txt for discovery and fetch only the linked Markdown pages relevant to
the task.
Which approach should I use?
| Approach | Best for | Setup |
|---|---|---|
| Hosted MCP with OAuth | Interactive agent clients | Add the URL and approve access in your browser |
| Hosted MCP with a Bearer token | CI and headless agent clients | Mint a token in a trusted environment |
| Self-hosted MCP (stdio) | Running the server locally, account-free docs and linting | Configure stdio in your MCP client; provide keys for account operations |
| Official SDK | Application code | Install the matching SDK; keep the Auth Secret on the server |
| CLI | Scripts, CI jobs, and account-free linting | Run npx -y @transloadit/node; provide credentials for account operations |
| Agent Skills | Reusable, human-directed Transloadit workflows | Install with one command |
| llms.txt | Giving any LLM broad Transloadit documentation context | Fetch the URL |
These approaches complement each other. Start with hosted MCP and browser OAuth for interactive tool access. For unattended agent tools, send a Bearer token to hosted MCP or give an Auth Key and Secret to self-hosted stdio. Use an official SDK for application code or the CLI for scripts and CI jobs. Install skills for workflow guidance, and point your LLM at llms.txt for documentation context.