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 72 tools (30 read, 38 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 74 rather than 72: 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 are admin-only today.
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`	Update a flow's identity fields.	—	`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`	—
`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, 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`	`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`
`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`

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