@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:

1. list_characters → find the id for Luna
2. apply_marketing_preset with { presetId: "product-review", characterId: "...", productDescription: "matte black insulated water bottle", productImageUrl: "https://..." }
3. The response is a video jobId
4. wait_for_generation with the jobId
5. 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