MCP Tools Reference

Every tool the SociaHive MCP server exposes — parameters, required API-key scopes, feature flags, and confirmation requirements.

The SociaHive MCP server advertises 89 tools (38 read, 47 write, 4 destructive). Every one runs through the same chokepoint the in-app copilot uses, so auth, tier limits, rate limits, credits, and audit logging apply identically whether the caller is Claude Desktop, the CLI, or the dashboard.

Connect a client first — see the setup guide.

tools/list reports 91 rather than 89: it also carries __cache_anchor (an internal prompt-cache sentinel — ignore it) and get_more_tools (injected by the analytics layer so an assistant can report a capability it wishes existed; it returns a plain-text acknowledgement, not JSON).

How access is decided

A tool call has to clear four gates, in order:

API key + agent:execute — enforced at /api/mcp before the server is reached.
Per-tool scopes — the "Required scopes" column below. A key with * clears all of them.
Feature flag — tools in the "Notes" column with a flag: entry are inert unless that flag is on for your account. Most follow your plan; a few are still admin-only previews.
Confirmation — tools marked confirm are irreversible. The first call returns a pending_confirmation envelope with a token; call again passing __confirmToken. Keyed surfaces (CLI, SDK) can instead pass confirm: true where the tool accepts it.

Tools marked not on connect keys need a scope the one-click Connect to AI key doesn't carry. Mint a key with the scopes you need in Settings → API Keys.

Tools

Session & capability

Tool	What it does	Parameters	Required scopes	Notes
`whoami`	Returns the calling user's identity, tier, surface, and currently selected connected account.	—	— (no scope)	—
`list_capabilities`	Returns the list of tools available to this user (filtered by tier + flags).	—	— (no scope)	—
`current_page_context`	Returns what the user is looking at — route, entity type/id/name, selection.	—	— (no scope)	—

Flows — read

Tool	What it does	Parameters	Required scopes	Notes
`list_flows`	List the user's automation flows — for BROWSING many.	`status`, `limit`, `sortBy`, `sortOrder`, `cursor`	`flows:read`	—
`list_flows_with_stats`	Rank flows by a performance metric — triggers, completions, unique_users, or button_clicks.	`metric`, `sortOrder`, `limit`, `status`	`flows:read`	—
`get_flow`	Fetch one flow by id.	`flowId`, `nodeId`	`flows:read`	—
`summarize_flow_purpose`	One-sentence flow summary.	`flowId`	`flows:read`	—
`get_flow_stats`	Fetch execution analytics for one flow — total triggers, button clicks, unique users, status breakdown, last 7 days daily timeline.	`flowId`	`flows:read`	—
`get_collected_data`	Summarize the data collected by a flow — total count, breakdown by field type, last N submissions (metadata only — actual values are not exposed to the LLM for privacy).	`flowId`, `fieldType`, `limit`	`flows:read`	—
`list_system_templates`	Browse pre-built system flow templates — common automations like welcome messages, lead generation, and customer support.	`category`, `limit`, `cursor`	`flows:read`	—
`get_flow_revisions`	List the version history of a flow.	`flowId`, `limit`	`flows:read`	—
`search_flows`	Disambiguate a FLOW referred to by name when several could match.	`query`, `limit`, `accountId`	`flows:read`	pass `accountId` on multi-account keys
`find_references`	Flows referencing a tag.	`entityType`, `entityId`, `limit`	`flows:read` `tags:read`	not on connect keys

Flows — write

