Skip to main content
Glama
thenavidm

Shotstack MCP Server

by thenavidm
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Direct Upload

create_upload_url_file
Destructive

Request a signed URL for securely uploading a binary file via PUT; the URL is saved to a private JSON file instead of being exposed in model output.

Instructions

Request a signed URL to upload a file to. The response returns a signed URL that you use to upload the file to. The signed URL looks similar to:

[temporary signed credential URL omitted]

In a separate API call, use this signed URL to send a PUT request with the binary file. Using cURL you can use a command like:

curl -X PUT -T video.mp4 {data.attributes.url}

Where video.mp4 is the file you want to upload and {data.attributes.url} is the signed URL returned in the response. The request must be a PUT type.

The SDK does not currently support the PUT request. You can use the SDK to make the request for the signed URL and then use cURL to make the PUT request.

Base URL: https://api.shotstack.io/ingest/{version} Explicit confirmation is required for this exact action; provider charges, hosting, sharing or deletion may apply. Never automatically resubmit unknown outcomes.

Input Schema

NameRequiredDescriptionDefault
accountNoNamed private Shotstack account; selects private credentials and stage/v1 environment.
confirmNoSet true only when the user asked for exactly this action.
secret_result_fileYesNew absolute JSON file in a private owner-only directory. Signed upload URL stays out of model output; no overwrite.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv3.0.0
    • changedInput schema / properties / confirm / description
      Previous value: -"Must be true for this exact requested render, generation, mutation, upload URL or deletion."New value: +"Set true only when the user asked for exactly this action."
  2. First observedv2.0.0

TDQS

A3.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructive/not-idempotent/open-world, and the description adds real context beyond them: explicit confirmation is required, charges/hosting/sharing/deletion may apply, and unknown outcomes must not be automatically resubmitted. It does not, however, explain what makes a URL request 'destructive' (e.g. credential scope or expiry).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded, but the body is padded with a raw curl example, a truncated credential URL, an HTML-anchored base URL, and a trailing confirmation/charges paragraph that reads like boilerplate. Several sentences could be trimmed without losing meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully explains that the response contains a signed URL and how it is consumed (PUT with the binary file), covering the end-to-end flow. It stops short of documenting URL expiry or the secret_result_file persistence contract beyond what the schema states.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so account, confirm, and secret_result_file are already documented in the schema. The description mentions the signed URL and the PUT target but adds no syntax or constraints beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource: request a signed URL to upload a file to, and explains the follow-up PUT step. It clearly distinguishes this setup call from the actual binary upload, though it never names a sibling tool (e.g. ingest_source) that might be an alternative for getting files into Shotstack.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It implies usage by describing the two-step workflow (get signed URL here, then PUT elsewhere) and notes the SDK cannot do the PUT, which is actionable. However, there is no explicit statement of when to choose this over sibling ingestion tools, and no exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools