Postkey: Instagram DM Automation and Comment-to-DM

Start a file upload

postkey_begin_upload

Postkey: Puts one file into the Library. A file attached to this chat: try this first, yourself, before postkey_request_file or postkey_list_library. It is usually in your own workspace, computer or sandbox: send its name, exact size in bytes and type. From a web address (a video or picture made on Higgsfield, fal, Sumi Studio, HeyGen and the like, or a Dropbox or Drive share link): send url alone, in the same turn, since those links run out. Postkey copies it in (up to 1 GB) and answers library_item_id: done. Any other file you can read with a command: the same. The answer's upload_url takes the bytes in one HTTP PUT with the same Content-Type (curl -X PUT -H "Content-Type: video/mp4" --data-binary @clip.mp4 "<upload_url>"), for 2 hours, up to 5 GB and no larger than the size sent. Then postkey_finish_upload with the path (finish_with spells it out). Nothing is published.

Input Schema

Name	Required	Description
`url`	No	The file's https address. Postkey fetches it and adds it to the Library in this one call. Send it without name, size and type.
`name`	No	Without url: the file's name with its extension, for example episode-1.mp4. 1 to 300 characters.
`size`	No	Without url: the file's exact size in bytes (from ls -l or stat), at most 5 GB. A file that turns out larger is refused at the PUT.
`type`	No	Without url: the file's MIME type: video/mp4, video/quicktime, image/jpeg, image/png and so on. Left out: read from the name's extension. Send the same value as the PUT's Content-Type.
`title`	No	With url: the file's title in the Library, 1 to 300 characters. Left out: the file's own name.

Output Schema

Name	Required	Description
`ok`	Yes	false: refused (isError; code, message, guide_topic, url); no change.
`kind`	No	With url: video, image or audio, read from the file itself.
`next`	No	What to do next.
`path`	No	Pass it to postkey_finish_upload.
`method`	No	PUT.
`example`	No	A curl command for the PUT.
`headers`	No	The headers the PUT needs (Content-Type).
`max_bytes`	No	The largest file the link takes.
`expires_at`	No	When the link stops working.
`size_bytes`	No	With url: the stored file's size.
`upload_url`	No	Send the file's bytes here with one HTTP PUT.
`finish_with`	No	The next call: { tool: postkey_finish_upload, args: { path, kind } }; add the title.
`library_item_id`	No	With url: the new Library file's id. The file is in the Library; there is no finish step.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 9, 2026

changedOutput schema / properties / ok / description

Previous value: -"false: refused (isError true; code, message, guide_topic, url), nothing changed."New value: +"false: refused (isError; code, message, guide_topic, url); no change."

Changed9 schema fields changedNov 5, 2026

changedInput schema / properties / name / description

Previous value: -"The file's name with its extension, for example episode-1.mp4. 1 to 300 characters."New value: +"Without url: the file's name with its extension, for example episode-1.mp4. 1 to 300 characters."

changedInput schema / properties / size / description

Previous value: -"The file's exact size in bytes (from ls -l or stat), at most 5 GB. A file that turns out larger is refused at the PUT."New value: +"Without url: the file's exact size in bytes (from ls -l or stat), at most 5 GB. A file that turns out larger is refused at the PUT."

addedInput schema / properties / title

Added value: +{
+  "description": "With url: the file's title in the Library, 1 to 300 characters. Left out: the file's own name.",
+  "maxLength": 300,
+  "minLength": 1,
+  "type": "string"
+}

changedInput schema / properties / type / description

Previous value: -"The file's MIME type: video/mp4, video/quicktime, image/jpeg, image/png and so on. Left out: read from the name's extension. Send the same value as the PUT's Content-Type."New value: +"Without url: the file's MIME type: video/mp4, video/quicktime, image/jpeg, image/png and so on. Left out: read from the name's extension. Send the same value as the PUT's Content-Type."

addedInput schema / properties / url

Added value: +{
+  "description": "The file's https address. Postkey fetches it and adds it to the Library in this one call. Send it without name, size and type.",
+  "maxLength": 2000,
+  "pattern": "^https://",
+  "type": "string"
+}