Tool	What it does	Parameters	Required scopes	Notes
`activate_flow`	Publish (activate) a flow so it processes triggers in production.	`flowId`, `flowName`	`flows:write`	—
`deactivate_flow`	Unpublish (deactivate) a flow so it stops processing triggers.	`flowId`, `flowName`	`flows:write`	—
`duplicate_flow`	Copy an existing flow as a new draft.	`flowId`, `flowName`, `newName`	`flows:write`	—
`update_flow`	Rename a flow or change its description; saved and shown in SociaHive.	—	`flows:write`	—
`create_flow`	Create a new empty automation flow as a draft.	`name`, `description`, `accountId`, `platformUserId`, `platform`, `trigger`	`flows:write`	—
`[email protected]`	DEPRECATED — use [email protected] (inline streaming in chat).	`description`, `accountId`, `platformUserId`, `platform`	`flows:write`	flag: `AI_FLOW_BUILDER`, deprecated
`generate_flow`	Generate a complete automation flow from a natural-language description.	`description`, `platform`, `variants`, `iterateOnFlowId`, `businessContext`, `accountId`	`flows:write`	flag: `AI_FLOW_BUILDER`
`add_node`	Add a node to a flow's graph.	`flowId`, `type`, `position`, `name`, `data`	`flows:write`	—
`update_node`	Change one existing node — every in-flow content edit.	—	`flows:write`	—
`add_edge`	Connect two nodes in a flow with an edge.	`flowId`, `source`, `target`, `sourceHandle`, `targetHandle`, `type`, `data`	`flows:write`	—
`delete_node`	Remove a single node from a flow.	`flowId`, `nodeId`	`flows:write`	—
`delete_edge`	Remove a single edge (connection) from a flow.	`flowId`, `edgeId`	`flows:write`	—
`bulk_update_flows`	Batch-edit up to 50 flows in ONE call — every PLURAL flow edit ("rename the holiday flows").	`flowIds`, `filter`, `patch`	`flows:write`	—
`revert_flow_to_version`	Revert a flow to a previous version.	`flowId`, `targetVersion`	`flows:write`	—
`create_automation`	Draft an automation from a natural-language outcome.	`outcome`, `accountId`	`flows:write`	flag: `OUTCOME_API_TOOLS`
`generate_multiple_flows`	Bulk-build automations from ONE whole-setup description (migration: "rebuild my ManyChat setup").	`description`, `accountId`	`flows:write`	confirm, flag: `AI_BULK_FLOW_GENERATION`

Posts & scheduler — read

Tool	What it does	Parameters	Required scopes	Notes
`list_scheduled_posts`	List posts from the SociaHive Content Scheduler — drafts, queued, recurring, published-via-scheduler.	`status`, `platform`, `limit`, `sortOrder`, `cursor`	`posts:read`	—
`get_scheduled_post`	Fetch one scheduler-side post by id (drafts / queued / recurring / scheduler-published).	`postId`	`posts:read`	—
`get_scheduler_calendar`	Get scheduler-side posts in a date range.	`fromDate`, `toDate`, `platform`	`posts:read`	—
`list_pinterest_boards`	List the boards of your Pinterest accounts, for a Pin's `metadata.boardId`. MCP and API keys only.	`accountId`	`posts:read`	—
`get_post_analytics`	Fetch per-platform analytics for one published post — impressions, reach, engagement, likes, comments, shares, saves, clicks.	`postId`	`posts:read`	—
`get_analytics_overview`	Fetch aggregate analytics across all published posts — total impressions, total engagement, post count, per-platform breakdown, and the last 30 days timeline.	`startDate`, `endDate`, `platform`	`posts:read`	—
`list_evergreen`	List the user's evergreen queue (recyclable posts that fill failed Autopilot slots).	—	`posts:read`	flag: `SCHEDULER_EVERGREEN`

Posts & scheduler — write

