Skip to content

Assets and uploads

Implemented

List saved media and prepare an owner upload.

Open as Markdown

Assets are saved media metadata. list_assets does not verify bytes or return a preview. start_media_upload creates an upload for one MP4 video, or one JPEG or PNG image. Without Publish the owner sends an MP4 at /media/upload. With Publish, directUpload supplies a signed HTTP PUT URL valid for 15 minutes; send bytes with Content-Type: video/mp4, image/jpeg or image/png, and Content-Length. The Content-Type decides the kind. Replay the same request ID and label for a fresh URL. Read get_media_upload or list_media_uploads to resume. An unknown transfer needs explicit recovery, not a replacement upload.

Quoted text is the tool description your client receives from tools/list.

Tools on this page#


list_assets#

Title
List Media Assets as sent in tools/list
Transport
Streamable HTTP at /mcp
Annotations
readOnlyHint true destructiveHint false idempotentHint true openWorldHint false as sent in tools/list
Owner handoff
No
Idempotency key
None
Revision guard
None

List saved media metadata in the selected workspace. This does not verify bytes, fetch media, or provide a preview.

Input#

Table: Field, Type, Required, Constraints
FieldTypeRequiredConstraints
workspaceIdstring (UUID)yes
cursorstringnomin length 1; max length 1024
limitintegernomin 1; max 100; default 25

Unknown fields are rejected.

Result#

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
assetsarray of objectyes
nextCursorstring or nullyes
previewobjectyes

The result carries no other fields.

assets[]

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstringyes

Other fields may be present. Do not assume they are absent.

preview.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
availablealways falseyes

The result carries no other fields.

Every successful result is also returned as structuredContent.


start_media_upload#

Title
Start a Media Upload as sent in tools/list
Transport
Streamable HTTP at /mcp
Annotations
readOnlyHint false destructiveHint false idempotentHint true openWorldHint false as sent in tools/list
Owner handoff
When directUpload is null; with Publish the agent can send bytes to directUpload.url. /media/upload from uploadUrl
Idempotency key
requestId
Revision guard
None

Create an upload for one file, subject to the workspace media budget: an MP4 video up to 50 MiB, or a JPEG or PNG image up to 30 MiB and 40,000,000 pixels. uploadUrl is the owner handoff for a video: the owner chooses an MP4 in a signed-in browser. That page takes no image. With Publish (list_workspaces access.canPublish), directUpload is also returned: send the file bytes with one HTTP PUT to directUpload.url before expiresAt, with Content-Length and one Content-Type: video/mp4, image/jpeg or image/png. The Content-Type decides the kind, so this call has no field for it. The server reads the real type, width and height from the bytes and refuses a file that is not the type you declared, an animated image, or a file over the limit. Never put file bytes, paths or storage URLs in MCP arguments. A failed transfer can be sent again to the same URL until it expires. Reuse requestId and label after an uncertain response. Use get_media_upload to read the result.

When to call it

Call this when you need a file that ShipContent does not already hold: an MP4 video, or a JPEG or PNG image. Read media.quota.availableBytes from get_onboarding_status first. This call checks no budget: the workspace budget is checked when file bytes are sent by the owner or an agent with Publish. Five unfinished uploads in the workspace return UPLOAD_LIMIT_REACHED; finish or cancel one, then call again. The upload stays open for 24 hours.

With Publish, directUpload is a signed HTTP PUT URL with a 15-minute expiresAt. It is null without Publish, or when upload.canUpload is false. Send one file with one PUT. Always send Content-Length. The Content-Type of the PUT decides the kind of the upload. This call has no field for the kind.

Table: File, Content-Type, Limit
FileContent-TypeLimit
Videovideo/mp450 MiB
Imageimage/jpeg or image/png30 MiB (31,457,280 bytes) and 40,000,000 pixels

The server does not trust the declared type. It reads the real type, width and height from the bytes. It refuses a file that is not the declared type, an animated file, a file over 30 MiB and an image over 40,000,000 pixels. A refused image saves no asset and holds no budget. The upload stays pending and takes the right file at the same URL. See Upload an existing image for each refusal and its code.

