Postly MCP

Upload Media

postly_upload_media

Imports media into Postly storage independently of a post mutation. Accepts a client-provided file reference, URL, data URL, or base64 payload. Returns a durable Postly media object only when complete; a 202 processing result requires a later list_media check with its idempotency_key before creating or scheduling a post.

Input Schema

Name	Required	Description
`url`	No	Public or temporary URL to import into Postly storage when no file reference is available.
`data`	No	Base64 content or a data URL for agents that can provide bytes instead of a URL.
`file`	No	Client-provided file reference for an attached, selected, or generated file.
`type`	No	Optional MIME type such as image/png, video/mp4, or application/pdf.
`alt_text`	No	Optional alt text to carry forward into the returned Postly media object.
`file_name`	No	Optional file name. Required when using data/base64 without a file reference.
`workspace_id`	No	Destination Media Library workspace ID. Omit to use the oldest available writable workspace within this connection. Check media_library in the result for its workspace_id and registration status.
`idempotency_key`	No	Optional stable key for safely retrying the same upload. Postly derives one automatically for file references and URLs.

Output Schema

Name	Required	Description	Default
`code`	No
`media`	No
`usage`	No
`status`	No
`message`	No
`next_step`	No
`raw_upload`	No
`media_library`	No
`idempotency_key`	No
`retry_after_seconds`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 10, 2026

addedInput schema / properties / workspace_id

Added value: +{
+  "description": "Destination Media Library workspace ID. Omit to use the oldest available writable workspace within this connection. Check media_library in the result for its workspace_id and registration status.",
+  "type": "string"
+}

addedOutput schema / properties / media_library
```
Added value: +{
+  "type": "object"
+}
```

Changed4 schema fields changedSep 29, 2026
- addedOutput schema / properties / idempotency_key
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / next_step
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / retry_after_seconds
```
Added value: +{
+  "type": "integer"
+}
```
- addedOutput schema / properties / status
```
Added value: +{
+  "type": "string"
+}
```

Changed1 schema field changedSep 16, 2026

addedInput schema / properties / idempotency_key

Added value: +{
+  "description": "Optional stable key for safely retrying the same upload. Postly derives one automatically for file references and URLs.",
+  "type": "string"
+}

Changed1 schema field changedAug 1, 2026

changedInput schema / properties / file / description

Previous value: -"ChatGPT/OpenAI file reference for an attached, selected, or generated file. ChatGPT supplies this when the tool metadata marks file as an openai/fileParams field."New value: +"Client-provided file reference for an attached, selected, or generated file."

Changed1 schema field changedJul 8, 2026
- removedInput schema / properties / file / properties / download_url / format
```
Removed value: -"uri"
```
Changed1 schema field changedJun 4, 2026
- addedInput schema / properties / file / properties / download_url / format
```
Added value: +"uri"
```
First observedMay 19, 2026

TDQS

A3.9/5.0

Behavior4/5

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

With annotations only declaring write/idempotency/open-world hints, the description adds substantive behavior: the call returns a durable media object only on completion, and a 202 means deferred processing that must be polled via list_media. The idempotency_key note coexists with idempotentHint=false because the schema explains Postly derives a key automatically for file references and URLs, so this is additive rather than contradictory.

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

Conciseness4/5

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

Three sentences, front-loaded with purpose then input modes then the async caveat; nothing is filler. The final sentence is long and packs two ideas (polling requirement and the gating of post creation), which slightly reduces scanability.

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?

An output schema exists so return values need not be explained, and the description covers the non-obvious async case and scoping. Missing details an agent might want are practical limits (file size/type constraints) and how this differs from the batch sibling, but the core call path is complete.

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 the schema already documents all eight parameters and the baseline is 3. The description restates the accepted input modes (file reference, URL, data URL, base64) but adds no format, precedence, or size guidance beyond the schema.

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?

Specific verb+resource ('Imports media into Postly storage') with the key scope qualifier 'independently of a post mutation', which routes the agent away from postly_create_post. It does not, however, distinguish itself from the close sibling postly_upload_media_batch, so it stops short of full sibling differentiation.

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

Usage Guidelines4/5

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

Gives a clear condition for the async path: a 202 result requires a later list_media check with the idempotency_key before creating or scheduling a post. That is real operational context. It does not state when to prefer this over postly_upload_media_batch or what the alternatives are, so it is context without exclusions.

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

All Postly MCP tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?