Tools reference
This page lists every tool exposed by the Mixpost MCP server, grouped by area. For an overview of how to connect and authenticate, see the MCP Server overview.
Tools at a glance
| Tool | Type | What it does |
|---|---|---|
list-workspaces | Read | List accessible workspaces — call this first |
get-workspace | Read | Details and counts for one workspace |
list-accounts | Read | List connected social accounts |
get-account | Read | Full details for one account |
list-posts | Read | List and filter posts |
get-post | Read | Full details for one post |
create-post | Write | Create, and optionally schedule or publish, a post |
update-post | Write | Change a post's content, accounts or tags |
update-post-version | Write | Update a single content version of a post |
delete-post-version | Destructive | Remove an account's own content version |
attach-tags-to-post | Write | Add tags, keeping existing ones |
detach-tags-from-post | Write | Remove tags from a post |
duplicate-post | Write | Copy a post as a new draft |
schedule-post | Write | Schedule for a time, or publish now |
unschedule-post | Write | Clear the schedule and return the post to draft |
add-post-to-queue | Write | Queue at the next available slot |
delete-post | Destructive | Trash or permanently delete a post |
restore-post | Write | Restore a post from the trash |
list-tags | Read | List workspace tags |
get-tag | Read | Details for one tag |
create-tag | Write | Create a tag |
update-tag | Write | Update a tag's name or colour |
list-media | Read | List media library files |
get-media | Read | Full metadata for one file |
upload-media-by-url | Write | Add a file to the library from a URL |
get-media-upload-status | Read | Check a background upload's progress |
Common parameters
Two arguments appear across most tools:
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | UUID of the workspace to operate on. Obtain it from list-workspaces. Required by every tool except list-workspaces. |
timezone | string | optional | IANA timezone (e.g. America/New_York) used to interpret input dates and format dates in the response. Defaults to your account timezone, then to UTC. |
Write operations (create, update, schedule, delete, etc.) require the token owner to have the Member or Admin role in the workspace. See Roles and permissions.
Workspaces
list-workspaces
Read-only. List the workspaces the authenticated user can access, most recently updated first. Call this first — every other tool needs a workspace uuid.
Parameters: none.
Returns: count and a workspaces array of { uuid, name, role }.
get-workspace
Read-only. Get details about a single workspace: name, the user's role and approval rights, and the number of connected accounts, posts and members.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
timezone | string | optional | Timezone for returned datetimes. |
Returns: a workspace object — { uuid, name, created_at, role, can_approve, accounts_count, posts_count, users_count }.
Accounts
list-accounts
Read-only. List the social media accounts connected to a workspace. Returns each account's numeric id (used with create-post), name, username, provider and authorization status.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
provider | string | optional | Filter by provider identifier, e.g. twitter, facebook_page, linkedin. |
authorized_only | boolean | optional | When true, return only accounts whose authorization is still valid. |
Returns: count and an accounts array of { id, name, username, provider, authorized }.
get-account
Read-only. Get full details for a single connected account by its numeric id, including profile image, external profile URL and provider-specific data (e.g. follower metrics).
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
account_id | integer | required | Numeric id of the account. Obtain it from list-accounts. |
timezone | string | optional | Timezone for returned datetimes. |
Returns: an account object — { id, uuid, name, suffix, username, provider, provider_name, authorized, image, external_url, data, created_at }.
Posts
list-posts
Read-only. List posts in a workspace, most recent first, with optional filters. Returns a compact summary per post: uuid, status, schedule/publish/created times, accounts, tags, plain-text content and media count.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
status | string | optional | One of draft, scheduled, published, failed, needs_approval, trash. |
account_ids | array<integer> | optional | Only posts assigned to any of these account ids. |
tag_ids | array<integer> | optional | Only posts tagged with any of these tag ids. |
keyword | string | optional | Only posts whose content contains this text. |
scheduled_from | string | optional | Only posts scheduled at or after this UTC date/time. Format Y-m-d or Y-m-d H:i. |
scheduled_to | string | optional | Only posts scheduled at or before this UTC date/time. A date-only value includes the whole day. |
created_from | string | optional | Only posts created at or after this UTC date/time. |
created_to | string | optional | Only posts created at or before this UTC date/time. |
limit | integer | optional | Maximum number of posts to return (1–100). Defaults to 25. |
timezone | string | optional | Timezone for returned datetimes. |
Returns: count and a posts array of post summaries (see Post summary shape).
get-post
Read-only. Get the details of a single post by its uuid: status, schedule/publish times, author, tags, the accounts it targets (with live post URLs and any publish errors) and every content version with the text and the media ids of each item.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
uuid | string | required | UUID of the post. Obtain it from list-posts. |
include | array<string> | optional | Extra parts of each content version to return (see below). Omitted by default. |
timezone | string | optional | Timezone for returned datetimes. |
Returns: a post object with author, tags, per-account publish info (external_url, errors) and the versions array. Each version carries synced_with: 0 or an account id when it follows that version (and holds a copy of its content), null when its content is its own.
Asking for more with include
Everything a version carries beyond its text costs real tokens, and most calls need none of it — so it is left out unless you name it. By default each content item returns body plus media as plain media ids, which is exactly what the write tools take back.
| Value | Adds |
|---|---|
media | Expands each media id into { id, name, type, url, alt_text }. |
options | The per-provider options object of each version (see Versions). |
content_urls | The url attached to each content item. |
video_thumbs | The thumbnail chosen for each video: { media_id, thumb_id, thumb_url }. |
all | All of the above. Ask for this only when you genuinely need everything. |
{
"workspace": "6059e1b3-e102-4be5-951b-82698abd9ee3",
"uuid": "0f5b1c7a-2f4d-4d2e-9e2a-6f3f2d1c8b90",
"include": ["media", "options"]
}
create-post
Writes data. Create a post and optionally schedule or publish it. Provide simple content for a single-version post, or versions for per-account content.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
account_ids | array<integer> | required | Numeric IDs of the connected accounts to post to (at least one). Obtain them from list-accounts. |
content | string | optional | The text body, used as the default for every account. Required unless versions is given. |
schedule | string | optional | draft (default), now (publish immediately), scheduled (publish at scheduled_at), or queue (next slot). |
scheduled_at | string | optional | When to publish, format Y-m-d H:i (e.g. 2026-05-22 14:30). Required when schedule is scheduled. |
tags | array<integer> | optional | Numeric tag IDs to attach. Obtain them from list-tags. |
versions | array | optional | Per-account content versions (see Versions). |
timezone | string | optional | Timezone for scheduled_at and returned datetimes. |
Returns: a message, the created post summary, and the timezone used.
A post created to be published now, scheduled or queued must meet the publishing requirements of its accounts' platforms; otherwise the tool returns an error listing what to fix and creates nothing. A draft is not checked.
update-post
Writes data. Update an existing post's content (content or versions), target accounts and/or tags. Only the fields you provide change, and the schedule is left untouched — use schedule-post for timing, or unschedule-post to clear it. The post must not already be published, failed or publishing.
Each part is saved through the same endpoint the editor uses, so a post an agent updates goes through the same validation, per-provider option handling and events as one updated in the dashboard.
A scheduled post must still meet the publishing requirements of its accounts' platforms once the change is applied — the new content checked against the new accounts, when both change. Otherwise the tool returns an error listing what to fix and changes nothing; fix it in the same call, or unschedule-post first. A draft is not checked.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
uuid | string | required | UUID of the post. Obtain it from list-posts. |
content | string | optional | New text body. Replaces the body of the post's original content. |
account_ids | array<integer> | optional | Replace the targeted accounts with these account ids (at least one). |
tags | array<integer> | optional | Replace the post's tags. Pass an empty array to remove all tags. |
versions | array | optional | Versions to create or update (see Versions). Versions you leave out keep what they had — remove one with delete-post-version. |
timezone | string | optional | Timezone for returned datetimes. |
Returns: a message, the updated post summary, and the timezone used.
update-post-version
Writes data. Update a single content version of a post, leaving the others untouched. Target the original/default version with account_id 0, or an account id to update (or create) that account's version. To replace every version at once, use update-post.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
uuid | string | required | UUID of the post. Obtain it from list-posts. |
account_id | integer | required | 0 for the original/default version, or a connected account id for that account's version. |
content | array | required | Ordered content items for this version (at least one); more than one publishes a thread. |
options | object | optional | Per-provider post options, keyed by provider identifier (e.g. { "mastodon": { … } }). |
timezone | string | optional | Timezone for returned datetimes. |
Each item in content has body (string), media (array of media ids) and url (string), all optional. Leave media out to keep the media the item already has; pass an empty array to clear it. Video thumbnails are always preserved — they are not part of the tool's input.
options are validated against the target provider's rules and normalised the way the dashboard normalises them; options for an unknown provider are dropped. Leave options out to keep the ones the version already has.
On a scheduled post, the version must leave the post meeting the publishing requirements of its accounts' platforms; otherwise the tool returns an error listing what to fix and changes nothing.
A version that follows another (its synced_with in get-post is not null) stops following it once this tool writes its content.
Returns: a message, the updated post summary, and the timezone used.
delete-post-version
Destructive. Remove an account's own content version from a post, so that account falls back to the post's default content. The default version itself has no account and cannot be removed this way. The post must not already be published, failed or publishing.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
uuid | string | required | UUID of the post. Obtain it from list-posts. |
account_id | integer | required | The connected account whose own version is removed. Obtain it from list-accounts. |
Use get-post to see which accounts have a version of their own — each entry in versions carries the account_id it belongs to.
On a scheduled post, the default content the account falls back to must meet the publishing requirements of that account's platform; otherwise the tool returns an error listing what to fix and removes nothing.
Returns: a message, the post uuid and the account_id that was reverted. The post itself is not returned — the only version a post summary carries is the default one, which this call leaves alone.
attach-tags-to-post
Writes data. Attach one or more tags to a post, keeping any tags it already has. To replace a post's tags instead, use update-post.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
uuid | string | required | UUID of the post. Obtain it from list-posts. |
tag_ids | array<integer> | required | Tag ids to attach (at least one), kept in addition to existing tags. |
timezone | string | optional | Timezone for returned datetimes. |
Returns: a message and the updated post summary.
detach-tags-from-post
Writes data. Remove one or more tags from a post, leaving its other tags in place.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
uuid | string | required | UUID of the post. Obtain it from list-posts. |
tag_ids | array<integer> | required | Tag ids to remove (at least one). |
timezone | string | optional | Timezone for returned datetimes. |
Returns: a message and the updated post summary.
duplicate-post
Writes data. Duplicate an existing post. Creates a new draft copy with the same accounts, tags and content versions; the copy is never scheduled or published.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
uuid | string | required | UUID of the post to duplicate. |
timezone | string | optional | Timezone for returned datetimes. |
Returns: a message and the new draft post summary.
schedule-post
Writes data. Schedule an existing post for a specific date/time, or publish it immediately with post_now. The post must have at least one account, a future scheduled time, content the platform of every account can publish, and must not already be published, failed or publishing.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
uuid | string | required | UUID of the post. Obtain it from list-posts. |
scheduled_at | string | optional | When to publish, format Y-m-d H:i. Required unless post_now is true or the post already has a scheduled time. |
post_now | boolean | optional | When true, publish immediately instead of scheduling. |
timezone | string | optional | Timezone for scheduled_at and returned datetimes. |
Returns: a message and the updated post summary. If the workspace requires approval, the post becomes needs_approval; otherwise it is queued for publishing.
The post must also meet the publishing requirements of its accounts' platforms — media for an Instagram post, a board for Pinterest, a title for YouTube. Otherwise the tool returns an error listing what to fix, and the post stays as it was.
unschedule-post
Writes data. Clear a post's scheduled time and take it back to draft, so it stays put until it is scheduled again. Its accounts, tags and content are untouched. Works on a scheduled post, one waiting in the queue and one awaiting approval; a post that has already been published or failed, or one being published right now, cannot be unscheduled.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
uuid | string | required | UUID of the post. Obtain it from list-posts. |
Returns: a message and the post uuid. The post itself is not returned — nothing but the schedule changed.
Use schedule-post to put it back on the calendar, or add-post-to-queue to send it to the next free slot.
add-post-to-queue
Writes data. Add an existing post to the posting queue — it is scheduled at the next available slot of the workspace's posting schedule. The post must have at least one account, content the platform of every account can publish, and must not already be published, failed or publishing.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
uuid | string | required | UUID of the post. Obtain it from list-posts. |
timezone | string | optional | Timezone for returned datetimes. |
Returns: a message and the updated post summary. The workspace must have posting schedule times configured.
The post must also meet the publishing requirements of its accounts' platforms; otherwise the tool returns an error listing what to fix, and the post stays as it was.
delete-post
Destructive. Delete a post. By default it is moved to the trash and can be restored; set permanent to true to delete it irreversibly. Use delete_mode to also remove the published post from the connected social platforms.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
uuid | string | required | UUID of the post. Obtain it from list-posts. |
delete_mode | string | optional | app_only (default), social_only, or app_and_social. |
permanent | boolean | optional | When true, permanently delete instead of moving to trash. Only applies when removing from Mixpost. Defaults to false. |
Returns: a message and the deleted post's uuid.
restore-post
Writes data. Restore a post from the trash. The post is recovered as a draft. Only posts moved to the trash (not permanently deleted) can be restored. Find them with list-posts using status: "trash".
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
uuid | string | required | UUID of the trashed post. |
timezone | string | optional | Timezone for returned datetimes. |
Returns: a message and the restored post summary.
Tags
list-tags
Read-only. List the tags defined in a workspace.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
Returns: count and a tags array of { id, name, hex_color }.
get-tag
Read-only. Get details for a single tag by its numeric id.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
tag_id | integer | required | Numeric id of the tag. From list-tags. |
Returns: a tag object — { id, name, hex_color }.
create-tag
Writes data. Create a tag in a workspace.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
name | string | required | The tag name (max 255 characters). |
hex_color | string | required | The tag colour as a hex code, e.g. #1d9bf0. |
Returns: a message and the created tag.
update-tag
Writes data. Update a tag's name and/or colour. Only the fields you provide change.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
tag_id | integer | required | Numeric id of the tag. From list-tags. |
name | string | optional | New tag name (max 255 characters). |
hex_color | string | optional | New tag colour as a hex code, e.g. #1d9bf0. |
Returns: a message and the updated tag.
Media
list-media
Read-only. List the media files (images, GIFs and videos) in a workspace's library, newest first. Returns each file's numeric id (which can be attached to a post version), name, type and URL.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
type | string | optional | Filter by image, gif, or video. |
limit | integer | optional | Maximum number of files to return (1–100). Defaults to 50. |
timezone | string | optional | Timezone for returned datetimes. |
Returns: count and a media array of summaries — { id, uuid, name, type, mime_type, url, alt_text, created_at }.
get-media
Read-only. Get the full metadata for a single media file by its uuid.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
uuid | string | required | UUID of the media file. From list-media. |
timezone | string | optional | Timezone for returned datetimes. |
Returns: a media object — { id, uuid, name, type, mime_type, url, thumb_url, alt_text, source, … }.
upload-media-by-url
Writes data. Upload a media file to the library by downloading it from a public URL. Small files are downloaded immediately and returned; large files download in the background and appear in list-media once complete.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
url | string | required | Publicly accessible URL of the media file to download. |
alt_text | string | optional | Alternative text describing the media (max 255 characters). |
timezone | string | optional | Timezone for returned datetimes. |
Returns: for a small file, a message and the uploaded media. For a large file, a message, status: "pending" and a download_id — poll it with get-media-upload-status.
get-media-upload-status
Read-only. Check the progress of a background media download started by upload-media-by-url.
| Key | Format | Required | Description |
|---|---|---|---|
workspace | string | required | Workspace UUID. |
download_id | string | required | The download_id returned by upload-media-by-url for a large file. |
timezone | string | optional | Timezone for returned datetimes. |
Returns: while in progress, a status (pending, downloading, processing) and a progress percentage; on completion, status: "completed" and the uploaded media; on failure, an error message.
Provider identifiers
The provider value on an account — and the provider filter on list-accounts — uses these identifiers:
| Identifier | Platform |
|---|---|
twitter | X (Twitter) |
facebook_page | Facebook Page |
instagram | Instagram (via a Facebook Page) |
instagram_standalone | Instagram (standalone) |
threads | Threads |
linkedin | LinkedIn (profile) |
linkedin_page | LinkedIn Page |
tiktok | TikTok |
pinterest | |
youtube | YouTube |
gbp | Google Business Profile |
mastodon | Mastodon |
bluesky | Bluesky |
pixelfed | Pixelfed |
Versions
The create-post, update-post and update-post-version tools support per-account content versions, so a single post can have different text or media for each network. The structure mirrors the REST API's post versions:
{
"versions": [
{
"account_id": 0,
"content": [
{
"body": "This is the default content used for every account.",
"media": [1],
"url": null
}
],
"options": {
"mastodon": { "sensitive": false }
}
},
{
"account_id": 12,
"content": [
{ "body": "A custom version just for this account." }
]
}
]
}
| Key | Format | Required | Description |
|---|---|---|---|
versions.*.account_id | integer | required | The account this version targets. Use 0 for the original/default version. |
versions.*.content | array | required | Ordered content items. Provide more than one to publish a thread. |
versions.*.content.*.body | string | optional | The text body of this content item. |
versions.*.content.*.media | array<integer> | optional | Media IDs to attach. Obtain them from list-media or upload-media-by-url. |
versions.*.content.*.url | string | optional | A URL associated with the content (supported by Facebook and LinkedIn). |
versions.*.options | object | optional | Options available for each social service provider. Only keys matching a registered provider are kept — unknown keys are silently dropped, and rules are applied only for the provider keys you actually send.
|
The version with account_id 0 is the default content, applied to every account that does not have its own account-specific version.
- With
create-post, exactly one version must haveaccount_id0— the post has no content yet. - With
update-post, the versions you send are created or updated and the rest are left alone, so0only has to be included if the post does not already have a default version.
A content item you send replaces the stored one, but the keys you omit are carried over from it: leave media or url out and the item keeps them, and video thumbnails are always preserved since they are not part of the tools' input. Pass an empty media array to actually clear the media.
Removing an account's version is a separate call — delete-post-version — never something that happens because you left it out of versions.
Post summary shape
Most post tools return a compact summary optimised for agents (the heavy web payload is omitted to save tokens):
{
"uuid": "6059e1b3-e102-4be5-951b-82698abd9ee3",
"status": "scheduled",
"scheduled_at": "2026-07-01 09:00:00",
"published_at": null,
"created_at": "2026-06-25 14:12:03",
"accounts": [
{ "id": 12, "name": "Acme", "username": "acme", "provider": "twitter", "authorized": true }
],
"tags": [
{ "id": 3, "name": "Launch" }
],
"content": "We just shipped a big update 🚀",
"media_count": 1
}
status is one of draft, scheduled, published, failed, needs_approval, publishing or trash. content is the plain text of the post's original version, with multiple content items joined by blank lines.