Replay the same requestId and label for a fresh direct URL after expiry. Read saved state before a retry. Updated 2026-10-17: an unresolved storage write or rollback sets canUpload to false and produces no fresh direct URL. URL or receiver expiry does not clear that unresolved result. Keep the same request ID.

Updated 2026-11-19: an agent with Publish can upload a JPEG or a PNG. Before this, only an MP4 was accepted. A request that sends only video/mp4 works as before.

Input#

Table: Field, Type, Required, Constraints
FieldTypeRequiredConstraints
requestIdstring (UUID)yes
labelstringyesmin length 1; max length 200
workspaceIdstring (UUID)yes

Unknown fields are rejected.

Result#

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
uploadobjectyes
uploadUrlstring (URL)yes
directUploadobject or nullyes

The result carries no other fields.

upload.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
assetIdstring (UUID)yes
requestIdstring (UUID)yes
labelstringyesmin length 1; max length 200
status"pending" | "receiving" | "storing" | "complete" | "cancelled" | "expired"yes
manifestobject (2 shapes) or nullyes
metadataobject (2 shapes) or nullyes
createdAtstring (date-time)yes
expiresAtstring (date-time)yes
activeUntilstring (date-time) or nullyes
canUploadbooleanyes
assetobject or nullyes

The result carries no other fields.

upload.asset.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
namestringyesmin length 1; max length 200
kind"video" | "image"yes
contentType"video/mp4" | "image/jpeg" | "image/png"yes
sizeintegeryesmin 1; max 52428800
widthintegeryesmax 9007199254740991
heightintegeryesmax 9007199254740991
durationnumberno
sourcealways "upload"yes
createdAtstring (date-time)yes

The result carries no other fields.

directUpload.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
urlstring (URL)yes
methodalways "PUT"yes
expiresAtstring (date-time)yes

The result carries no other fields.

Every successful result is also returned as structuredContent.

Example call#

json
{
  "name": "start_media_upload",
  "arguments": {
    "workspaceId": "00000000-0000-4000-8000-000000000001",
    "requestId": "00000000-0000-4000-8000-000000000014",
    "label": "Product demo, 12 seconds"
  }
}

Example result#

json
{
  "upload": {
    "id": "00000000-0000-4000-8000-000000000015",
    "assetId": "00000000-0000-4000-8000-000000000012",
    "requestId": "00000000-0000-4000-8000-000000000014",
    "label": "Product demo, 12 seconds",
    "status": "pending",
    "manifest": null,
    "metadata": null,
    "createdAt": "2026-10-05T09:10:00Z",
    "expiresAt": "2026-10-06T09:10:00Z",
    "activeUntil": null,
    "canUpload": true,
    "asset": null
  },
  "uploadUrl": "https://shipcontent.example.com/media/upload?workspaceId=00000000-0000-4000-8000-000000000001&uploadId=00000000-0000-4000-8000-000000000015",
  "directUpload": {
    "url": "https://shipcontent.example.com/mcp/uploads/example-only",
    "method": "PUT",
    "expiresAt": "2026-10-05T09:25:00.000Z"
  }
}

Errors#

  • AUTH_REQUIRED
  • AUTH_NOT_CONFIGURED
  • FORBIDDEN
  • INVALID_INPUT
  • IDEMPOTENCY_CONFLICT
  • UPLOAD_LIMIT_REACHED
  • DATABASE_UNAVAILABLE

Errors return isError: true and { code, error } in structuredContent. See Error codes.

Replay and conflicts#

Reuse the same requestId with identical input to recover a lost response; the original result is returned. Changed input with the same ID is rejected. A new ID creates a new operation. See Request IDs, replay and recovery.

Owner handoff#

When directUpload is null; with Publish the agent can send bytes to directUpload.url, use the owner handoff if returned. The owner URL is uploadUrl for /media/upload. Give that URL to the owner and stop. The URL grants no access by itself.

  • What the owner does: Choose an MP4 and send the bytes. The page takes video only.
  • What the agent reads: get_media_upload, field upload.status.

The example direct URL is a nonfunctional placeholder, not a bearer token. Do not put file bytes, paths, credentials or signed URLs in MCP arguments. If directUpload is null and upload.canUpload is true, give uploadUrl to the owner. With Publish, send bytes to directUpload.url over HTTP instead. Read get_media_upload for upload.status.