Tool	What it does	Parameters	Required scopes	Notes
`schedule_post`	Put an EXISTING draft on the publishing calendar.	`postId`, `postName`, `scheduledAt`, `timezone`, `attach_automation`, `attach_funnel`	`posts:write`	—
`update_scheduled_post`	Edit a scheduler-side post that ALREADY EXISTS (draft or scheduled) — text, media (replaces all), time, timezone.	—	`posts:write`	—
`cancel_scheduled_post`	Cancel a scheduled post — reverts to draft so it won't publish.	`postId`, `postName`	`posts:write`	—
`publish_post_now`	Publish a post immediately to all configured platforms.	`postId`, `postName`	`posts:write`	confirm
`create_scheduled_post`	Create a NEW social post from supplied content — draft, optionally scheduled in the same call.	`text`, `media`, `platforms`, `scheduledAt`, `timezone`, `signatureId`, `nextSlot`	`posts:write`	—
`bulk_reschedule_posts`	Move up to 50 scheduled posts to a new publish time in one call.	`postIds`, `scheduledAt`, `timezone`	`posts:write`	—
`publish`	Publish a prepared post (by postId) to its platforms NOW.	`postId`, `platforms`	`posts:write`	confirm, flag: `OUTCOME_API_TOOLS`
`add_to_evergreen`	Add a recyclable post (caption text) to the user's evergreen queue.	`text`, `sourcePostId`	`posts:write`	flag: `SCHEDULER_EVERGREEN`

Accounts & media

