Postminion MCP docs

Set up your agent to publish through Postminion

Connect once with the server URL below. Your assistant sends you to Postminion to sign in and approve what it may do. There is no API key to create or paste.

Connect your assistant

You need:

A Postminion account with an active subscription.
At least one social account connected in Postminion.
An AI assistant that can add remote MCP servers with OAuth, often called custom connectors.

Server URL

https://mcp.postminion.com/mcp

In your assistant, add a custom connector (it may be called a custom or remote MCP server) and paste the server URL.
Your assistant opens Postminion. Sign in, pick a workspace if you have several, and review the permissions it asks for.
Approve. Full requested approves everything the assistant asked for, including immediate publishing; Schedule preset approves everything except immediate publishing. You can also untick single permissions.
Check that it worked: ask your assistant to list your connected social accounts.

Permissions and account reach

Access covers every social account in the workspace you approve, including accounts you connect later; it can't be limited to some of them. The consent screen lists each permission separately and warns you when an assistant asks for immediate publishing.

An assistant never gains permissions on its own. To allow something you didn't approve, disconnect it and connect again. Revoking one assistant doesn't disconnect your social accounts or affect other assistants.

Example prompts

“List my connected social accounts and tell me what each supports.”

“Create a draft for my Facebook Page and LinkedIn profile. Do not schedule it.”

“List my posts scheduled for the next seven days.”

“Schedule this post for 9:30 AM tomorrow in Asia/Makassar after validating it.”

“Move that draft to Friday at 2:00 PM in America/New_York, using its current revision.”

“Accept this post for immediate publishing, then check its status until the platform result is available.”

“Cancel the scheduled post we just created, using its current revision.”

“Check the status and per-account results for that post.”

“Upload the eight PNGs in ~/Desktop/slides and schedule them as one Instagram carousel for Monday 9:00 AM in Europe/Berlin.”

Publishing runs in the background. When you ask to publish now, Postminion accepts the post into its publishing queue right away; ask your assistant for the post's status to see each network's result.

Photos and videos

Attached in the chat: if your assistant passes chat attachments to tools, attach the files to your message and it imports them into your Postminion media library.
Attachments that don't arrive: some assistants keep attachments to themselves. Ask the assistant to save a draft, then open the editor link it gives you and add the files from your device.
Public links: any assistant can use a photo or video at a public HTTPS link. Postminion downloads and checks it when the post is saved.
Files on your computer: coding agents that can run shell commands upload local files themselves; see Uploading local files.

Photos are stored as JPEG so every network accepts them: PNG and WebP are converted, and anything larger than TikTok's limit of 1080 by 1920 pixels (in either orientation) is scaled down to fit. GIFs and videos are never converted. Images can be up to 30 MB and videos up to 512 MB, as JPEG, PNG, WebP, GIF, MP4, WebM, or QuickTime.

Drafts and scheduled posts come with a link that opens them in the Postminion editor. If a post needs a fix only the editor can make, Postminion saves it as a draft and your assistant gives you that link.

What your assistant will ask you

TikTok

TikTok's rules require you, not the assistant, to choose the privacy level (everyone, friends, followers, or only you) and both disclosure settings (your own brand and branded content) for every post, so expect your assistant to ask each time. You can also set comments, duet, stitch, the AI-generated content label, auto-music, and the video cover.

YouTube

Shorts need a title and a video. Each account can also get its own caption.

Instagram

Choose feed, story, or reel. Stories and reels must meet their own media shape rules.

All platforms

Every time a post is saved or changed, Postminion checks that each account is still connected and rechecks captions, media counts, and platform combinations.

Troubleshooting

Connecting fails or the sign-in page shows an error: Start connecting again from your assistant. Each sign-in link is short-lived and works once.
The assistant says it doesn't have permission: That permission wasn't approved when you connected. Disconnect the assistant, connect again, and approve it.
The assistant can't find my social accounts: Connect them in Postminion under Accounts & Integrations, in the workspace you approved, then ask again.
The assistant says a subscription is required: Creating posts needs an active Postminion subscription. See plans.
An attached photo or video didn't arrive: Your assistant may not pass attachments to Postminion. Ask it to save a draft and add the file through the editor link, or give it a public link to the file.
The assistant gave me an editor link: The post needs a fix only the editor can make, such as an image TikTok won't accept. Open the link, remove that image, and add it again from your device. Then publish from the editor, or tell the assistant you're done.
The post was accepted but isn't on the network yet: Publishing runs in the background and can queue or retry. Ask your assistant for the post's status; it shows each network's result, including the reason for any failure.

Review and revoke

Open AI Agents in the Postminion sidebar. Each connected assistant shows its permissions, account reach, when it was connected and last used, and its recent activity. Choose Revoke access and confirm. The assistant loses access immediately; your login, social accounts, posts, and other assistants are unaffected.

For developers

Reference for agent builders, and for checking what an assistant does on your behalf. Agents also read each tool's input schema and usage instructions from the server itself.

Server and authorization

Remote MCP over Streamable HTTP at https://mcp.postminion.com/mcp; the URL carries no credentials. Clients discover OAuth from the protected-resource metadata, register with a Client ID Metadata Document or dynamic client registration, and authorize with the code flow and S256 PKCE. Access tokens are short-lived and refresh tokens rotate. A grant covers one workspace's current and future social connections, and another user's IDs deliberately look missing. A refresh never adds scopes: a call that needs an ungranted scope fails with insufficient_scope until the user reconnects and approves it.

Compatibility

Postminion works with MCP clients that support remote servers and OAuth. A client is named here once its current version passes our launch tests.

MCP-compatible client

