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 [`masky-mcp-server`](https://www.npmjs.com/package/masky-mcp-server) 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:

```bash
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:

```json
{
  "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:

```bash
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):

```json
{
  "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.
- `register_oauth_client` / `get_sso_integration_guide` — add "Login with Masky" SSO to your own site (full guide: https://masky.ai/masky-sso.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
