# MCP setup and usage guide

> Updated 2026-11-03 · For KiiKii MCP and the WorkBuddy connector  
> HTML version: https://kiikii.cc/en/doc/mcp

## Quick answers

- MCP is a standard way to connect AI clients to kiikii. One configuration covers digital human and general creation.
- Non-WorkBuddy clients use a personal API key (starts with `kii_sk_`); WorkBuddy uses OAuth and needs no key.
- Digital human video is plan first, confirm later; image, video and voice jobs are asynchronous.
- The full key is shown once. Up to 10 active keys, each with its own configuration.

## 1. What MCP is

MCP (Model Context Protocol) lets AI clients call external capabilities. With the kiikii MCP server you can check credits, clone avatars, generate digital human videos, images, videos and voiceovers directly from Cursor, Claude Desktop or Trae.

One kiikii MCP configuration contains both digital human and general creation tools. The model picks the right tool based on whether an avatar or cloned voice needs to appear.

## 2. What you can do

| Capability | Details | Example prompt |
| --- | --- | --- |
| Account | Credits, plan and recharge link | Check my kiikii credit balance |
| Avatars | Clone from portraits, design a new avatar, list avatars | Clone my avatar from this photo |
| Voices | System voices, cloned voices, match by gender and age | Find a warm female voice around 45 |
| Digital human video | Five modes, shot plans, confirm, revise, subtitles | Make a 45-second explainer about chrysanthemums |
| Images | Text-to-image, reference images, 1–4 per call, up to 4K | Generate a 4K 16:9 coffee poster |
| Video | Text-to-video, image-to-video, first/last frame, references, audio driven | A 5-second rainy neon street clip |
| Voiceover | Text-to-speech with voice, speed, format and tone | Read this script in a male Chinese voice |
| Assets and jobs | Upload tickets, gallery link, job status and results | Send me the video you just generated |

## 3. Create an API key

1. Sign in and open Profile → API keys, or `/profile?section=apiKeys`.
2. Click Create, name it after the client or teammate, and choose an expiry.
3. Copy the full key and the ready-to-use MCP configuration immediately. The key cannot be viewed again.
4. Revoke any key from the list; it stops working immediately and does not affect other keys.

| Item | Details |
| --- | --- |
| Format | Starts with `kii_sk_`, shown once, only a hash is stored |
| Limit | Up to 10 active keys |
| Scopes | Account read, assets read, assets write; no admin access |
| Expiry | Never / 30 / 90 / 365 days |
| WorkBuddy | Uses OAuth and does not need this key |

Never commit a key to a public repository, screenshot it or paste it into a group chat. Create separate keys per person.

## 4. Connect a client

The kiikii MCP server uses Streamable HTTP, so there is nothing to install locally.

```json
{
  "mcpServers": {
    "kiikii": {
      "type": "streamableHttp",
      "url": "https://api.kiikii.vip/api/mcp",
      "headers": {
        "Authorization": "Bearer <your API key>"
      }
    }
  }
}
```

| Client | Where to configure | Notes |
| --- | --- | --- |
| Cursor | `~/.cursor/mcp.json` | Merge the mcpServers block and restart Cursor |
| Claude Desktop | `claude_desktop_config.json` | Merge the block and restart the app |
| Trae | Settings → MCP → Add | Choose HTTP / Streamable HTTP, add the URL and an Authorization header |
| WorkBuddy | Connector install | OAuth authorization, no API key needed |

Verify by asking "Check my kiikii credit balance". A nickname and balance means the key and network work.

## 5. Tool reference

| Tool | Purpose | When it is used |
| --- | --- | --- |
| `kiikii_get_account` | Nickname, credits, plan, recharge link | Before generating |
| `kiikii_list_modes` | Five digital human modes and a recommendation | When the mode is unclear |
| `kiikii_list_avatars` | List usable avatars with avatarId | Before digital human video |
| `kiikii_create_avatar` | Clone or design an avatar (async) | When a new avatar is needed |
| `kiikii_list_voices` | Filter voices by gender, age and keywords | Choosing a voice |
| `kiikii_create_voice_clone` | Clone a voice from a sample | When a custom voice is needed |
| `kiikii_create_upload_ticket` | Create an upload ticket and URL | Uploading images, audio or songs |
| `kiikii_complete_upload` | Validate and register a file, return assetToken | After the bytes are uploaded |
| `kiikii_get_upload_ticket` | Check upload ticket status | Recovering an interrupted upload |
| `kiikii_create_video` | Create a plan only, no production | Starting a digital human video |
| `kiikii_confirm_video` | Confirm the plan and start production | Only after explicit confirmation |
| `kiikii_revise_video_plan` | Revise the plan on the same job | Changes before confirmation |
| `kiikii_update_video_subtitles` | Re-burn subtitles without regenerating frames | Subtitle changes after the final cut |
| `kiikii_get_job` | Avatar and video job status and results | Plan, progress and final video |
| `kiikii_list_jobs` | Recent jobs | When a jobId is missing |
| `kiikii_generate_image` | Text-to-image and reference images | Posters, covers, illustrations |
| `kiikii_generate_video` | Text-to-video, image-to-video, first/last frame, audio driven | Scenes without an avatar |
| `kiikii_generate_audio` | Text-to-speech | Narration and voiceover |
| `kiikii_get_creation` | Creation job status and results | Polling image, video and audio jobs |
| `kiikii_list_creation_models` | Available image, video and audio models | Model choice or parameter limits |
| `kiikii_open_asset_gallery` | Signed asset gallery link | Browsing avatars or voices |

