Skip to main content
Use a managed connection. Tool arguments carry metadata. The client transfers binary data with HTTP and must be able to read the source file. Resolve the relative upload, part and download paths against the trusted Studio origin. Attach the MCP bearer credential only to that origin. S3 signed URLs are sent to the configured S3 origin using their returned headers.

Identify the effective limits

Call studio_get_upload_policy with workspace. It returns accept (allowed file extensions), ordinaryMaxBytes, whether resumable uploads are enabled, and the chunkBytes, maxBytes, maxParts, maxConcurrent and multipartThresholdBytes values. Workspace and server restrictions can change. Treat the returned limits as specific to that workspace.

Upload a single file

Call studio_prepare_file_upload with workspace, then POST multipart form data to its uploadPath. Send the file in file and optionally send the destination folder ULID in parent. Omit parent for the root.
The key uses 16–128 letters, digits, underscores or hyphens on this HTTP route. Keep the same key and identical input for a retry. A successful upload returns HTTP 201 and an entry with id, versionId and revision.

Import an image with supplied renditions

Call studio_prepare_image_import with workspace. Use its separate uploadPath with the original in file and 1–12 named images under variants. An optional roles map assigns the thumbnail or preview to a variant from this request.
Input names match [a-z][a-z0-9_-]{0,22}. The saved presets acquire the import- prefix. Each image must meet workspace file policy and the 40-million-pixel validation limit. The complete bundle must fit the ordinary upload byte limit. The source and supplied conversions belong to one version.

Resumable uploads

  1. Call studio_begin_upload with workspace, the filename in name, declared byte size, and retry key. Optionally provide parent and direct: true to prefer S3 Multipart.
  2. Record the returned session id, transport, chunkBytes, size and acceptedParts. The card also returns the state and either the published entry or entry: null. It adds partPathPrefix for local transport.
  3. Split the original into chunkBytes chunks starting at index 0. The last part contains the remainder. Hash the exact bytes of each part with SHA-256. Respect maxConcurrent. If the connection drops, query studio_get_upload with the same credential and resume the missing indices.
  4. Call studio_complete_upload with workspace and session after all parts are accepted. A successful completion returns the published entry. Use studio_cancel_upload for an unfinished session that should be discarded.

Local chunks

Send a binary PUT to partPathPrefix plus the zero-based part index. Include X-Part-SHA256 as 64 lowercase hex characters. The HTTP result is {"accepted":true}. An accepted index can be retried with the same bytes.

S3 Multipart

Use the transport returned by studio_begin_upload. direct: true is a preference, and Studio may return local transport. For Multipart, call studio_sign_upload_part with workspace, session, part and sha256. PUT the exact bytes to its signed URL using the returned headers. Keep the S3 ETag, including its quotes, and call studio_record_upload_part with workspace, session, part and etag. A signed part only appears in acceptedParts after recording. If a URL expires, ask for a new signature for the same index and checksum. Never forward the Studio bearer token to S3.

Download an authorized version

Call studio_prepare_file_download with workspace, entry and optionally version. If you omit the version, Studio resolves the current version when preparing the link. GET the returned downloadPath on the Studio origin with the bearer token. The binary route checks workspace, permission and version again. Set the output to a local path you control.
See upload and storage settings for limits, S3 setup and retention.