@socialaf/mcp-server

@socialaf/mcp-server

MCP server for socialAF Character Studio. Build a character once, then generate stills, video, voice, and lip-synced talking heads against it from any MCP client (Claude Desktop, Cursor, OpenClaw, Codex).

Install

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "socialaf": {
      "command": "npx",
      "args": ["-y", "@socialaf/mcp-server"],
      "env": { "SOCIALAF_API_KEY": "saf_live_..." }
    }
  }
}

Get your API key at socialaf.ai/settings (Settings → API Keys). Restart Claude Desktop and the socialaf tools appear in the tool list.

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "socialaf": {
      "command": "npx",
      "args": ["-y", "@socialaf/mcp-server"],
      "env": { "SOCIALAF_API_KEY": "saf_live_..." }
    }
  }
}

OpenClaw, Codex, other agents

Any MCP client that speaks stdio-transport JSON-RPC can use this server. Run npx -y @socialaf/mcp-server as a child process, pipe stdin/stdout, and pass SOCIALAF_API_KEY in the environment.

Tools

Tool	What it does
apply_marketing_preset	The wedge. Pick one of 8 ad formats (Product Review, Unboxing, Talking Head Ad, Tutorial, Virtual Try-On, Hero Shot, UGC Selfie, TV Spot) and the system bakes in the right prompt, model, aspect, and duration for the user's character.
list_marketing_presets	List the 8 presets and what each one does.
list_characters	List the user's characters and other asset kinds.
get_character	Get one character with its reference images.
create_character	Create a new character (or location, object, outfit, style).
delete_character	Soft-delete an asset.
attest_character	Affirm the character is an adult. Required before any generation.
create_upload_url	Get a presigned R2 upload URL for a reference image.
attach_character_reference	Attach an uploaded reference image to a character. Runs moderation synchronously.
remove_character_reference	Soft-delete a reference image.
generate_image	Synchronous image generation. Returns rendered URLs.
generate_video	Async video. Returns a jobId.
generate_lipsync	Async talking-head avatar. Returns a jobId.
generate_voice	Async TTS voiceover. Returns a jobId.
get_generation	Poll one job by id.
list_generations	List the user's recent generation jobs.
wait_for_generation	Poll a job until it settles or times out. Use this after async generations.
list_tools	Catalog of available image and video models with capabilities.
get_billing_status	Plan, credit balance, and subscription period.

Example flow

A user says: "Make a 9:16 product review ad for my Luna character holding the matte black water bottle."

A typical agent flow:

• list_characters → find the id for Luna
• apply_marketing_preset with { presetId: "product-review", characterId: "...", productDescription: "matte black insulated water bottle", productImageUrl: "https://..." }
• The response is a video jobId
• wait_for_generation with the jobId
• Return the resultUrls to the user

For an image preset (hero-shot, ugc-selfie), step 3 returns the rendered image URLs directly — no wait_for_generation needed.

Auth

Bearer token from SOCIALAF_API_KEY. Format: saf_live_*. The token rate-limits, deducts credits per generation, and scopes responses to the user's organization. Revoke / reissue at socialaf.ai/settings.

Development

cd packages/mcp-server
npm install
npm run build      # tsc → dist/
npm link           # makes the bin available globally
SOCIALAF_API_KEY=saf_live_... SOCIALAF_API_URL=http://localhost:3000 socialaf-mcp

For local Inspector debugging:

npx @modelcontextprotocol/inspector dist/index.js

License

MIT