Skip to main content
Connect a supported MCP client to the social accounts and workflows you manage in PostOnce. Start with the MCP setup instructions for the recommended connection method.
  • Endpoint: https://postonce.to/mcp
  • Transport: Streamable HTTP
  • Manual authentication: Authorization: Bearer <PostOnce API key>
The hosted server forwards your credential to the Public API for each tool operation. Your existing plan access and credential scopes apply. A custom configuration is separate from an official client directory listing.

​
Prepare your account

Create a dedicated key in Preferences → API keys. Start with accounts:read to check the connection; add the relevant posts, media or workflow scopes for the actions you need. Keep the key in your client’s private configuration or secret environment, never in a conversation or a committed project file. Connect your social accounts in PostOnce. An empty account list means the connection worked but no usable social accounts were returned. See plans for Public API entitlement.

​
Other clients

Use the endpoint, Streamable HTTP transport and private Authorization header above if your client supports them. A client that requires OAuth needs its own supported setup; an arbitrary JSON snippet does not establish compatibility. Consult the integration directory for available client instructions.

​
First useful action

Ask: “Show my connected social accounts.” The list_accounts and list_active_accounts tools return account IDs and platform capabilities. Check media_requirements for required media and input constraints before choosing a text, image or video post. These are platform-level constraints; the service still checks account permissions at the requested operation. For an authorized post:
  1. Select actual returned account IDs and prepare the content.
  2. Call create_post with the content and those targets. Use a future publish_at timestamp only when scheduling is intended. Use create_draft for a draft.
  3. Call get_post with the returned ID and inspect every destination’s actual status. A queued or scheduled post has not necessarily been published.
  4. Review delivery and recovery in publishing history.
For automatic crossposting, inspect list_workflows first. Use create_workflow or update_workflow with the selected source and destination IDs, then read the saved rule with get_workflow. A new active workflow is configured to process future source content; its creation does not prove a source post has already been delivered. Review it in Workflows.

​
Media with the hosted connection

Pass a supported, publicly fetchable media URL to create_post, or upload a selected local file from your client:
  1. Call create_upload_url with filename and content_type.
  2. PUT the file bytes from the client to the returned data.upload.signedUrl using the matching content type. Check that upload succeeds. Do not send your PostOnce key to the storage host or expose the signed URL in chat/logs.
  3. Call get_media with data.media_id and use the returned public_url in the post’s media object.
  4. Inspect the resulting post’s delivery status.
An allocated media ID alone is not proof that a file was uploaded. Media prepared for publishing is publicly accessible. Check the destination’s media and thumbnail requirements. The hosted server cannot read a path on your computer. It does not expose upload_media_from_path, create_media_post_from_path or create_tiktok_draft_from_path; those helpers belong to a separately configured local stdio server. A chat attachment works only when the client can transfer its bytes through the supported upload flow or provide a suitable accessible URL.

​
Reusable agent skill

The PostOnce skill teaches account discovery, media transfer, posting, delivery inspection and automatic crossposting. Use it as workflow guidance according to your client’s supported skill mechanism. Installing a skill adds guidance; it does not authenticate the client or change plan access.

​
Errors and recovery

  • Invalid or revoked credentials: reconnect through the supported client setup.
  • Missing scope or plan access: follow the returned requirement and update the existing key or plan as appropriate.
  • Disconnected social account: reconnect it in PostOnce and refresh account discovery.
  • Invalid media/settings: correct the specific input from the response before retrying.
  • Uncertain creation result: retain the same idempotency_key and identical payload, inspect existing results before retrying, and avoid publishing a second copy.
  • Partial delivery: inspect each destination and recover the failed destination rather than recreating the post for every target.
Revoke manual keys in Preferences → API keys. Removing a server configuration or deleting a skill alone does not revoke its credential.