removedInput schema / required

Removed value: -[
-  "name",
-  "size"
-]

addedOutput schema / properties / kind

Added value: +{
+  "description": "With url: video, image or audio, read from the file itself.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / library_item_id

Added value: +{
+  "description": "With url: the new Library file's id. The file is in the Library; there is no finish step.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / size_bytes

Added value: +{
+  "description": "With url: the stored file's size.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

Changed4 schema fields changedOct 24, 2026

changedInput schema / properties / name / description

Previous value: -"The file's name, with its extension (episode-1.mp4)."New value: +"The file's name with its extension, for example episode-1.mp4. 1 to 300 characters."

changedInput schema / properties / size / description

Previous value: -"The file's exact size in bytes (for example from ls -l or stat). A file that turns out larger is refused."New value: +"The file's exact size in bytes (from ls -l or stat), at most 5 GB. A file that turns out larger is refused at the PUT."

changedInput schema / properties / type / description

Previous value: -"The file's type: video/mp4, video/quicktime, image/jpeg, image/png and so on. Read from the name when left out."New value: +"The file's MIME type: video/mp4, video/quicktime, image/jpeg, image/png and so on. Left out: read from the name's extension. Send the same value as the PUT's Content-Type."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "example": {
+      "description": "A curl command for the PUT.",
+      "type": "string"
+    },
+    "expires_at": {
+      "description": "When the link stops working.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "finish_with": {
+      "description": "The next call: { tool: postkey_finish_upload, args: { path, kind } }; add the title.",
+      "type": "object"
+    },
+    "headers": {
+      "description": "The headers the PUT needs (Content-Type).",
+      "type": "object"
+    },
+    "max_bytes": {
+      "description": "The largest file the link takes.",
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "method": {
+      "description": "PUT.",
+      "type": "string"
+    },
+    "next": {
+      "description": "What to do next.",
+      "type": "string"
+    },
+    "ok": {
+      "description": "false: refused (isError true; code, message, guide_topic, url), nothing changed.",
+      "type": "boolean"
+    },
+    "path": {
+      "description": "Pass it to postkey_finish_upload.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "upload_url": {
+      "description": "Send the file's bytes here with one HTTP PUT.",
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "ok"
+  ],
+  "type": "object"
+}

First observedOct 23, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations only cover readOnly/openWorld/destructive; the description adds the substantive behavior: a direct fetch path capped at 1 GB, an alternate upload_url path capped at 5 GB and valid for 2 hours, a PUT with matching Content-Type, size enforcement at PUT time, and the reassurance 'Nothing is published.' It stops short of describing error modes or what happens on expiry mid-PUT, so not a 5.

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?

It is front-loaded and information-dense, but written as long run-on clauses with an awkward lead-in ('Postkey: Puts one file into the Library') and an inline curl example that bloats the prose. Almost nothing is redundant, yet the structure makes it slower to scan than necessary.

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?

For a two-phase upload tool with a mutation annotation, no output schema detail needed, the description covers limits, expiry, follow-up tool, and non-publication. Missing only failure handling (link expired during PUT, oversized file rejected) and any permission expectations.

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 the baseline is 3; the description still adds value by stating the mutual-exclusivity rule (url alone vs. name+size+type) that the per-property schema text only implies individually, plus the requirement that 'type' match the PUT's Content-Type. It does not explain the optional 'title' behavior, which lives only in the schema.

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

Purpose5/5

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

Opens with a specific verb+resource ('Puts one file into the Library') and immediately frames the two intake modes (local file metadata vs. https URL). It is unmistakably distinct from siblings like postkey_request_file and postkey_list_library, which it names.

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?

Gives explicit ordering ('try this first, yourself, before postkey_request_file or postkey_list_library'), selection rules for url vs name/size/type, and names the required follow-up (postkey_finish_upload). The 'same turn' warning for expiring links is a real operational constraint, not filler.

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

All Postkey: Instagram DM Automation and Comment-to-DM 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?