Skip to main content
MagicPost supports two media workflows:
  • attach_media_to_post copies a file reference supplied by a chat host such as claude.ai;
  • prepare_post_media_upload and complete_post_media_upload let code and CLI clients upload bytes from their local filesystem.
Both workflows link one file to an existing draft. You can then schedule or publish the post with its media.

​
Chat-host workflow

1

Create or update the draft

Call create_or_update_post and keep the returned post_id.
2

Attach the file

Add the file to the conversation, then call attach_media_to_post with the draft’s post_id. You can also provide optional alt text for an image.
3

Schedule or publish

After the attachment succeeds, call schedule_post or publish_post_now with the same post_id.
For example:
Create a LinkedIn draft from this text, attach the image in this conversation with the alt text “Product analytics dashboard”, then schedule it for tomorrow at 14:00.
Your MCP client must expose the uploaded file to the tool as a temporary file reference. If attach_media_to_post is not offered the file, create the draft in chat and add the media from the MagicPost web app.

​
Local-file workflow

Use this workflow with Claude Code or another MCP client that can read a local file and perform an HTTPS upload.
1

Create or update the draft

Call create_or_update_post and keep the returned post_id.
2

Prepare the upload

Call prepare_post_media_upload with the draft’s post_id, the file’s base name, and its MIME type. The tool returns an upload_id and a short-lived multipart upload_request.
3

Upload the local bytes

Send the local file to the signed URL exactly as described by upload_request. The URL expires after 15 minutes and must not be reused.
4

Complete the upload

Call complete_post_media_upload with the same post_id and upload_id. MagicPost validates the stored file before attaching it to the draft.
5

Schedule or publish

Call schedule_post or publish_post_now with the draft’s post_id.
In Claude Code, a request can be as simple as:
Create a LinkedIn draft from this text, attach the local file at /absolute/path/to/product.png, then schedule it for tomorrow at 14:00.
Claude Code can read the local file, call the two MagicPost upload tools, and perform the signed HTTPS upload between them. For manual troubleshooting, the equivalent upload shape is:

​
Supported files

Only one file can be attached to a post through either workflow.

​
Draft requirements

The target post must:
  • belong to your MagicPost account;
  • be unpublished and not currently publishing;
  • be unscheduled;
  • have no poll;
  • have no existing media.
If the draft is already scheduled, ask the client to cancel the schedule, attach the media, then schedule it again. The tool does not replace or remove existing media.

​
Client compatibility

MagicPost declares media_file as a file input for MCP hosts that support chat-provided files. File attachment behavior still depends on the host and its MCP integration. For claude.ai and compatible ChatGPT clients, attach the file to the same conversation and explicitly ask the assistant to use it with attach_media_to_post. Claude Code and CLI hosts do not pass local paths to a remote MCP server. They must use the prepare_post_media_upload / complete_post_media_upload workflow instead. A local path is read by the client, never by the MagicPost server.

​
Privacy and transfer

The temporary file URL supplied by a chat host is used only during the tool call. For local uploads, the signed storage URL expires after 15 minutes. MagicPost validates the file type, size, MIME type, and signature before linking the stored copy to your draft. Temporary and signed URLs are not stored in the post or included in tool audit data. The MCP cannot browse your MagicPost media library or retrieve media from past posts.

​
Common errors

​
Tool details

See the generated schemas for attach_media_to_post, prepare_post_media_upload, and complete_post_media_upload.