Socode

Run Flash from Claude Code

Socode is the Flash integration for Claude Code (and Claude Desktop / Cursor): a downloadable skill plus a governed MCP server. Operate Flash — and ask about your data — in natural language. Three steps: download, install, use.

Download

Grab the Socode skill (flash-operations) + MCP config.

Install

Create a key and add the MCP server with one command.

Use

Ask Claude in plain language — query data, manage loyalty.

1. Download Socode (the skill)

The Socode skill (flash-operations) teaches Claude how to drive Flash safely — which tool to use, confirming writes by member name/email, and only quoting governed metric numbers. It pairs with the Flash 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 Flash, 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://your-domain.com/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://your-domain.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${FLASH_API_KEY}"
      }
    }
  }
}

c) Verify

Run claude mcp list — flash should show as connected.
Ask Claude to "list available Flash 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 Flash'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.

Running it unattended? For a scheduled agent that watches member behavior and acts on its own (the agentic retention loop), create an Agent key instead — it adds a cumulative budget, a kill-switch, and reversible writes, and keeps outreach to drafts a human sends. See Autonomous Agent Keys in the MCP guide.

MCP Guide (full reference)REST API Reference Manage API Keys Help Center