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

The MCP server exposes 70 tools. The full catalog — parameters, required API-key scopes, feature flags, and which ones need confirmation — lives in the tools reference, generated directly from the tool registry so it can't drift.

Every tool runs as the authenticated user, so your tier limits and billing apply automatically. Call list_capabilities from any MCP client to see the exact set your key can invoke — it filters by your scopes, tier, and feature flags.

Broad strokes:

Area	Examples
Session	`whoami`, `list_capabilities`
Flows — read	`list_flows`, `get_flow`, `list_flows_with_stats`, `search_flows`
Flows — write	`create_flow`, `generate_flow`, `add_node`, `add_edge`, `activate_flow`
Posts — read	`list_scheduled_posts`, `get_scheduler_calendar`, `get_post_analytics`
Posts — write	`create_scheduled_post`, `schedule_post`, `publish_post_now`
Accounts & media	`list_accounts`, `get_capabilities`, `search_published_media`
Analytics	`get_flow_stats`, `get_analytics_overview`, `get_content_insights`
Autopilot	`get_autopilot_status`, `generate_autopilot_week`, `approve_autopilot_week`
Destructive	`delete_flow`, `delete_scheduled_post`, `disconnect_account`

Two behaviours worth knowing before you start:

Graph mutations reject published flows. add_node / update_node / add_edge return a state_error with a duplicate_then_edit suggestion — duplicate the flow to a draft, edit it, then republish.
There is no one-step "create and publish". Use create_scheduled_post to draft, then publish_post_now (which confirms). The combined path was removed because it bypassed the confirmation gate protecting against accidental live publishes. Already-published media on the platform is never touched — the agent does not delete from Instagram, Facebook, etc.

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.