Tested: postminion-conformance/2026-08-05
Protocol: 2026-07-28
OAuth: OAuth discovery with authorization code and S256 PKCE
Step-up: Explicit preset re-consent fallback

Named products appear only after their launch version passes OAuth, refresh, write-action, annotation, and media tests.

Scopes

Scope	Allows
accounts:read	See connected social accounts, their status and publishing capabilities, and validate posts.
posts:read	See drafts, scheduled posts, publishing status, and post details.
posts:draft	Create drafts without scheduling or publishing them.
posts:schedule	Schedule posts and move a ready draft into the publishing pipeline.
posts:publish	Accept posts for immediate publishing. Separate from scheduling.
posts:update	Edit drafts and scheduled posts that publishing has not claimed.
posts:cancel	Cancel scheduled posts before publishing claims them.
media:write	Upload files, import chat attachments and public HTTPS media, and reuse media from the library.

Tools

Tool	Scope	Behavior
list_social_accounts	accounts:read	Returns only your connected account identities, readiness, capabilities, defaults, and required settings.
validate_post	accounts:read	Read-only draft or publish_ready validation; never creates content or downloads media. Returns nextStep when only the web editor can fix the blocking issues.
create_draft	posts:draft	Creates one draft with a stable requestId.
schedule_post	posts:schedule	Creates one post at a local date/time plus IANA timezone.
publish_post_now	posts:publish	Accepts one post into asynchronous immediate publishing.
list_posts	posts:read	Lists owned posts with bounded cursor, status, account, and date filters.
get_post	posts:read	Returns revision, safe media, aggregate state, per-account results, post URLs, and editUrl.
update_post	posts:update	Updates an editable owned post using expectedRevision; draft-to-scheduled also needs posts:schedule.
cancel_scheduled_post	posts:cancel	Cancels an owned scheduled post before Postminion claims it.
import_attached_media	media:write	Imports files the user attached in the conversation, for clients that pass attachments through the openai/fileParams extension. Returns one assetId per file.
create_media_upload	media:write	Reserves direct uploads for local files: per file an assetId, a one-hour presigned PUT URL, exact headers, and a ready-to-run curl command.
complete_media_upload	media:write	Verifies uploaded objects (size, Content-Type, real media type), converts and resizes still images, and marks the assets usable; repeat-safe.

Media entries use exactly one of assetId or url, plus type (image, GIF, or video). Platform entries need platform and an owned connectionId from list_social_accounts. Mutation results return accepted and published flags, contentId, revision, state, replay status, and warnings, plus editUrl for drafts and scheduled posts, or a structured safe error. When schedule_post or publish_post_now is rejected only for issues the editor can fix, Postminion keeps a draft and returns its editUrl with the error.

Validation modes

draft allows incomplete work and reports publish-readiness gaps as warnings. publish_ready treats required captions, media, titles, disclosures, account settings, schedule, and platform constraints as blocking issues.

TikTok settings

customizations.tiktok.privacyLevel must be one of PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, or SELF_ONLY; list_social_accounts returns the allowed values as capabilities.privacyLevels, and any other value is rejected before the post is created. Agents must ask the user for the privacy level and both disclosure toggles and never infer or default them.

Uploading local files

Coding agents that can run shell commands can post local files. The flow is three calls and one shell step, and it needs the media:write scope:

create_media_upload with each file's local path, exact byte size, MIME type, and type (image, gif, or video). The result carries one assetId per file, a presigned PUT URL, the exact headers, and a curl command built from them.
Run every returned curl command. The agent needs shell access for this step; clients without a shell should use attachments, public HTTPS URLs, or the editor link instead.
complete_media_upload with the asset IDs. Postminion checks the stored size and Content-Type and sniffs the leading bytes; a mismatch marks that asset failed and deletes the object, while the other assets still complete.
Reference the verified IDs as media[].assetId in validate_post, create_draft, schedule_post, publish_post_now, or update_post.

Uploads that are not completed within one hour expire and are deleted, and a mutation that references a pending asset returns media_upload_incomplete. Each call accepts up to 35 files. Uploaded files join the same workspace media library as imported URLs and the web app.

complete_media_upload converts and resizes still images as described under Photos and videos, at JPEG quality 85 with transparency flattened onto white, the same normalization the web composer applies. PNG and WebP uploads get a non-blocking static_image_will_be_converted notice at upload time, and a converted asset reports image/jpeg, a .jpg filename, and normalizedFrom with the original type. Upload files as they are; no conversion step is needed.

Media by URL

Mutation inputs accept an owned verified asset ID or a public HTTPS URL with declared image, GIF, or video intent. URL credentials, HTTP, alternate ports, private/loopback/link-local/reserved destinations, excessive redirects, oversized bodies, unsupported or spoofed types, and unsupported containers are rejected. Imports use Postminion-generated object keys and are cleaned up if the content mutation fails.

validate_post never fetches a URL; treat its media result as provisional until a mutation imports and verifies the file. For an owned verified assetId it uses the stored format, size, and dimensions.

Status and retries

accepted means Postminion durably accepted the content; it does not mean every network published it.
Use get_post for aggregate and per-account queued, publishing, published, failed, or cancelled states. Each account updates as its platform finishes; the aggregate status is reconciled shortly after, so poll until it leaves queued.
Every mutation needs a stable domain requestId. Repeating the same operation and canonical payload returns the stored result.
Reusing the ID with a changed payload returns an idempotency conflict.
If the client loses the response, retry the exact call with the same ID. Never invent a new ID until the result is known.
Completed replay receipts are retained for 30 days. Do not reuse business request IDs after that window.
Updates and cancellation also require the latest expectedRevision; fetch again after a conflict.