OverviewAPI Reference
MCP Server

Tools

Reference for every Onepostly MCP tool, with inputs, outputs, and error codes.

Look up the inputs each tool accepts, the result it returns, and the errors it can raise. Your assistant reads the same definitions from the server, so this page is for checking what a tool can do or debugging a call.

Tool Catalog

ToolAccessUse it to
connections_listReadList connected accounts and get their accountId values.
publish_optionsReadGet the boards or privacy levels an account needs before posting.
posts_createWritePublish now or schedule a post to one or more accounts.
posts_listReadList posts, newest first, with filters.
posts_getReadGet one post with the status of each destination.
analytics_getReadRead normalized metrics for a post.
posts_deleteWriteDelete published posts from the platform.

Write tools need the mcp:write scope. See Access Levels.

Every tool returns a one-line text summary (for example Found 2 connected accounts.) and a structured result. The Output section of each tool describes the structured result.

connections_list

Lists the connected social accounts in the workspace. Call it first to get the accountId values the other tools need.

Input

Prop

Type

Output

Prop

Type

authHealth: "action_required" means the account must be reconnected. See Reconnect an Account.

publish_options

Returns the values an account requires before you can post to it. Pinterest needs a board and TikTok needs a privacy level. Other platforms return an empty required list and an empty options object.

Input

Prop

Type

Output

Prop

Type

Example output for a TikTok account:

