Docs MCP server

Masky API keys are generated at https://masky.ai/docs. No key? See "First: get an API key" in https://masky.ai/skill.md — an AI assistant can connect its user's account with one link, no developer page needed.

Masky MCP#

Masky exposes its capabilities as native MCP tools for any MCP client — Claude Desktop, Claude Code, Cursor, or Anthropic API tool use — two ways:

  1. Hosted endpoint — https://masky.ai/api/mcp (streamable HTTP), nothing to install
  2. Local server — the undefined npm package (stdio)

Both expose the same tools:

  • List your avatars and publicly renderable avatars from other users
  • Create avatars (image + personality + voice) and generate images
  • Start live conversations and inject turns whose audio/video can be embedded in OBS or any web page
  • Generate one-shot avatar TTS / talking-head clips and freeform videos

Hosted endpoint (no install)#

Claude Code, one line:

claude mcp add --transport http masky https://masky.ai/api/mcp --header "Authorization: Bearer mky_YOURKEY"

Any client that takes an HTTP/streamable-HTTP server config:

{
  "mcpServers": {
    "masky": {
      "type": "http",
      "url": "https://masky.ai/api/mcp",
      "headers": { "Authorization": "Bearer mky_YOURKEY" }
    }
  }
}

Details:

  • Stateless streamable HTTP, JSON responses — each POST /api/mcp call stands alone; no session to manage.
  • initialize and tools/list work without auth, so clients can connect and discover tools before a key exists.
  • Every tools/call needs Authorization: Bearer mky_... — the same keys, OAuth access tokens, and billing as the REST API.

Local server (npm)#

Claude Code, one line:

claude mcp add masky -e MASKY_API_KEY=mky_... -- npx -y masky-mcp-server

Claude Desktop (or any client that takes a JSON server config):

{
  "mcpServers": {
    "masky": {
      "command": "npx",
      "args": ["-y", "masky-mcp-server"],
      "env": { "MASKY_API_KEY": "mky_..." }
    }
  }
}

Restart the client; the Masky tools appear in the MCP tools menu. Requires Node ≥18.

Environment variables:

  • MASKY_API_KEY (required) — bearer token from https://masky.ai/docs
  • MASKY_API_BASE (optional) — defaults to https://masky.ai

Tools#

  • list_my_avatars / list_public_avatars — your avatars, and avatars marked publicly renderable across all users
  • create_avatar — { displayName, imageUrl?, personalityPrompt?, voiceId?, knowledgeBaseUrls?, publiclyRenderable? }
  • generate_image — { prompt, aspectRatio?, model? } → public imageUrl (feed it to create_avatar). model: "ideogram" renders legible in-image text at 3x cost; with model omitted, "double-quoted" text in the prompt auto-routes there.
  • edit_image — { prompt, imageUrl|imageUrls[], aspectRatio?, model? } — edit/compose from 1–5 reference images; model: "qwen" for legible in-image text.
  • generate_video / get_video / get_video_pricing — async freeform video renders (scenes, animated images, generated sound/music). Never for lip-sync — its speechText is voice-over, not mouth-sync. Talking to camera → avatar_speak or a speak-mode turn; talking inside a moving scene → compose the frame with edit_image, then the REST speak endpoint with scenePrompt (see the "talking avatar in a complex scene" recipe in https://masky.ai/masky-api.md).
  • list_voices / set_avatar_voice — preset + your trained voices; attach one to an avatar
  • set_avatar_publicly_renderable — share / unshare an avatar
  • start_conversation — { avatarOwnerUserId, avatarId } → liveUrl (embed in OBS / web) + conversationId
  • inject_turn — { conversationId, userText, output?, mode?, speakerAvatarId?, userOutput?, avatarText?, voiceStyle? }. For a two-avatar podcast: speakerAvatarId + userOutput: "video" renders the user turn as a second avatar of yours, and avatarText scripts the exact reply — both sides in one call. userText max 500 chars (≈ ~35s of speech); replies are auto-split into ≤3-sentence clips — a latency feature for the realtime /live player, so the first clip plays while the rest renders.
  • set_conversation_visibility — public/private toggle
  • avatar_speak / get_avatar_speak — say one line (it wraps a one-turn conversation and returns the liveUrl player). Takes text OR audioUrl (exactly one): audioUrl is a public MP3/WAV URL the avatar lip-syncs directly — sung vocals, any pre-recorded voice, no TTS, no voice needed on the avatar, max 3 minutes, always one unsplit clip. When you want a single unsplit media file with no realtime player at all, call the REST one-shot endpoint instead — POST /avatars/{avatarId}/speak (also takes text or audioUrl), poll GET /avatars/speak/{generationId} (see https://masky.ai/masky-api.md).

Voice delivery: speak/turn calls take an optional voiceStyle: { emotion, style, prosody: [] } (falls back per-field to the avatar's Voice-tab default), and the spoken text may embed inline cues like <|sfx:laughter|> or <|prosody:pause|> (stripped from captions). An sfx tag must immediately precede matching onomatopoeia to vocalize — <|sfx:laughter|>Haha! laughs; a bare tag before ordinary words is silently skipped. Full tag vocabulary: the Voice delivery section of https://masky.ai/masky-api.md.

Example prompts#

  • "List my Masky avatars."
  • "Create a dragon avatar from this image: https://... Make it gruff and a bit medieval."
  • "Start a conversation with my dragon avatar and ask what it had for breakfast — give me the embeddable live URL."
  • "Make a 30-second podcast where my two avatars argue about tabs vs spaces."

Prefer raw HTTP instead? The same capabilities (plus translations, brain memory, the local-agent bridge, tribes, and credit gifts) are documented in the full API reference at https://masky.ai/masky-api.md, with a curl quickstart at https://masky.ai/masky-cli.md.

Generate or manage your Masky API key any time at https://masky.ai/docs

Reading this as an AI assistant, or want to hand it to one? The same guide is plain markdown at masky.ai/masky-mcp.md.