Skip to content

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.

  • 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.

  • Drafts only. create-post, update-post and create-post-from-template save 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-post and delete-post read the post first, and refuse anything but a draft or a post awaiting approval (post.not_draft) without changing it. update-post keeps every field it isn’t given, and a post awaiting approval stays awaiting.
  • Versions. update-post takes the version from get-post. If someone changed the post since, it is refused (post.changed): read it again, then make the change.
  • Pages. pageKey ties a draft to a page, and pageDelayMinutes (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 the cms-- tools, and get what a post about it needs with get-page-share.
  • Images. mediaKey is an Umbraco media item’s key, from the cms-- media tools.
  • Approvals. With Pro and approvals on, submit-post-for-approval sends the API user’s own draft to the approvers.

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.