Media uploads from anywhere

The original create_file MCP tool worked by having the agent include the file as base64 in the request body. That works for small text files. For a 2 MB image it means roughly a million tokens per upload — completely impractical.

forge-media v1.2.0 fixes this with a two-step flow: generate a short-lived upload token, then upload the file directly via HTTP multipart. The admin token never leaves the MCP layer.

The upload token flow

Step 1 — Agent generates a token:

create_upload_token

Returns a signed token valid for 15 minutes. Role required: Author or above.

Step 2 — Client uploads directly:

POST /media
Authorization: UploadToken <token>
Content-Type: multipart/form-data

file=<bytes>
description=<alt text>

The description field is required. There is no path through the upload boundary that produces an unlabelled file.

Step 3 — Agent sets the media URL on content:

The upload response includes the file URL. The agent passes it to update_post, update_story, or whichever content type it is working with.

This flow works from any HTTP client: Claude.ai on mobile, a browser form, curl, or a CI pipeline. The upload token is minimal privilege — POST /media only, scoped to a 15-minute window. It cannot read, list, or delete files.

What gets accepted

MIME whitelist: image/jpeg, image/png, image/webp, image/gif, image/avif. Anything else is rejected at the upload boundary.

Filenames get a hex prefix generated at upload time, which prevents overwrites of existing files.

Maximum upload size is 5 MB by default, configurable via media_max_size in forge.config.

AVIF support

AVIF is now accepted alongside JPEG, PNG, WebP, and GIF. Modern browsers support AVIF natively. If you are generating AVIF derivatives from your image pipeline, you can now serve them directly through forge-media.

CLI media commands

forge-cli v0.6.0 adds direct media operations from the terminal. The CLI uploads using your Bearer token directly — no upload token needed.

forge-cli media upload photo.jpg --description "Conference keynote stage"
forge-cli media list
forge-cli media list --type image
forge-cli media delete <id>

--description is required on upload. The CLI enforces the same alt text requirement as the MCP tool and the HTTP endpoint.

forge-cli media list accepts an optional --type filter (image, video, etc.) to narrow results. Without a filter it returns all files the current token has access to read.

Configuring TTL

The default upload token TTL is 15 minutes. Change it in code:

forge.New(db, forge.Config{
    MediaUploadTokenExpiry: 30 * time.Minute,
})

The window is short by design. An upload token is for one upload operation, not for ongoing access.

forge v1.19.0, forge-media v1.2.0, forge-mcp v1.9.0, forge-cli v0.6.0.

*See forge-media for full installation and wiring reference.* *See forge-cli for CLI configuration and authentication.*