add_tag
ChatGPTAttach a tag to an existing post. create_post also accepts tags=[...] at creation time; this tool is for a post that already exists. Idempotent per (post_id, tag). Requires WRITE-level access on the account.
connect_account
ChatGPTConnect a social account to Postey, or re-authorise one whose credential has expired. Returns a link for the user to open in their browser; no credential is returned to the caller. When the platform needs connecting or reconnecting, the call fails with a URL-elicitation error (-32042) whose data carries the link. After the user finishes in the browser, a repeat call confirms the connection; repeat calls are safe. Credentials are per account, not per platform: one account's X can be RECONNECTION_REQUIRED while another's is fine, so account_id selects the account being fixed. Without account_id the call answers the fleet-wide question and, when accounts disagree, returns needs_reauth[] and healthy[] instead of a link, because the target account is ambiguous. Each blocker in postey://setup carries the account_id for this tool in its action.arguments.
convert_post_content
ChatGPTAdapt an existing post's content from one platform to one or more others, in place on the same post_id (updates the contents for each target). It is for explicit requests to auto-adapt content (e.g. 'convert this to LinkedIn', 'adapt for Bluesky'). Automatic adaptation can lose intentional formatting; hand-written per-platform content goes through update_post. Prerequisites: source_platform already exists on the post, and target_platforms does not contain it. validate_post_content checks each target afterwards. Synced platforms: synced_platforms=[...] (a subset of target_platforms) locks those platforms and keeps them mirrored from source_platform going forward, instead of a one-time conversion. It is only valid when source_platform is the post's primary platform (socials[0]), and applies when the user asks for platforms to stay mirrored.
create_post
ChatGPTCreate a new DRAFT post. account_id comes from postey://accounts, which lists every account the caller can access, and is the account the user confirmed for this post, including when only one account exists. postey://platforms/{platform}/rules lists each platform's required, optional and forbidden content fields. One create_post call covers every platform for a topic: platform and contents for the first platform, additional_platforms=[{platform, contents}, ...] for the rest. All of them share one post_id, which cross-platform grouping, scheduling and analytics rely on. Separate create_post calls for the same topic create separate post_ids that cannot be grouped, scheduled or managed together. Example: create_post(platform=X, contents=[...], additional_platforms=[{platform: LINKEDIN, contents: [...]}, {platform: INSTAGRAM, contents: [...]}]). convert_post_content is for explicit requests to auto-adapt content, not for multi-platform creation. The compose-post prompt covers each target platform, and content has to fit the platform's hard limit (validate_post_content checks it). tags=[...] attaches tags inline, without separate add_tag calls. postey://accounts/{account_id}/tags lists existing tags; reusing an existing name with its exact casing attaches that tag.
delete_draft
ChatGPTDelete a DRAFT post, either to the trash or permanently. Only posts currently in DRAFT status can be deleted here; published or scheduled posts cannot. The mode is the user's choice and needs their confirmation: trashing leaves the post recoverable for 30 days via restore_post(post_id), but it still counts toward the account's draft limit until it is permanently deleted or the trash window expires; permanent deletion is irreversible but frees that limit slot immediately. Either way the post leaves every listing immediately and its schedules are purged. mode='trash' or mode='permanent' acts immediately without an interactive prompt, which is the reliable way to reach permanent deletion on clients that don't support interactive confirmation.
file_manager
ChatGPTUpload a local file (image or video) to Postey's CDN and get back a cdn_url for a post's media. The file goes straight to the CDN; the assistant receives only the URL, never the file contents. It is for files on the user's machine; upload_media handles files that already have a public URL. The returned cdn_url is the media URL as given; a URL built from an id, filename or path points at no stored object. It does not upload anything by itself: it returns a widget that the client renders and the user drops a file into. A client that cannot render MCP Apps UI uploads nothing, and no error says so; upload_media with source_type='url' or 'base64' works on those clients. Media uploaded through Postey's MCP surface cannot currently be deleted.
get_accounts
ChatGPTEvery social account the caller can access, with its connected platforms. Returns the same data as the resource postey://accounts, for clients that cannot read MCP resources. When several accounts exist, which one to use is the user's choice.
get_post_content
ChatGPTFull text and media of one post on one platform, looked up by post_id. Returns the same data as the resource postey://posts/{post_id}/content/{platform}, for clients that cannot read MCP resources.
get_posts
ChatGPTList post summaries for one account and one platform, filtered by status (DRAFT, SCHEDULED, PUBLISHED). Suited to requests about 'my posts' or 'drafts', or to picking a post. Returns no post text; postey://posts/{post_id}/content/{platform} has that. Requires platform and account_id (from postey://accounts). One call covers one platform, so a cross-platform question takes one call per platform. Default size=10, max=100.
get_review_status
ChatGPTCollect the result of a review_post run, by job_id (preferred) or post_id (fallback when the job_id is lost; resolves to the most recent review_post job for that post). Exactly one of job_id or post_id is accepted. review_post starts a full AI pass that takes 60-120 seconds and returns a job_id immediately rather than holding the call open. status is one of: running (not finished; a later call returns the result), done (result carries the comments that were written), error (the run failed and the reason says why), lost (the worker was replaced mid-run, most likely by a deploy; a new review_post is needed). Read-only: polling costs nothing and never runs a second AI pass. Calling review_post again for the same post while a job is running runs a second paid pass and writes a second set of comments.
get_schedule
ChatGPTRetrieve the current schedule for a SCHEDULED post: which platforms are scheduled and when (UTC), plus any existing post actions and Auto-DM rules per platform, reported read-only. Returns NOT_FOUND if the post has no active schedule. get_posts(status=SCHEDULED) lists all scheduled posts.
get_team_info
ChatGPTFull team details, including every member's resolved display name, email and access level. Translates the created_by / published_by UUIDs on posts into names. Returns the same data as the resource postey://teams/{team_id}, for clients that cannot read MCP resources. The response carries real member email addresses. They are there to identify teammates inside this team (attributing a post, or checking who holds which access level), not for repeating to the user unprompted or for contacting anyone.
get_teams
ChatGPTEvery team the caller owns or belongs to, with team_id, team_name, accounts and the caller's permission level. Returns the same data as the resource postey://teams, for clients that cannot read MCP resources.
list_files
ChatGPTList the files uploaded through the file_manager widget, with their cdn_url, name, size and content type. A file the user already dropped appears here; uploading it again creates a second copy with a different URL. It does not list media uploaded with upload_media. Only the file_manager widget writes to this index, so an empty list does not mean nothing was uploaded, and a cdn_url that upload_media returned cannot be recovered here. Scoped to the calling credential, not to one conversation, and kept for 24 hours after the last upload. It never lists another user's files.
publish_draft
ChatGPTImmediately publish a DRAFT post to selected platforms. Publication is irreversible and publicly visible on the real social networks, so it needs the user's explicit confirmation in the current turn. Rejects non-DRAFT posts; get_posts(status=DRAFT) lists drafts.
read_file
ChatGPTReturn the metadata for one uploaded file by id: its cdn_url, name, size and content type. Recovers the cdn_url for a file listed by list_files. Returns metadata only, never the file's bytes.
remove_tag
ChatGPTDetach a tag from an existing post by tag_id. The tag itself is not deleted; only its association with this post is removed. Idempotent: detaching a tag that exists but is not attached to this post is a no-op and returns success. A tag_id that does not exist, or that belongs to a different account, is an error, so 'removed' always means the tag is now off the post. Requires WRITE-level access on the account.
resolve_share_link
ChatGPTResolve a Postey share URL (app.postey.ai/?d=...) or share_id to post metadata (post_id, account, platform, status). It is the only lookup available when a share link is all there is. Metadata only; postey://posts/{post_id}/content/{platform} has the text. Accepts only Postey share links, not Instagram, YouTube, TikTok, X or other social media URLs. Read-only.
restore_post
ChatGPTBring a post back from the trash. A post reported as in the trash still has its content intact, so restoring it recovers the original post instead of creating a replacement. Works for 30 days after deletion; after that the post cannot be recovered. A post that was SCHEDULED or PUBLISHING comes back as a DRAFT, because deleting it purged its schedules.
restore_posts
ChatGPTRestore several trashed posts at once. postey://accounts/{account_id}/trash lists what is in the trash and how many days each post has left. Each post comes back as a DRAFT. Works for 30 days after deletion; after that a post cannot be recovered. Partial success is normal: the result names what was restored and, per post, why anything else was not. restore_post handles a single post.
review_post
ChatGPTAnalyse a post for virality and add Postey's internal team comments (visible only inside Postey, never published to the platform) with specific improvement suggestions. Works on a post in any status: draft, scheduled or published. Returns a job_id immediately and runs the AI pass in the background, because the pass takes 60–120 seconds, longer than most clients wait. get_review_status(job_id) returns the result; it is read-only and costs nothing. A second call for the same post while a job is running runs a second AI pass, writes a second set of comments and is charged again. Requires COMMENT-level access on the account.
schedule_post
ChatGPTSchedule a DRAFT post for automatic publication. Each platform can have its own scheduled_at timestamp, so publishing can be staggered across platforms. Once the scheduled time arrives, publication is irreversible and publicly visible, so scheduling needs the user's explicit confirmation. scheduled_at is a UTC timestamp at least 10 minutes in the future, measured from server now (retrieved_at on any response) and computed after the user confirms. A relative request ("now", "in 5 minutes") needs at least 15 minutes of margin; an absolute confirmed time is sent exactly as confirmed. A confirmed time that has passed is rejected rather than moved, and a replacement time is the user's choice.
store_files
ChatGPTInternal endpoint for the file_manager widget. Not for direct model use: the widget POSTs the bytes the user dropped into it here, base64-encoded, and this stores them on Postey's CDN under the caller's storage quota. To upload media, call file_manager (opens the drop widget) or upload_media (for media already at a public URL, or a base64 payload). Calling this directly bypasses the widget that is supposed to produce its argument.
unschedule_post
ChatGPTCancel the schedule for one or more platforms on a SCHEDULED post; the post reverts to DRAFT when all platforms are removed. Also deletes any post actions (auto-retweet, etc.) for the unscheduled platforms. This cannot be undone, so it needs the user's explicit confirmation. Only SCHEDULED posts can be unscheduled; get_schedule shows the currently scheduled platforms. Passing every scheduled platform removes them all at once.
update_post
ChatGPTOverwrite an existing post's contents. get_post_content shows the current content for the user to confirm changes against. Updating applies to DRAFT and SCHEDULED posts; updating a PUBLISHED post does not re-publish it. Partial updates are safe: only the fields sent change. A field omitted on a content item is carried over from the existing post. This covers media_urls, post_type and every platform config (the youtube_ fields except youtube_title, tiktok_privacy_status, cover_url, graduation_strategy, share_to_feed, and the pinterest_ fields except pinterest_title). Updating text alone does not strip media or reset configs, and the whole post does not need re-sending. A config changes only when its new value is passed explicitly. media_urls=[] on a content item removes its media. YOUTUBE is the one exception: youtube_title is required, so an update keeps exactly one content item and includes contents[0].youtube_title on every call. contents[0].text is the video description and is left out unless a description is intended; contents[0].media_urls holds the uploaded video. post_type does not apply to YOUTUBE. PINTEREST works the same way: pinterest_title is required, so an update keeps exactly one content item and includes contents[0].pinterest_title on every call. contents[0].text (the Pin description), pinterest_board_id, pinterest_link and pinterest_alt_text are optional and carried over if omitted. post_type does not apply to PINTEREST. Tags: update_tags takes specs ({tag, color, account_id}), not tag_ids. A spec whose name already exists resolves to that tag rather than creating a duplicate, and postey://accounts/{account_id}/tags lists existing tags with their exact casing.
update_schedule
ChatGPTUpdate the scheduled time and/or platform set for a SCHEDULED post. Unscheduling a platform here keeps its Auto-DM rule. Once the scheduled time arrives, publication is irreversible and publicly visible, so a change needs the user's explicit confirmation. scheduled_at is a UTC timestamp at least 10 minutes in the future, measured from server now (retrieved_at on any response) and computed after the user confirms. A relative request ("now", "in 5 minutes") needs at least 15 minutes of margin; an absolute confirmed time is sent exactly as confirmed. A confirmed time that has passed is rejected rather than moved, and a replacement time is the user's choice. Platforms in the new list but not currently scheduled are added; platforms currently scheduled but absent from the new list are removed. platform_schedules must be non-empty; unschedule_post cancels all platforms. get_schedule shows the current state.
upload_media
ChatGPTUpload media (image, video, GIF, PDF) and return CDN URLs for contents[].media_urls in create_post / update_post. Media is uploaded before the post that references it is created. The returned cdn_url is the media URL, used exactly as returned. A media URL assembled from media_id, a filename or a path points at no stored object, and the post is created without its media. Source types: • 'url' — media already hosted at a public CDN URL (not a social-media page URL). Downloads server-side. Up to 250 MB. Works everywhere and is the best fit on the hosted server. Larger files go through the file_manager upload widget or PosteySkills. • 'base64' — small files (under 5 MB recommended, 20 MB decoded hard cap). Works everywhere. • 'local_path' — local CLI only. Uploads a file from the local machine via the PosteySkills CLI (chunked upload above 50 MB, per-platform validation). Requires PosteySkills installed locally (npx skills add posteyai/skills) and works with the credential already in use, OAuth or API key. Not available on the hosted server, which cannot see the local filesystem. When running locally with PosteySkills, local_path is the fastest option for on-disk files (any size, no encoding). Subject to plan storage quota. Media uploaded here cannot currently be deleted through this server; there is no delete tool on the MCP surface. list_files reads the file_manager widget's own index and does not show upload_media uploads, so the cdn_url this returns cannot be recovered there.
validate_post_content
ChatGPTDry-run content against a platform's hard limit, counting rules, threading requirements, banned words and media constraints. Returns warnings without mutating state. Useful before create_post / update_post for any non-trivial content. account_id is required for X/Twitter, where it resolves the premium character limit, and optional for every other platform. Issues come in two kinds, tagged in detailed_issues: hard_limit issues make the post unpublishable as written; style issues only make it read off-style. valid is false if either kind is present.