Tool	What it does	Parameters	Required scopes	Notes
`list_accounts`	List the user's connected social media accounts (Instagram, Facebook, etc.).	`platform`, `status`	`accounts:read`	—
`list_published_media`	List recent media on the user's connected platform (Instagram first), recency-sorted.	`mediaType`, `limit`, `accountId`	`accounts:read`	pass `accountId` on multi-account keys
`get_latest_published_media`	Resolve the user's SINGLE most recent item published ON THE PLATFORM — singular intents pointing at the live account ("my latest reel", "our last post on Instagram"), or targeting a published post for a flow trigger.	`mediaType`, `accountId`	`accounts:read`	pass `accountId` on multi-account keys
`get_published_media`	Fetch a single platform-published media item by its `mediaId` (the platform's own ID, e.g.	`mediaId`, `accountId`	`accounts:read`	pass `accountId` on multi-account keys
`search_published_media`	Semantic search across captions of media published on the connected platform (Instagram first).	`query`, `mediaType`, `limit`, `accountId`	`accounts:read`	pass `accountId` on multi-account keys
`get_capabilities`	List what each connected account can DO — automation (DM/comment triggers) vs scheduler (post scheduling).	`accountId`	`accounts:read`	—
`resolve`	Auto-resolve a support conversation (by sessionId) from the knowledge base.	`sessionId`, `message`	`accounts:write`	flag: `OUTCOME_API_TOOLS`, not on connect keys
`capture_lead`	Capture a lead: find-or-create a contact from (platform, platformUserId) and record a lead-outcome.	`platform`, `platformUserId`, `source`, `username`, `displayName`	`accounts:write`	flag: `OUTCOME_API_TOOLS`, not on connect keys

Autopilot

Tool	What it does	Parameters	Required scopes	Notes
`get_autopilot_status`	Use ONLY to report Autopilot's state: is it on, review mode (approve vs autopublish), posts/week, target-account count, pause reason, and this week's batch summary (planned/ready counts, status).	—	`autopilot:read`	flag: `AI_COPILOT_AUTOPILOT_TOOLS`
`update_autopilot_brand_kit`	Set/update the Brand Kit grounding Autopilot's content (business name, what-you-do, audience, voice preset, banned words, pillars).	`businessName`, `whatYouDo`, `audience`, `voice`, `voiceNote`, `bannedWords`, `pillars`	`autopilot:write`	flag: `AI_COPILOT_AUTOPILOT_TOOLS`
`generate_autopilot_week`	Use when the user asks to generate/create/make/plan this week's content ("generate my week").	`feedback`	`autopilot:write`	flag: `AI_COPILOT_AUTOPILOT_TOOLS`
`adjust_autopilot_week`	Use when the user asks to change/adjust/revise the current week with feedback ("make it more casual", "fewer promos") OR to regenerate it from scratch (omit feedback).	`feedback`, `batchId`	`autopilot:write`	flag: `AI_COPILOT_AUTOPILOT_TOOLS`
`approve_autopilot_week`	Use when the user asks to approve/ship/publish the week ("approve the week", "ship it").	`batchId`, `confirm`	`autopilot:write`	confirm, flag: `AI_COPILOT_AUTOPILOT_TOOLS`
`turn_on_autopilot`	Use when the user asks to set up/turn on/enable/start Autopilot ("set up autopilot", "turn on autopilot").	`postsPerWeek`, `reviewMode`, `accountIds`, `confirm`	`autopilot:write`	confirm, flag: `AI_COPILOT_AUTOPILOT_TOOLS`

Content insights

Tool	What it does	Parameters	Required scopes	Notes
`get_content_insights`	Get this account's content performance insights: which formats, days of week, and content pillars index above/below the account's average engagement (with sample sizes), plus top/bottom posts.	`weeks`	`analytics:read`	flag: `SCHEDULER_LEARNING_LOOP`

Tool	What it does	Parameters	Required scopes	Notes
`search_tags`	Resolve tag reference ("tagged X").	`query`, `limit`	`tags:read`	not on connect keys
`create_tag`	Create a tag.	`name`, `color`	`tags:write`	not on connect keys

CRM & growth

Tool	What it does	Parameters	Required scopes	Notes
`create_broadcast`	Call DIRECTLY on any broadcast/announcement ask — no whoami or context lookup first.	`name`, `channel`, `message`, `audience`	`broadcasts:write`	confirm, flag: `AI_MAIN_FEATURE_TOOLS`, not on connect keys
`create_sequence`	Create a drip sequence as a DRAFT.	`name`, `description`, `steps`	`sequences:write`	confirm, flag: `AI_MAIN_FEATURE_TOOLS`, not on connect keys
`create_landing_page`	Create a hosted lead-capture landing page as a DRAFT (disabled — not publicly live until the human enables it).	`name`, `headline`, `body`, `button_text`, `slug`	`growth_tools:write`	confirm, flag: `AI_MAIN_FEATURE_TOOLS`, not on connect keys
`create_growth_widget`	Create a website growth widget (popup / slide-in / bar / embed box) as a disabled DRAFT — not live until the human enables it in Growth Tools.	`name`, `widget_type`, `headline`, `body`, `button_text`	`growth_tools:write`	confirm, flag: `AI_MAIN_FEATURE_TOOLS`, not on connect keys
`create_ref_url`	Create a shareable tracked ref link (Growth Tools) — per-link click counting; the primitive behind referral/invite links and link-in-bio tracking.	`name`, `flow_id`, `platform`	`growth_tools:write`	flag: `AI_MAIN_FEATURE_TOOLS`, not on connect keys
`get_pixel_embed`	Get the user's SociaHive Pixel install snippet + instructions.	—	`analytics:read`	flag: `AI_MAIN_FEATURE_TOOLS`

Destructive

Tool	What it does	Parameters	Required scopes	Notes
`delete_flow`	Soft-archive a flow (status='archived').	`flowId`, `flowName`	`flows:write` `agent:destructive`	confirm, flag: `AI_COPILOT_DESTRUCTIVE_TOOLS`, not on connect keys
`delete_scheduled_post`	Delete a scheduler-side post — hidden from all dashboards, won't publish.	`postId`, `postName`	`posts:write` `agent:destructive`	confirm, flag: `AI_COPILOT_DESTRUCTIVE_TOOLS`, not on connect keys
`disconnect_account`	Disconnect a connected social account — clears OAuth tokens, flips status to "disconnected".	`accountId`, `platform`, `handle`	`accounts:write` `agent:destructive`	confirm, flag: `AI_COPILOT_DESTRUCTIVE_TOOLS`, not on connect keys
`bulk_delete_scheduled_posts`	Soft-delete up to 50 scheduler-side posts in ONE call — every PLURAL scheduler delete ("remove all expired draft posts").	`postIds`, `filter`	`posts:write` `agent:destructive`	confirm, flag: `AI_COPILOT_DESTRUCTIVE_TOOLS`, not on connect keys

Other

Tool	What it does	Parameters	Required scopes	Notes
`export_collected_data`	Returns the actual values (emails, phones, names, answers) collected by the user's flows, newest first, for export or sync ("export my leads to a spreadsheet").	`flowId`, `fieldType`, `since`, `limit`, `cursor`	`flows:read`	flag: `AGENT_LEAD_EXPORT`
`list_media`	List the images and videos the user uploaded to the scheduler (their media library), newest first.	`kind`, `tag`, `query`, `limit`, `cursor`	`posts:read`	flag: `SCHEDULER_MEDIA_LIBRARY`
`list_plugs`	List the plugs on a scheduled or published post ("when this gets 100 likes, repost it"), with progress (lastValue of threshold) and state, plus which of the post's accounts can carry a plug and the metrics and actions each supports.	`postId`	`posts:read`	flag: `SCHEDULER_PLUGS`
`list_review_links`	List the client review links of a post and what the client said ("did my client approve Tuesday's post?").	`postId`, `postName`	`posts:read`	flag: `SCHEDULER_CLIENT_REVIEW_LINK`
`get_post_link_clicks`	Clicks on the short links of a scheduled or published post.	`postId`	`posts:read`	flag: `SCHEDULER_SHORT_LINKS`
`list_signatures`	List the user's saved post signatures (sign-offs appended after a blank line when a post publishes).	—	`posts:read`	flag: `SCHEDULER_SIGNATURES`
`find_next_slot`	Find the next free posting slot for a post on these accounts: the earliest of their weekly posting times (next 60 days) where none of them already has a scheduled post within 5 minutes.	`accountIds`, `after`	`posts:read`	flag: `SCHEDULER_POSTING_SLOTS`
`list_client_invites`	List the user's client invite links ("did my client connect their accounts?"): state, how many accounts each added and which ones.	`groupId`	`accounts:read`	flag: `SCHEDULER_CLIENT_INVITE_LINK`
`list_rss_feeds`	List the user's RSS feeds (at most 5) and how each new item is handled: "draft" (a draft of the item's text), "ai_draft" (AI writes a draft for review) or "ai_schedule" (AI writes it and schedules it into the next free posting slot).	—	`posts:read`	flag: `SCHEDULER_RSS_AI`
`detach_post_automation`	Remove the comment automation from a scheduled post ("remove the automation from Tuesday's post").	`postId`, `postName`	`posts:write`	confirm, flag: `AI_BUILDER_EXTENDED_STEPS`
`upload_media_from_url`	Copy an image or video from a public URL into the user's SociaHive uploads and return a URL on our storage.	`url`	`uploads:write`	flag: `MEDIA_UPLOAD_FROM_URL`
`create_review_link`	Make a client review link for a scheduled post or draft ("send this post to my client for approval").	`postId`, `postName`, `reviewerName`	`posts:write`	confirm, flag: `SCHEDULER_CLIENT_REVIEW_LINK`
`duplicate_scheduled_post`	Copy a post as a new DRAFT with the same text, media, channels, platform options and tags ("duplicate Tuesday's post", "make a copy of that post").	`postId`, `postName`	`posts:write`	flag: `SCHEDULER_CALENDAR_CARD_ACTIONS`
`arm_plug`	Arm a plug on a scheduled or published post: when the post reaches `threshold` of `metric` on that account, SociaHive reposts it (X) or adds the comment (X reply, Instagram, Facebook), once.	`postId`, `accountId`, `metric`, `threshold`, `action`, `text`	`posts:write`	confirm, flag: `SCHEDULER_PLUGS`
`generate_post_image`	Make 1 to 4 AI images for a post from a description (`prompt`) or from the post caption (`caption`).	`prompt`, `caption`, `aspect`, `count`	`uploads:write`	flag: `SCHEDULER_COMPOSER_IMAGE_GEN`
`create_signature`	Save a post signature (a sign-off such as "Team Acme · acme.com") the user can append to posts at publish.	`name`, `text`, `accountIds`, `isDefault`	`posts:write`	flag: `SCHEDULER_SIGNATURES`
`manage_posting_slots`	List, add, change or remove posting slots: weekly posting times per account ("every Monday at 09:30, Europe/Berlin, for @shop on Instagram and Facebook").	`action`, `slotId`, `accountIds`, `weekday`, `time`, `timezone`	`posts:write`	flag: `SCHEDULER_POSTING_SLOTS`
`create_client_invite`	Make a client invite link for one of the user's account groups ("send my client a link to connect their Instagram").	`groupId`, `groupName`, `platforms`, `maxAccounts`	`accounts:write`	confirm, flag: `SCHEDULER_CLIENT_INVITE_LINK`, not on connect keys
`update_rss_feed`	Pause or resume an RSS feed, or change how AI writes posts from it: mode ("draft" or "ai_draft"), instructions, tone, image, accounts and the daily cap.	`feedId`, `paused`, `mode`, `instructions`, `tone`, `image`, `accountIds`, `dailyCap`	`posts:write`	flag: `SCHEDULER_RSS_AI`

