MCP Integration Guide

The Model Context Protocol (MCP) is an open standard that lets AI assistants call external tools directly. SocialHub implements an MCP server so you can manage stores, members, coupons, and points from within Claude Desktop, Cursor, or any MCP-compatible client.

Instead of writing code, you simply ask the AI: "List all active stores" or "Award 500 points to member m_abc123" and the assistant calls the SocialHub MCP tool on your behalf.

Connection Configuration

SocialHub exposes a Streamable HTTP MCP endpoint. You need two pieces of information:

Endpoint URL	https://flash.socialhub.ai/api/mcp
API Key Header	Authorization: Bearer fl_live_...

Create an API Key at /flash/account/api-keys. Ensure the key has the scopes needed for the tools you plan to use.

Claude Desktop Configuration

Add the following to your Claude Desktop MCP settings (claude_desktop_config.json):

{
  "mcpServers": {
    "flash": {
      "type": "http",
      "url": "https://flash.socialhub.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer fl_live_your_key_here"
      }
    }
  }
}

Cursor Configuration

In Cursor, go to Settings > MCP and add a new server:

{
  "mcpServers": {
    "flash": {
      "type": "http",
      "url": "https://flash.socialhub.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer fl_live_your_key_here"
      }
    }
  }
}

The type field also accepts streamable-httpas an alias. These desktop clients store the key in their config file — treat it as a secret, and prefer the environment-variable form (below) where supported to keep the plaintext key off disk.

Connect from Claude Code

Add SocialHub as an HTTP MCP server with the claude mcp add command. Export your key as an environment variable first so the plaintext key never lands in a config file or your shell history:

export FLASH_API_KEY="fl_live_your_key_here"

claude mcp add --transport http flash \
  https://flash.socialhub.ai/api/mcp \
  --header "Authorization: Bearer ${FLASH_API_KEY}"

Or commit a project-scoped .mcp.json at the repo root. Reference the env var with ${FLASH_API_KEY}— never paste a plaintext key:

{
  "mcpServers": {
    "flash": {
      "type": "http",
      "url": "https://flash.socialhub.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ${FLASH_API_KEY}"
      }
    }
  }
}

Self-check after connecting:

Run claude mcp list and confirm flash shows as connected.
Ask the assistant to "list available SocialHub tools" — you should see only the tools your key's scopes allow.
The server key must be exactly flash; make sure FLASH_API_KEY is exported in the shell that launches Claude Code.

Gotcha: an invalid or revoked key surfaces as a failed connection, not an auth prompt. SocialHub uses bearer-token auth with no OAuth fallback, so if the server shows as failed/disconnected, re-check the key value and that it has the scopes you need before debugging anything else.

Available Tools (30)

list_metrics

List the metrics available to this team from the governed semantic layer (key, label, unit, certification, category). Call first to discover valid metric keys. Requires metrics:read.

Parameters: category?

describe_metric

Get the full spec of one metric: authoritative definition, unit, certification, dimensions, filterable fields, tunable parameters, and usage guidance. Requires metrics:read.

Parameters: metric

query_metric

Run a governed metric query and return numbers with their authoritative definition. Pick a metric key plus optional dimensions, filters, time range, grain, and period-over-period comparison — never SQL. Requires metrics:read.

Parameters: metric, dimensions?, filters?, timeRange?, grain?, compare?, params?

breakdown_metric

Break one metric down by a single dimension over a fixed recent window, with human-readable labels (store/tier/channel names). Requires metrics:read.

Parameters: metric, dimension, days, state?

ask_metrics

Answer a natural-language question by selecting the right governed metrics, fetching them, and breaking down the primary metric. For open-ended diagnosis. Requires metrics:read.

Parameters: question, categories?

list_stores

List all stores for the current team. Supports optional status filter, search, and pagination.

Parameters: status?, search?, limit?, offset?

get_store

Get details of a specific store by its ID.

Parameters: store_id

list_members

List loyalty program members. Supports program filter and pagination.

Parameters: programId?, limit?, offset?, status?

get_member

Get details of a specific loyalty member by ID. Returns decrypted PII fields.

Parameters: member_id

list_coupon_pools

List coupon pools. Supports status and type filters.

Parameters: status?, coupon_type?, limit?, offset?

get_dashboard_stats

Operational dashboard snapshot (captures, scans, capture rate, coupons, stores, plan). Not a governed metric — use the metric tools for authoritative business metrics.

Parameters: (none)

earn_points

Award loyalty points to a member. Returns transaction ID and new balance.

Parameters: member_id, amount, description?

redeem_points

Deduct loyalty points from a member (FIFO consumption).

Parameters: member_id, amount, reason

get_points_balance

Get member's current points balance and recent transaction history.

Parameters: member_id, limit?

get_member_coupons

Get a member's available (unredeemed, unexpired) coupons.

Parameters: member_id

get_member_tier

Get member's current tier, next tier upgrade requirements, and all tiers.

Parameters: member_id

get_member_receipts

Get member's receipt submission history with OCR status and points awarded.

Parameters: member_id, limit?

redeem_points_for_coupon

Redeem loyalty points for a coupon from a specified pool (atomic: points + coupon, or neither).

Parameters: member_id, pool_id, points_cost

check_email_frequency

Check whether a marketing email can be sent to an address under the frequency limits (1/day, 2/week, 4/month).

Parameters: email

list_ambassador_candidates

List scored Ambassador candidates for the loyalty program (Pro mode). Empty in Lite mode.

Parameters: band?, status?, level?, sort_by?, limit?, offset?

get_ambassador_metrics

Get the Ambassador ROI report: the three subgoals, Month-2 retention, and the 90-day go/no-go gate.

Parameters: since_days?, assumed_paid_cac_usd?

issue_ambassador_code

Issue or upgrade a member's personal Ambassador affiliate code. Returns the code string.

Parameters: member_id, single_use?, max_redemptions?, min_order_amount?

get_tracking_stats

Get page-visit / behavior analytics: overview, top pages, device breakdown, or traffic sources.

Parameters: metric?, period?, start?, end?, campaign?, limit?

get_member_timeline

One member's recent behavior timeline (visits, points, coupons, emails, receipts) + summary, to decide a personalized action. Returns decrypted PII. Requires members:behavior:read.

Parameters: member_id, limit?

list_segments

List the team's audience segments (name, status, cached member count). Requires segments:read.

Parameters: status?, limit?, offset?

create_segment

Create an audience segment from structured conditions (never SQL); rejects duplicates. Requires segments:write + a user-owned key.

Parameters: name, conditions, description?

list_automations

List the team's automations (event-triggered campaigns) and their status. Requires automations:read.

Parameters: status?

pause_automation

Pause a running automation by campaign ID (idempotent). Requires automations:write.

Parameters: campaign_id

create_campaign_draft

Create a campaign DRAFT from a template or prior campaign (NEVER sends — human review required). Requires campaigns:write-draft.

Parameters: title, template_id?, source_campaign_id?, segment_id?, merge_context?

check_member_reach

Check if a member was already contacted (any system) on a channel within a recent window — avoid over-contacting. Requires members:behavior:read.

Parameters: member_id, channel, days?

Safety & Privacy

The MCP surface is the AI convenience layer, not a bulk admin tool. A few things to keep in mind:

The server is the boundary, not the chat. Write operations (awarding/redeeming points, issuing coupons, issuing Ambassador codes) require the matching write scope andare bounded by a server-side guard: a per-call value cap plus a per-key write-rate limit, both enforced fail-closed. Any in-chat confirmation your AI client asks for is courtesy — the server is what actually stops a leaked key or a prompt-injected model from draining points.
Some read tools return member PII. Tools like get_member and list_members can return decrypted names and emails into your AI client. Treat that data accordingly and prefer least-privilege keys.
Never commit a plaintext key. Always reference ${FLASH_API_KEY} in a checked-in .mcp.json rather than the literal key.
Use least-privilege, read-only keys. Create a key scoped to only the tools you need. If a key lacks a tool's scope, that tool is simply hidden — it never appears in the list.

Numbers Come from the Governed Semantic Layer

Every metric the AI reports — GMV, active members, redemption rate, and the rest — flows through SocialHub's governed metrics layer, which holds a single authoritative definition (and certification) for each metric. The list_metrics, describe_metric, query_metric, breakdown_metric, and ask_metricstools select metric keys and dimensions under that governance — the AI never writes SQL. So the figures you get back match your dashboards instead of being ad-hoc, drift-prone aggregates.

Example Conversation

You: "List all active stores"

Claude: Calls list_stores with status="active"

Claude: "You have 3 active stores: Downtown Flagship, Mall Kiosk, and Airport Pop-up."

SoCode — Run SocialHub from Claude Code REST API Reference Quickstart Back to Developer Center

Create an API Key