MCP Setup Guide

Connect Claude Desktop, Claude Code, ChatGPT, or any MCP-compatible agent to SociaHive — HTTP, stdio, OAuth, and CLI in one place.

Connect Claude Desktop, Claude Code, ChatGPT, or any MCP-compatible agent to your SociaHive instance to manage flows, posts, and analytics in natural language. Contacts live in the dashboard — the agent intentionally doesn't expose them as tools.

Connect your client

First, get an API key from Settings → API Keys in your SociaHive dashboard. New keys include the agent:execute scope by default. Then pick your client:

Open Claude Desktop → Settings → MCP Servers, paste:

{
  "sociahive": {
    "url": "https://www.sociahive.com/api/mcp",
    "headers": {
      "X-API-Key": "sk-your-api-key-here"
    }
  }
}

Restart Claude Desktop. SociaHive tools appear in the tool list.

No local setup, no Node.js, no build steps. The same JSON config works for ChatGPT Connectors and Cursor.

Available Tools

Every tool runs as the authenticated user — your tier limits and billing apply automatically. Call list_capabilities from any MCP client to see the exact set your key can invoke.

Tool	Description
`whoami`	Authenticated user identity (id, role, tier)
`list_capabilities`	Tools the current key can call
`current_page_context`	In-app surface only — returns empty over MCP

Accounts

Tool	Description
`list_accounts`	List connected social media accounts
`get_capabilities`	Per-account automation/scheduler capabilities
`disconnect_account`	Disconnect (destructive — confirms)

Flows

Tool	Description
`list_flows`	List automation flows
`get_flow`	Full flow detail (nodes, edges, trigger)
`create_flow`	Create a new draft flow
`update_flow`	Update name / description (graph edits use add/update_node)
`activate_flow`	Publish a flow
`deactivate_flow`	Unpublish a flow
`duplicate_flow`	Copy a flow as a new draft
`delete_flow`	Soft-delete (archive — restorable ~30 days)
`generate_flow`	AI-powered flow generation from a natural-language prompt

Flow Builder (graph mutations on drafts)

Tool	Description
`add_node`	Add a node (message, delay, condition, action, etc.)
`update_node`	Update node data, position, or name
`add_edge`	Connect two nodes (supports button routing via `sourceHandle`)

These tools reject mutations against published flows with a state_error and a duplicate_then_edit suggestion — duplicate the flow to a draft, edit, then republish.

Posts (Scheduler-side)

These tools read and write the SociaHive Content Scheduler — drafts, queued, recurring posts the user composed in-app. For media actually published on the connected platform (e.g. Instagram), see the Media section.

Tool	Description
`list_scheduled_posts`	List scheduler-side posts (drafts / queued / scheduler-published)
`get_scheduled_post`	Single scheduler-side post detail
`create_scheduled_post`	Create a draft (optionally scheduled with `scheduledAt`)
`update_scheduled_post`	Update post content or schedule
`schedule_post`	Schedule a draft for a specific time
`cancel_scheduled_post`	Revert a scheduled post to draft
`publish_post_now`	Publish immediately (destructive — confirms)
`delete_scheduled_post`	Soft-delete (no UI undo — confirms). Already-published media on platforms is unaffected — the agent does not delete from platforms.
`get_scheduler_calendar`	Calendar view of scheduler-side posts

To publish RIGHT NOW: use create_scheduled_post (drafts) → publish_post_now (confirms). The previous one-step "create + immediately publish" path was removed because it bypassed the confirmation gate that protects against accidental live publishes.

Analytics

Tool	Description
`get_flow_stats`	Per-flow metrics (triggers, button clicks, unique users)
`get_collected_data`	Flow form submissions (PII-redacted)
`get_post_analytics`	Per-post metrics across platforms
`get_analytics_overview`	Aggregate analytics with optional date range / platform filter
`list_system_templates`	Browse pre-built flow templates

Example Prompts

Try these in Claude Desktop, Claude Code, or any MCP client after connecting:

"List my Instagram automation flows"
"Build me a flow that DMs new followers a discount code"
"What's my engagement on Instagram last week?"
"Schedule a post for tomorrow at 9am: 'New product launch'"
"Duplicate my welcome flow and rename it to 'Holiday Welcome'"
"Add a 5-minute delay between the welcome message and the discount in flow X"
"Show stats for my lead capture flow"

API Key Scopes

API keys carry one or more scopes. The MCP endpoint requires agent:execute, which is included by default on every new key.

Irreversible operations — delete_*, disconnect_account, publish_post_now — are gated by a confirmation step regardless of scope. The first call returns a single-use confirmation token (5-minute TTL); the second call must pass it back. See Confirmation Flow below.

Confirmation Flow

Destructive tools return a pending_confirmation envelope on the first call. Clients (Claude Desktop, Claude Code, the sociahive CLI) handle this transparently — the LLM relays the affected entities to you and asks before re-calling with the confirm token.

For programmatic clients, the contract is:

First call returns { __mcp_envelope: 'pending_confirmation', confirmToken, summary, affectedEntities } (TTL 5 min).
Second call: same args plus __confirmToken: <token>. The server validates the token, ensures it hasn't been used before, and runs the tool.

Troubleshooting

"Authentication failed" / 401

Verify X-API-Key header is set (not Authorization).
Verify the key has agent:execute scope (auto-granted on first use; check API Key UI to confirm).

"Connection refused" on local stdio

Run npm run dev to start the local Next.js server.
Set SOCIAHIVE_API_URL=http://localhost:3000 (NOT /api/v1 — the CLI now appends /api/mcp itself).

Tools don't appear

Restart Claude Desktop after adding the config.
Check Claude Desktop logs: Help > Show Logs.

Rate limit

Per-tool limits: reads 120/min, writes 30/min, expensive (e.g. generate_flow) 5/min, daily cap 1000.
Concurrent sessions cap: 200 on the HTTP transport. Close idle sessions or wait 5 min for TTL.

generate_flow timeout

The tool returns immediately with a draft + builder URL. The actual AI generation streams when you open the flow in the dashboard. Cost is metered there, not at this call.

publish_post_now returns pending_confirmation

This is expected — destructive ops require a second call with the __confirmToken. CLI: pass --yes. MCP-aware clients handle it natively.

add_node / update_node / add_edge rejects with state_error

The target flow is published. Duplicate it to a draft (duplicate_flow), edit the copy, then republish.