Updated 2026-11-19: the owner page at uploadUrl takes an MP4 only. It does not take images. An agent without Publish cannot upload an image. The owner adds an image in Library with Upload assets, or gives Publish to the agent.

upload.assetId is reserved when the handoff is created. It is not an asset, and it is not attachable. Wait for upload.status to be complete and a non-null upload.asset, then use upload.asset.id. Updated 2026-10-17: retention can make an old completed upload return asset: null. Its canUpload stays false. Replaying its request ID cannot restore the removed bytes.

Updated 2026-10-17: releasing storage quota after confirmed retention does not reopen an unfinished receiver. A retired current destination keeps canUpload: false, including after account access is restored; it cannot supply a fresh direct URL.

Updated 2026-10-24: a prepared upload cannot accept fresh bytes or start a new storage write after the selected plan expires. Restore plan access before retrying. A storage write that was already dispatched can still record its result and finish the saved upload; the current grant and workspace authority still apply.


get_media_upload#

Title
Get Media Upload as sent in tools/list
Transport
Streamable HTTP at /mcp
Annotations
readOnlyHint true destructiveHint false idempotentHint true openWorldHint false as sent in tools/list
Owner handoff
Yes. /media/upload from uploadUrl
Idempotency key
None
Revision guard
None

Read the saved upload request, owner handoff, and finalized asset if complete. A complete upload returns upload.asset: a video has kind video and a duration; an image has kind image, contentType image/jpeg or image/png, width and height, and no duration. Use upload.asset.id in a post; read get_post_catalogue for the image formats. Upload success proves inspected bytes, not Instagram readiness. A failed transfer returns to pending so the same file can be sent again; never start a replacement upload to hide an uncertain result.

When to call it

Call this after start_media_upload, or after a PUT with no reply, until upload.status is complete. A complete upload returns upload.asset. Use upload.asset.id in a post.

upload.asset.kind says what was saved. For a video, contentType is video/mp4 and duration is in seconds. For an image, contentType is image/jpeg or image/png, width and height are the true size in pixels, and there is no duration. upload.manifest.contentType is present for an image only. upload.metadata holds the measured values: contentType, width and height for an image.

An image asset can attach to the image and carousel formats, and to an Instagram story. See Upload an existing image for the formats that publish today. A complete upload proves inspected bytes. It does not prove that a channel accepts the file.

Input#

Table: Field, Type, Required, Constraints
FieldTypeRequiredConstraints
workspaceIdstring (UUID)yes
uploadIdstring (UUID)yes

Unknown fields are rejected.

Result#

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
uploadobjectyes
uploadUrlstring (URL)yes

The result carries no other fields.

upload.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
assetIdstring (UUID)yes
requestIdstring (UUID)yes
labelstringyesmin length 1; max length 200
status"pending" | "receiving" | "storing" | "complete" | "cancelled" | "expired"yes
manifestobject (2 shapes) or nullyes
metadataobject (2 shapes) or nullyes
createdAtstring (date-time)yes
expiresAtstring (date-time)yes
activeUntilstring (date-time) or nullyes
canUploadbooleanyes
assetobject or nullyes

The result carries no other fields.

upload.asset.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
namestringyesmin length 1; max length 200
kind"video" | "image"yes
contentType"video/mp4" | "image/jpeg" | "image/png"yes
sizeintegeryesmin 1; max 52428800
widthintegeryesmax 9007199254740991
heightintegeryesmax 9007199254740991
durationnumberno
sourcealways "upload"yes
createdAtstring (date-time)yes

The result carries no other fields.

Every successful result is also returned as structuredContent.

Example call#

json
{
  "name": "get_media_upload",
  "arguments": {
    "workspaceId": "00000000-0000-4000-8000-000000000001",
    "uploadId": "00000000-0000-4000-8000-000000000015"
  }
}

Example result#

