MCP Tools
These are the tools the UmbSocial MCP server can register. An assistant sees only the ones the API user may use: see Which tools are registered.
Reading the table
Section titled “Reading the table”- Needs: the UmbSocial permissions that can use the tool. Any one of them is enough. “UmbSocial section” means the section alone. Permissions explains each permission.
- Slice: what the tool does, for the filters. A slice marked (off) is off by default.
- Edition: Pro tools are registered only when the site’s UmbSocial Pro licence is valid.
- Hints: read-only tools change nothing; a destructive tool can’t be undone. The assistant’s client may use them to decide when to ask you first.
- Inputs: what the assistant sends. An input ending in
?is optional.
The table is generated from the server’s own tool definitions, so it matches the release it describes.
| Tool | What it does | Needs | Slice | Edition | Hints | Inputs |
|---|---|---|---|---|---|---|
get-social-edition |
Gets the site’s UmbSocial edition (whether Pro is licensed, the channel allowance and the history kept) and the UmbSocial permissions this API user has, so you know what you may try. | UmbSocial section | read | Any | read-only | none |
list-channels |
Lists the site’s UmbSocial channels (one per connected network account): each channel’s key, name, network, whether it is enabled or paused, and the main limits a post must keep to there (characters, alt text, an image, thread parts, a first comment). | View, Write or Manage settings | list | Any | read-only | none |
get-channel |
Gets one UmbSocial channel with every limit its network sets: characters (and how links and wide characters count), image size and whether one is needed, alt text, link handling, thread parts, a first comment, a content warning, a title and calls to action. | View, Write or Manage settings | read | Any | read-only | channelKey |
list-posts |
Lists Social posts in a window of time, each with its key, status, origin (Manual, Ai or Automation), when it goes or went out, when it was last changed, its first 200 characters, its channels and its campaign. | View or Write | list | Any | read-only | fromUtc?, toUtc?, status?, channelKey?, campaignKey?, pageKey?, pageCulture?, tagKey?, newestFirst?, limit? |
get-post |
Gets one Social post in full: its text, link, image, campaign, page, status, origin (Manual, Ai or Automation), version (send it back with any change), and each channel’s target with its id, status, text override, options, the live post’s postUrl and any error. |
View or Write | read | Any | read-only | key |
get-post-history |
Gets a Social post’s history: each change, review, schedule and send, with when it happened, who did it (isSystem for the site itself) and any comment. |
View or Write | read | Any | read-only | key, cursor? |
get-post-metrics |
Gets the views and interactions of up to 200 posts, for each channel a post was published to, as the networks last reported them (fetchedUtc). |
View or Write | read | Any | read-only | postKeys |
get-schedule |
Gets the site’s posting schedule: the weekly slots (a day and a local time) that queued posts go out in, and the time zone those times are in. | View, Write or Manage settings | read | Any | read-only | none |
list-free-slots |
Lists every slot of the posting schedule from one time to another (at most 42 days), in UTC, and whether a post already takes it. | View, Write or Manage settings | read | Any | read-only | fromUtc, toUtc |
get-next-free-slot |
Gets the next slot of the posting schedule that no post takes, in UTC: where a queued post would go next. | View, Write or Manage settings | read | Any | read-only | none |
list-campaigns |
Lists the UmbSocial campaigns a post can belong to, with each one’s key, name and value (the utm_campaign it adds to links). | Write or Manage settings | list | Any | read-only | query?, cursor? |
get-page-share |
Gets what a post about an Umbraco page needs: the page’s name, address, description, image (mediaKey, only if this user may pick it), its campaign, its languages, and whether it is live, with its planned release if it isn’t yet. |
Write | read | Any | read-only | documentKey, culture? |
check-post |
Checks a Social post against each of its channels without saving it: each channel’s character count against its limit, the text as the network will show it, errors and warnings, and errors for the post as a whole. | Write | read | Any | read-only | key?, text, channelKeys, channelTexts?, options?, linkUrl?, linkTitle?, linkDescription?, linkImageUrl?, mediaKey?, imageAltText?, campaignKey?, pageKey?, pageCulture?, pageDelayMinutes? |
create-post |
Creates a Social post and saves it as a draft, for one or more channels, with an optional link, image, campaign and per-channel text and extras. | Write | create | Any | – | text, channelKeys, channelTexts?, options?, linkUrl?, linkTitle?, linkDescription?, linkImageUrl?, mediaKey?, imageAltText?, campaignKey?, pageKey?, pageCulture?, pageDelayMinutes? |
update-post |
Changes an UmbSocial draft, or a post awaiting approval: it reads the post, keeps every field it isn’t given, and saves it as a draft again (a post awaiting approval stays awaiting). | Write | update | Any | – | key, version, text?, channelKeys?, channelTexts?, options?, linkUrl?, linkTitle?, linkDescription?, linkImageUrl?, mediaKey?, imageAltText?, campaignKey?, pageKey?, pageCulture?, pageDelayMinutes? |
delete-post |
Deletes an UmbSocial draft, or a post awaiting approval, for good. | Write | delete | Any | destructive | key, confirm? |
create-campaign |
Creates an UmbSocial campaign to group posts under, or returns the existing one with that name. | Write | create | Any | – | name |
preview-link |
Reads a web page’s link card: its title, description and image, as the site fetches them. | Write | read | Any | read-only | url |
retry-post-target |
Sends a Failed or Unknown channel of a post again, so it goes to the live network once more. | Resolve | resolve (off) | Any | destructive | targetId, confirm? |
mark-post-target-published |
Records that a Failed or Unknown channel of a post is in fact live on its network, because a person has seen it there. | Resolve | resolve (off) | Any | destructive | targetId, postUrl?, confirm? |
submit-post-for-approval |
Submits an UmbSocial draft for approval, so that a person with the Approve permission can review it and put it on the calendar. | Write | update | Pro | – | key |
approve-post |
Approves a Social post awaiting approval and puts it on the calendar: Queue, At, Now or OnPagePublish. | Approve | approve (off) | Pro | destructive | key, expectedVersion, when, atUtc?, pageDelayMinutes?, confirm? |
return-post |
Returns a Social post awaiting approval to its writer as a draft, with a note saying what to change. | Approve | approve (off) | Pro | – | key, expectedVersion, note |
list-templates |
Lists the Social post templates by name, each with its key, the first 200 characters of its text, its link, campaign and channels, whether AI wrote it (fromAi) and the document types it is for. |
Write | list | Pro | read-only | filter?, documentTypeKey?, cursor? |
get-template |
Gets a Social post template: its name, full text, link, campaign, channels, whether AI wrote it (fromAi) and the document types it is for. |
Write | read | Pro | read-only | templateKey |
create-post-from-template |
Creates an UmbSocial draft from a post template: the site copies the template’s text, link, campaign and channels and, with pageKey, ties the post to that page. | Write | create | Pro | – | templateKey, pageKey?, pageCulture? |
list-tags |
Lists the Social post tags by name, each with its key, colour and how many posts have it. | View, Write or Manage settings | list | Pro | read-only | filter?, cursor? |
get-tag |
Gets a Social post tag: its name, colour, how many posts have it and when it last changed. | View, Write or Manage settings | read | Pro | read-only | tagKey |
get-post-tags |
Gets the tags of up to 200 Social posts, each with its key, name and colour. | View or Write | read | Pro | read-only | postKeys |
set-post-tags |
Replaces a Social post’s tags with the ones given: any tag not in the list is taken off. | Write | update | Pro | – | key, tagKeys |
list-hashtags |
Lists the saved UmbSocial hashtag groups by name, each with its key, its hashtags and how often it has been used. | Write or Manage settings | list | Pro | read-only | filter?, cursor? |
get-hashtag-group |
Gets a saved UmbSocial hashtag group: its name, its hashtags and how often it has been used. | Write or Manage settings | read | Pro | read-only | hashtagGroupKey |
get-post-utm |
Gets a Social post’s own UTM values (source, medium, content) and whether its links go out without UTM tags (disabled). |
Write | read | Pro | read-only | key |
set-post-utm |
Changes a Social post’s own UTM values: it reads them, keeps every field it isn’t given, and saves them. | Write | update | Pro | – | key, source?, medium?, content?, disabled? |
get-post-short-links |
Gets a Social post’s short links: for each channel, the short address, where it leads (an address, or a page by its document key) and how many times it was clicked. | View | read | Pro | read-only | key |
get-short-link-clicks |
Gets how many times the short links of up to 200 posts were clicked, in total and per channel (by channel key). | View or Write | read | Pro | read-only | postKeys |
list-short-links |
Lists the site’s UmbSocial short links, newest first, each with its short address, where it leads (targetGone when the page has gone), its post and channel, and its clicks. |
Manage settings | list | Pro | read-only | filter?, cursor? |
get-metrics-trend |
Gets how a published channel’s views and interactions changed over time: each reading the site took, oldest first, at most the latest 500. | View or Write | read | Pro | read-only | targetId |
Besides these, the chained CMS server adds eight read-only cms-- tools that find images and pages.
Writing posts
Section titled “Writing posts”- Drafts only.
create-post,update-postandcreate-post-from-templatesave drafts. Every post they write is marked as written with AI, so a person reviews it before it goes on the calendar. - Only drafts change.
update-postanddelete-postread the post first, and refuse anything but a draft or a post awaiting approval (post.not_draft) without changing it.update-postkeeps every field it isn’t given, and a post awaiting approval stays awaiting. - Versions.
update-posttakes theversionfromget-post. If someone changed the post since, it is refused (post.changed): read it again, then make the change. - Pages.
pageKeyties a draft to a page, andpageDelayMinutes(0, 60 or 1440) keeps how long after the page goes live it should go out. A person then chooses When the page goes live (Posting from pages). Find the page with thecms--tools, and get what a post about it needs withget-page-share. - Images.
mediaKeyis an Umbraco media item’s key, from thecms--media tools. - Approvals. With Pro and approvals on,
submit-post-for-approvalsends the API user’s own draft to the approvers.
When a tool is refused
Section titled “When a tool is refused”A refused call comes back to the assistant as an error with the site’s codes, the HTTP status and, for most codes, a hint saying what to do next:
{ "codes": ["ai.needs_review"], "status": 403, "hint": "A person must review this post in the Umbraco backoffice before it can be scheduled. Leave it as a draft, or submit it for approval if the site uses approvals." }The codes are UmbSocial’s own (Error codes). The hints, and the few codes the server adds itself, are listed under The MCP server.