## 6. Digital human video

| Mode | Best for | Target duration | Inputs |
| --- | --- | --- | --- |
| studio | Explainers, courses, product intros | 30–150 s | Avatar + voice |
| continuous | Single-take talking head | 20–60 s | Avatar + voice; slower to render |
| mv | Songs, covers, brand themes | Follows the song | 1–2 avatars + a song |
| ecommerce | Product selling points and promos | 20–80 s | Avatar + voice + product image (+ scene image) |
| store_visit | Local stores and tourism | 20–80 s | Avatar + voice + 1–3 scene images |

Flow:

1. `kiikii_create_video` only returns shots and script.
2. The assistant shows the plan, duration and estimated credits, then waits for an explicit yes before `kiikii_confirm_video`.
3. Before confirming, say "change shot 2 to text-to-video" or "make shot 3 more conversational"; `kiikii_revise_video_plan` edits the original job.
4. Production is asynchronous; use `kiikii_get_job` for stage and final video.

```text
Use my avatar "Zhiya" and a warm 45-year-old female voice.
Make a 45-second explainer about chrysanthemums and the Double Ninth Festival.
9:16, 720p, burned-in subtitles.

(After the plan) Change shot 2 to a text-to-video insert of
chrysanthemums after rain; change shot 3 to a web animation timeline.
```

## 7. Images, video and voice

### Images

- Up to 4 images per call, billed individually; text-to-image and reference images (up to 4).
- Ratios: auto / 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3.
- Resolution: 1K / 2K / 4K; only nano-banana-2 truly supports 2K and 4K. Other models are submitted at 1K.
- When the user names a model, call `kiikii_list_creation_models` and use the returned model value.

### Video

- Text-to-video, image-to-video, first frame, first/last frame, reference image/video and audio driven; one clip per call.
- Ratios: auto / 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16; resolution 480 / 720 / 1080; default 5 seconds.
- If the clip needs an avatar, talking head, lip sync or a singing MV, use the digital human tools.

### Voice

- Up to 20,000 characters, with format and speed (0.5–2).
- Describe the voice with `voiceHint` or gender + age; the server matches the closest real voice.
- Use `kiikii_create_voice_clone` first when you need a unique voice.

## 8. Jobs and credits

| Job type | Create with | Query with | Result |
| --- | --- | --- | --- |
| Avatar | `kiikii_create_avatar` | `kiikii_get_job` | Avatar ID, four-view sheet and cover |
| Digital human video | `kiikii_create_video` / `confirm_video` | `kiikii_get_job` | Plan, segment status, final video URL |
| Image | `kiikii_generate_image` | `kiikii_get_creation` | Image URLs, model, actual cost |
| Video | `kiikii_generate_video` | `kiikii_get_creation` | Video URL, model, actual cost |
| Voiceover | `kiikii_generate_audio` | `kiikii_get_creation` | Audio URL, voice, actual cost |

- Poll every 10–20 seconds and stop once the job succeeds or fails.
- Call `kiikii_get_account` before generating; results include the actual cost.
- Failed jobs are refunded per site policy. Timed-out jobs stay running; keep querying the same jobId.
- Digital human video accepts an `idempotencyKey`; reuse it when retrying.

## 9. Tips

1. If unsure about the mode, describe the goal and duration and let the assistant recommend one.
2. Name the shot and the target change; up to 3 shots per revision.
3. Shot types are editable: "change shot 2 to text-to-video", "change shot 3 to a long digital-human take".
4. Upload first and use the assetToken; assets cannot be replaced mid-conversation.
5. Describe voices ("45-year-old female, warm and intellectual") instead of guessing an ID.
6. Separate post-production edits: subtitle re-burn for subtitles, plan edit for visuals or script, re-assemble for the final cut.

## 10. FAQ

### How is MCP different from the WorkBuddy connector?

Both expose the same capabilities. WorkBuddy installs a connector through OAuth and needs no API key; Cursor, Claude Desktop and Trae use a personal API key.

### Why are my MCP images only 1K?

Only nano-banana-2 supports 2K and 4K right now; every other image model is submitted at 1K. Call `kiikii_list_creation_models`, then pass `resolution`.

### Why did a revision create a new video?

Digital human video is plan first, confirm later. Use `kiikii_revise_video_plan` on the existing job instead of `kiikii_create_video`.

### A job stays in progress for a long time. What should I do?

Image, video and audio jobs are asynchronous. Poll every 10–20 seconds; a timeout does not charge twice.

### Can I recover a lost API key?

No. The full key is shown once and only a hash is stored. Revoke it and create a new one.

### How many keys can one account create?

Up to 10 active keys, each with its own configuration.

### How do uploads work over MCP?

Call `kiikii_create_upload_ticket`, PUT the bytes, then call `kiikii_complete_upload` to obtain an assetToken.

### Do MCP generations consume credits?

Yes. MCP uses the same credit rules as the web app; failed jobs are refunded per site policy.

## 11. Get started

1. Create a key in Profile → API keys and copy the full MCP config.
2. Merge `mcpServers` into your client config and restart.
3. Ask "Check my kiikii credit balance", then "Make a 45-second explainer with my avatar".

- Create an API key: https://kiikii.cc/profile?section=apiKeys
- Digital human guide: https://kiikii.cc/en/doc/digital-human
- Models and credits: https://kiikii.cc/en/doc/models