Resources

Read-only context the client can fetch by URI, no tool call needed. Eleven are listed by resources/list; the two templated URIs are readable but not enumerated.

URI	Contents
`sociahive://platforms`	Supported platforms and their capabilities
`sociahive://trigger-types`	Flow trigger types per platform
`sociahive://node-types`	Flow node types
`sociahive://post-statuses`	Scheduled-post status machine
`sociahive://flows`	Your flows
`sociahive://posts/upcoming`	Next 14 days of scheduled posts
`sociahive://accounts`	Your connected accounts
`sociahive://audit/recent`	Recent agent actions taken on your account
`sociahive://health`	Account health signals
`sociahive://changelog`	Platform changelog
`sociahive://docs/quick-start`	Quick-start guide
`sociahive://flows/{id}`	One flow, full detail (template — not listed)
`sociahive://posts/{id}`	One scheduled post (template — not listed)

Clients that support notifications/resources/updated get pushed refreshes when a post publishes or a flow changes.

Prompts

One-click workflows the client surfaces as slash commands.

Prompt	Arguments	What it does
`weekly-report`	`timezone`	Reads upcoming posts + flow stats, writes a Monday recap
`content-audit`	`lookback_days`	Reviews scheduled posts for tone, clashes, platform-fit
`flow-cleanup`	—	Finds inactive/underperforming flows, proposes archives
`onboard-agency`	`client_name`, `platforms`	Scaffolds a new agency client's flows and draft posts

Known gaps

A live audit on 2026-08-20 found six defects here. All are now fixed; this section records what remains.

Scope catalog: no gaps. Every scope enforced at a chokepoint is mintable on a granular key, guarded by api-key-scope-catalog.test.ts.
15 tools are unreachable from a one-click connect key — they need scopes outside the connect grant (deliberately: the connect key is fixed and non-destructive). Mint a custom key with the scopes you need.
5 tools need an explicit accountId on a multi-account key. MCP keys are workspace-level with no account picker, so a default account is bound only when the owner has exactly one. On a key with two or more, pass accountId (from list_accounts) to search_flows, list_published_media, get_latest_published_media, get_published_media, search_published_media. Omitting it returns auth_error / no_account_selected; an id you don't own returns the same error rather than leaking that it exists.
Deleting a scheduled post needs posts:write, not admin. DELETE /api/v1/posts/{id} performs the same soft-delete as the dashboard. The agent tools (delete_scheduled_post, bulk_delete_scheduled_posts) additionally require the admin-only AI_COPILOT_DESTRUCTIVE_TOOLS flag plus agent:destructive.

Errors and limits

Typed error envelopes and retry guidance: errors · rate limits.