{
  "account": {
    "id": "5a2d9c1e-7b4f-4e83-a6d0-3c8b1f9e2a74",
    "platform": "tiktok",
    "displayName": "Acme",
    "handle": "acme",
    "avatarUrl": null,
    "status": "active",
    "authHealth": "healthy"
  },
  "required": ["privacyLevel"],
  "options": {
    "privacyLevelOptions": ["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "SELF_ONLY"],
    "commentDisabled": false,
    "duetDisabled": false,
    "stitchDisabled": true,
    "maxVideoPostDurationSec": 600
  }
}

posts_create

Publishes a post now, or schedules it when you pass scheduledFor. One call can target several accounts. The tool accepts the same fields as POST /v1/posts, plus a clientRequestId idempotency key, and mediaKind is optional. See Publishing for how posts and destinations behave.

Input

Prop

Type

Rules that depend on mediaKind:

  • text cannot include mediaUrls. Every other kind needs at least 1 URL.
  • multi-image needs at least 2 URLs.
  • image, video, reel, and stories accept exactly 1 URL.

Which kinds each platform accepts is listed in Publishing. Media URLs must meet the media URL requirements. The server has no upload tool, so upload files with the Media API before the call.

Destination Fields

Each destination takes accountId (required), an optional text that replaces the root text for that account, and the platform fields for its platform, such as boardId for Pinterest or privacyLevel for TikTok. The complete list per platform is in Platform Settings. A field the account's platform does not accept fails with VALIDATION_ERROR, and the message names the field and the platforms that accept it.

Examples

Publish a text post now:

{
  "text": "Spring collection is live.",
  "destinations": [{ "accountId": "YOUR_X_ACCOUNT_ID" }]
}

Schedule an image post with a retry-safe key:

{
  "text": "Doors open at 9.",
  "mediaUrls": ["https://cdn.onepostly.com/media/storefront.jpg"],
  "scheduledFor": "2027-03-15T09:00:00",
  "timezone": "America/New_York",
  "clientRequestId": "launch-post-2027-03-15",
  "destinations": [
    { "accountId": "YOUR_INSTAGRAM_ACCOUNT_ID" },
    { "accountId": "YOUR_PINTEREST_ACCOUNT_ID", "boardId": "1084523710032119087" }
  ]
}

Output

Prop

Type

A queued post has not reached the platform yet. Call posts_get to follow it to published or failed. Status meanings are in Post Status.

posts_list

Lists the workspace's posts, newest first.

Input

Prop

Type

Output

Prop

Type

posts_get

Returns one post with the status, link, and error of each destination.

Input

Prop

Type

Output

Prop

Type

analytics_get

Returns normalized metrics for a post, one entry per destination. Pass a Onepostly post id, a destination id, or the platform's own post id together with accountId for a post published outside Onepostly. See Outside Posts.

Input

Prop

Type

Pass postId, destinationId, or both. A call with neither fails with VALIDATION_ERROR.

Output

Prop

Type

A published destination with no metrics yet returns pending. Status meanings and per-platform metric support are in Analytics Status.

posts_delete

Deletes published posts from the platform. Pass destinationId to delete one destination, or leave it out to delete every published destination of the post. The post stays in Onepostly and those destinations change to deleted. Which platforms support deleting is listed in Remote Delete.

Input

Prop

Type

Output

Prop

Type

Deleting a destination that is already deleted succeeds and returns the post unchanged. When every destination fails, the tool returns an error with the code of the first failure instead of this result.

The Post Object

posts_create, posts_list, posts_get, and posts_delete return posts in this shape.

Prop

Type

Example posts_get result for a post published to X and Bluesky:

{
  "post": {
    "id": "1699f415-7fb6-43f4-9d2a-c447491f32a8",
    "text": "Spring collection is live. Free shipping through Sunday.",
    "mediaKind": "text",
    "status": "published",
    "scheduledFor": null,
    "timezone": null,
    "createdAt": "2027-03-15T09:00:02.114Z",
    "updatedAt": "2027-03-15T09:00:06.871Z",
    "destinations": [
      {
        "id": "c27a9e4b-6f13-4d8a-a5b2-9e0d1f3c7a64",
        "accountId": "3f6c2a91-5d4e-4b7a-9e1f-8a2b6c0d4e57",
        "platform": "x",
        "status": "published",
        "externalPostId": "1899745123456789012",
        "externalUrl": "https://x.com/i/web/status/1899745123456789012",
        "error": null,
        "publishedAt": "2027-03-15T09:00:05.402Z"
      },
      {
        "id": "e5d8b2f1-3c7a-4e96-8b4d-2a1f0c9e6d35",
        "accountId": "8b1e7d3c-2a9f-4c65-b0d8-5e4f1a7c9b23",
        "platform": "bluesky",
        "status": "published",
        "externalPostId": "at://did:plc:4k2xq7mzv3r5t6y8w9a1b2c3/app.bsky.feed.post/3lkq7xz2abc2w",
        "externalUrl": "https://bsky.app/profile/acme.bsky.social/post/3lkq7xz2abc2w",
        "error": null,
        "publishedAt": "2027-03-15T09:00:06.533Z"
      }
    ],
    "mediaUrls": []
  }
}

Errors

A failed call returns a tool result marked as an error. Its text is a JSON object with a code, a message, the HTTP-style status, and, when it helps, a hint with the next step. Invalid arguments also list every problem in issues, each with the param at fault:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid tool arguments.",
    "status": 400,
    "issues": [
      {
        "param": "timezone",
        "code": "custom",
        "message": "timezone requires scheduledFor."
      }
    ]
  }
}
CodeCauseFix
VALIDATION_ERRORAn argument is missing or invalid, the text is over a platform's limit, or a destination has a field or mediaKind its platform does not accept.Fix the arguments named in issues or in the message, then call again.
ACCOUNT_NOT_FOUNDThe accountId is not a connected account in this workspace.Call connections_list and use an id from its result.
CONNECTION_INACTIVEThe account is not active.Reconnect the account. See Reconnect an Account.
NOT_FOUNDNo post with this postId exists in the workspace.Call posts_list to find the post id.
DESTINATION_NOT_FOUNDThe destinationId, or the accountId passed with a post id, does not match a destination of the post.Call posts_get and use a destination id from its result.
ACCOUNT_REQUIREDanalytics_get received a postId that is not a Onepostly post id, without accountId.Pass the accountId of the account that published the post.
OPTIONS_UNAVAILABLEThe platform did not return the account's boards or creator settings.Call publish_options again. If it keeps failing, check the account in connections_list and reconnect it.
RATE_LIMITEDThe account reached its posting limit on the platform. details.retryAfterSeconds says how long to wait.Wait that long, or schedule the post for later. See Rate Limits.
NOT_DELETABLEThe destination is not published, or the post has no published destination to delete.Check the destination statuses with posts_get.
UNSUPPORTED_PLATFORMDeleting posts is not available for the destination's platform.Delete the post in the platform's own app.
INSUFFICIENT_WALLETThe workspace wallet does not cover the X delete.Top up the wallet in Settings → Wallet, then call again.
TOKEN_INVALIDThe platform rejected the account's authorization.Reconnect the account. See Reconnect an Account.
PLATFORM_UNAVAILABLEThe platform did not respond in time.Call again.
DELETE_FAILEDThe platform refused the delete.Read the message. Call again, or delete the post in the platform's own app.
TOOL_ERRORThe call failed unexpectedly.Call again. For posts_create, reuse the same clientRequestId so the post is not created twice.

Other codes match the REST API. See Error Codes.

See Also

Setup

Add the server to your client and manage its access.

Platform Settings

Every destination field and text limit per platform.

Publishing

Post statuses, scheduling, threads, and remote delete.

Analytics

Metric definitions and analytics status values.

Setup

Client configuration for the Onepostly MCP server, access levels, revoking access, and connection errors.

Supported Platforms

Capabilities, post types and connection method for each platform Onepostly publishes to.

On this page

Tool Catalogconnections_listInputOutputpublish_optionsInputOutputposts_createInputDestination FieldsExamplesOutputposts_listInputOutputposts_getInputOutputanalytics_getInputOutputposts_deleteInputOutputThe Post ObjectErrorsSee Also