Skip to main content
Glama

Get a Hosted App file upload URL

request_app_upload_url

The PUT must be sent from the caller's own environment, over outbound HTTPS to this server's host. That works from Claude Code or a terminal. Hosted code sandboxes, such as ChatGPT's, have no outbound network, so a URL minted there cannot be used. Such a caller hands the file over with import_app_file when its client can attach or reference the file, and otherwise sends it with stage_app_file in base64 parts. Request a single-use URL for uploading a local binary asset directly with curl -X PUT --data-binary, without emitting its bytes as tool arguments. Returns an absolute url, expires_at and curl example in structuredContent. Treat the URL as a secret. The upload returns accumulated size_bytes and sha256 for verification before publishing. A lost URL response uploads nothing by itself: if no PUT was dispatched, request a fresh URL and let the unused one expire. After an uncertain PUT, call list_staged_app_files with the same slug and publisher and compare path, content_type, accumulated size_bytes and sha256 against the intended prefix. Never replay a consumed URL or blindly repeat an append with a fresh URL. Absence can mean expiry, consumption by publication, or an in-flight PUT; it is not permission to retry. The PUT's own response is the only settlement evidence for that attempt, and a listing never says which PUT wrote the bytes it shows. When that response is lost, do not append another part: replace the complete file — a fresh URL with append: false for its first part and fresh URLs appending the rest — then verify the staged sha256 before publishing and the published file's sha256 after publishing. A published digest that differs from the intended file is an unresolved duplicate or lost write: stop and hand it to a person with the digests you read. After publishing, call list_staged_app_files for the slug: a publish consumes the whole area, so any file still staged is an earlier attempt that landed after the publish; discard it with discard_staged_app_files and report it to a person before any later publish. For binary assets on disk, call request_app_upload_url and run its curl command so bytes do not pass through the model. Each URL is single-use, expires after 15 minutes, and binds the project, publisher, slug, path, content type and append flag. Upload parts of at most 1 MiB using a fresh URL for each part, with append: true after the first. An accepted attempt consumes its URL even if reading or staging fails; inspect staged sizes and sha256 before retrying. Each MCP call is limited to 1048576 bytes for the entire request body, including the JSON envelope and encoded files. Base64 leaves less than 768 KiB of decoded content after overhead. Use stage_app_file to send a file larger than one call in ordered parts with append: true after its first part; encode each base64 part independently. Each staged file expires 6 hours after its last write; expired files are hidden from listings, deleted on area mutations, and swept hourly in bounded batches across all areas. The area belongs to this project, publisher and slug. A taken slug you cannot manage is refused with slug_unavailable by staging, listing, discarding, publication and signed-upload redemption; this reveals only that the slug is taken, and nothing is staged or created.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "slug": "<slug>",
      "path": "<path>"
    },
    "name": "request_app_upload_url"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathYesRelative file path
slugYes1–64 lowercase letters, digits and internal hyphens; an app need not exist yet
appendNoDefault false replaces the path; true appends an ordered part with the same content type
content_typeNoType inferred from extension when omitted. For a recognized extension, explicit content_type must match; otherwise an explicit allowed content_type is required. Allowed types (extension: content_type): .cjs: text/javascript; .css: text/css; .csv: text/csv; .gif: image/gif; .htm: text/html; .html: text/html; .ico: image/x-icon; .jpeg: image/jpeg; .jpg: image/jpeg; .js: text/javascript; .json: application/json; .md: text/markdown; .mjs: text/javascript; .otf: font/otf; .pdf: application/pdf; .png: image/png; .svg: image/svg+xml; .ttf: font/ttf; .txt: text/plain; .wasm: application/wasm; .webp: image/webp; .woff: font/woff; .woff2: font/woff2. PDFs are served as downloads: an app fetches their bytes to process them, and they cannot be shown inline.

Output Schema

NameRequiredDescriptionDefault
urlYes
curlYes
expires_atYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.3/5.0
Behavior5/5

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

Annotations only declare readOnly=false, destructive=false, idempotent=false and openWorld=false; the description adds the operational profile the agent actually needs: single-use URLs, 15-minute expiry, binding to project/publisher/slug/path/content type/append flag, 1 MiB part sizing, the 1048576-byte request-body ceiling with base64 overhead, and 6-hour staged-file expiry with hourly sweeps. It also discloses the slug_unavailable refusal and that a taken slug reveals nothing and stages nothing, which is far beyond the annotation set.

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

Conciseness2/5

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

Roughly 480 words for a four-parameter tool, with the purpose buried after a network-constraint preamble and substantial repetition — 'append: true after the first' appears three times, and staged-file expiry, sha256 verification, and the list_staged_app_files recovery loop are each restated. The content is valuable but not front-loaded and not deduplicated, forcing the agent to parse the recovery protocol repeatedly.

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

Completeness5/5

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

For a non-idempotent, stateful upload-URL minting tool with an output schema, it covers everything an agent needs: where the PUT must originate, expiry and single-use semantics, sizing limits, verification steps, and explicit recovery behavior after a lost or uncertain PUT including when to stop and escalate to a person.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning the schema does not: each URL binds the append flag, so a replacement needs a fresh URL with append:false for the first part and fresh appending URLs for the rest, and parts are capped at 1 MiB each. It adds little for slug and path beyond the schema, which keeps it from a 5.

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 core purpose is stated precisely: 'Request a single-use URL for uploading a local binary asset directly with curl -X PUT --data-binary, without emitting its bytes as tool arguments,' and it explicitly distinguishes itself from import_app_file and stage_app_file. The only flaw is placement — the definition opens with a paragraph about outbound-network constraints instead of the verb+resource, so the agent must read several sentences to learn what the tool is.

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

Usage Guidelines5/5

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

It names the alternatives and the exact conditions that select them: use import_app_file when the client can attach the file and the sandbox has no outbound network, stage_app_file for base64 parts, and this tool for binary assets on disk. It also states when not to use it (hosted sandboxes such as ChatGPT's with no outbound HTTPS) and forbids specific wrong behaviors such as replaying a consumed URL or blindly repeating an append.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources