SocialHub.AI
Book a demo
Resources · SoCode

Run SocialHub from Claude Code

SoCode is the SocialHub integration for Claude Code (and Claude Desktop / Cursor): a downloadable skill plus a governed MCP server. Operate SocialHub — and ask about your data — in plain language.

Get startedWhy SoCode?
claude · socialhub (mcp)

› ask in plain language

you › GMV last week by store, top 3▋

↳ governed metric · gmv · by store · last_7d

Store 042$128,400
Store 017$96,250
Store 233$81,900

from the semantic layer · no SQL · audited · illustrative

01 — Overview

What is SoCode?

SoCode is how SocialHub plugs into your AI assistant. It's two pieces working together — so Claude can operate SocialHub and answer questions about your data, in plain language, without you leaving your editor.

The skill

flash-operations

A downloadable Claude skill that teaches Claude how to drive SocialHub safely — which tool to use, confirming writes by member name/email, and only quoting governed metric numbers.

The server

Governed MCP server

A Model Context Protocol endpoint that exposes SocialHub's tools — loyalty, members, coupons, campaigns and your governed metrics — authenticated by a tenant API key and authorized per tool.

02 — Why it matters

Why SoCode?

Your data and operations, reachable from the AI tools your team already uses — without trading away governance.

Natural language, no dashboards

Ask in plain English; Claude picks the right governed tool and runs it. No clicking through screens, no SQL to write.

Governed & safe by design

Metric numbers come from SocialHub's semantic layer (the AI never invents figures). Writes require a write scope and pass a server-side guard. Every key is scoped to your team; every call is audited.

Works where you already work

Claude Code, Claude Desktop, Cursor — any MCP client. Connect once with a single command and operate SocialHub without leaving your assistant.

Start read-only

Begin with the metrics:read preset (safest for AI). Add write scopes only when you need to award points or issue coupons — you stay in control.

What wasn't possible before SoCode

Each of these used to need an analyst, an engineer, or a dashboard you don't have — so the person with the question rarely got the answer in time. A governed agent inside your own AI toolis what makes them possible: business-grade answers and actions, self-serve, without giving up control of your data. That's the unlock — not a faster dashboard, a different operating model.

★ Retention marketer · the core loop

“Find the members slipping toward churn, launch a win-back, and keep tuning it to my goal.”

BeforeThree teams and three tools across weeks: an analyst pulls the data, a marketer builds the campaign, someone checks results next month — by then the moment has passed and the loop never actually closes.

With SoCodeOne agentic loop runs analyze → execute → improve: it reads the governed metrics, launches the journey you approve, measures the lift, and re-tunes — continuously, against the goals and guardrails you set.

Growth / analytics lead

“GMV last week by store — and why are redemptions down this month?”

BeforeFile a request and wait for an analyst, or stitch it together across dashboards — the answer arrives after the decision is already made.

With SoCodeA governed, trustworthy answer in seconds — the call gets made on data, not on a hunch.

AI / ML engineer

Expose SocialHub's governed metrics to your own assistant or a Cursor workflow over MCP.

BeforeA custom integration, hand-written queries, and governance re-implemented from scratch — months of work, and a new place for numbers to drift.

With SoCodeOne scoped key and the governed layer is callable from your stack. The integration that used to be a project is a config line.

Marketing manager

“Did active members drop vs last month? Break it down by tier.”

BeforeYou'd notice it in the monthly review — after the month was already lost.

With SoCodeSelf-serve, multi-step diagnosis the moment you wonder — catch the leak while you can still act on it.

03 — Set up in 3 steps

How SoCode works

Three steps: download the skill, install the MCP server, and use it in natural language.

1. Download SoCode (the skill)

The SoCode skill (flash-operations) teaches Claude how to drive SocialHub safely. It pairs with the SocialHub MCP server you'll add in step 2.

Get the skill folder

# Pull just the SoCode skill into Claude Code
npx degit huangchunbo2025/flash/skills/flash-operations \
  ~/.claude/skills/flash-operations

Or browse / download it on GitHub → skills/flash-operations. Copy the folder into ~/.claude/skills/ (personal) or your project's .claude/skills/.

The skill is optional but recommended — the MCP server works without it; SoCode's skill just makes Claude use it well.

2. Install the MCP server

a) Create an API key

In SocialHub, go to Settings → API Keys → Create Key and pick the "Read-only" preset (includes metrics:read — safest for AI use; add write scopes only when you need to award points or issue coupons). The key is shown once — copy it.

Go to API Keys

b) Add the server to Claude Code

Export the key as an environment variable first, so the plaintext key never lands in your shell history or a config file:

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}"

Prefer config? Add a project-scoped .mcp.json at your repo root — reference the env var, never paste a plaintext key:

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

c) Verify

  • Run claude mcp list — flash should show as connected.
  • Ask Claude to "list available SocialHub tools"— you'll only see the tools your key's scopes allow.
  • The server name must be exactly flash, and FLASH_API_KEY must be exported in the shell that launches Claude Code. An invalid key shows as a failed connection.

3. Use it

Just ask Claude in plain language. For example:

Query your data

  • “List the metrics I can query.”
  • “GMV last week by store.”
  • “Why did redemptions drop this month?”

Run operations

  • “Award 200 points to Alice (alice@…).”
  • “List active coupon pools.”
  • “Issue an ambassador code for this member.”

Stay in control

  • Writes are confirmed before running.
  • Server-side caps block oversized writes.
  • See every call under API Keys → Recent MCP Activity.

Safe by design.Metric numbers come from SocialHub's governed semantic layer (the AI never writes SQL or invents figures). Write operations require a write scope and pass a server-side guard (per-call value cap + rate limit) — chat confirmation is courtesy, the server is the boundary. Every key is scoped to your team only.

MCP Guide (full reference)REST API ReferenceManage API KeysBack to Resources