json
{
  "upload": {
    "id": "00000000-0000-4000-8000-000000000015",
    "assetId": "00000000-0000-4000-8000-000000000012",
    "requestId": "00000000-0000-4000-8000-000000000014",
    "label": "Store front photo",
    "status": "complete",
    "manifest": {
      "name": "upload.jpg",
      "size": 482113,
      "contentType": "image/jpeg"
    },
    "metadata": {
      "contentType": "image/jpeg",
      "width": 1600,
      "height": 1200
    },
    "createdAt": "2026-11-19T09:10:00.000Z",
    "expiresAt": "2026-11-20T09:10:00.000Z",
    "activeUntil": null,
    "canUpload": false,
    "asset": {
      "id": "00000000-0000-4000-8000-000000000012",
      "name": "upload.jpg",
      "kind": "image",
      "contentType": "image/jpeg",
      "size": 482113,
      "width": 1600,
      "height": 1200,
      "source": "upload",
      "createdAt": "2026-11-19T09:10:07.000Z"
    }
  },
  "uploadUrl": "https://shipcontent.example.com/media/upload?workspaceId=00000000-0000-4000-8000-000000000001&uploadId=00000000-0000-4000-8000-000000000015"
}

Errors#

  • AUTH_REQUIRED
  • AUTH_NOT_CONFIGURED
  • FORBIDDEN
  • INVALID_INPUT
  • NOT_FOUND
  • DATABASE_UNAVAILABLE

Errors return isError: true and { code, error } in structuredContent. See Error codes.

Owner handoff#

The owner URL is uploadUrl for /media/upload. Give that URL to the owner and stop. The URL grants no access by itself.

  • What the owner does: Finish an upload that is still open.
  • What the agent reads: get_media_upload, field upload.status.

list_media_uploads#

Title
List Media Uploads as sent in tools/list
Transport
Streamable HTTP at /mcp
Annotations
readOnlyHint true destructiveHint false idempotentHint true openWorldHint false as sent in tools/list
Owner handoff
No
Idempotency key
None
Revision guard
None

Discover unfinished upload requests first, then recent history, up to 25 records in this workspace. Use this after reconnecting or losing chat history. Continue an existing owner handoff; completed uploads include the stable asset ID for draft attachment, for a video or an image (upload.asset.kind).

When to call it

Call this after you reconnect or lose chat history. It returns up to 25 upload requests of the workspace: unfinished requests first, then recent history. Each item has the same upload as get_media_upload.

An upload is a video or an image. Read upload.asset.kind of a complete upload. An image upload has upload.manifest.contentType of image/jpeg or image/png, and upload.asset has no duration. An upload that never received a file has manifest: null, so its kind is not set yet. The first PUT sets it. A refused image upload returns to that state.

Continue an unfinished upload with the same requestId and label in start_media_upload. Do not start a replacement upload to bypass an uncertain result.

Input#

Table: Field, Type, Required, Constraints
FieldTypeRequiredConstraints
workspaceIdstring (UUID)yes

Unknown fields are rejected.

Result#

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
uploadsarray of objectyes

The result carries no other fields.

uploads[]

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
uploadobjectyes
uploadUrlstring (URL)yes

The result carries no other fields.

uploads[].upload.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
assetIdstring (UUID)yes
requestIdstring (UUID)yes
labelstringyesmin length 1; max length 200
status"pending" | "receiving" | "storing" | "complete" | "cancelled" | "expired"yes
manifestobject (2 shapes) or nullyes
metadataobject (2 shapes) or nullyes
createdAtstring (date-time)yes
expiresAtstring (date-time)yes
activeUntilstring (date-time) or nullyes
canUploadbooleanyes
assetobject or nullyes

The result carries no other fields.

Every successful result is also returned as structuredContent.

Errors#

  • AUTH_REQUIRED
  • AUTH_NOT_CONFIGURED
  • FORBIDDEN
  • DATABASE_UNAVAILABLE

Errors return isError: true and { code, error } in structuredContent. See Error codes.


The schemas on this page are generated from the repository at build time. The guidance was last reviewed on 2026-11-19.

Status: Implemented · Generated from src/lib/mcp/agent-tools.ts, src/lib/server/mcp/AgentMcp.ts, src/lib/docs/handoffs.ts, src/lib/docs/channels.ts

Open as Markdown