> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akool.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Connect AKOOL AI capabilities to Claude, Cursor, Codex, and any MCP-compatible client.

## Overview

AKOOL provides a **Model Context Protocol (MCP)** server that exposes face swap, image generation, TTS, and more as native tools inside AI assistants — no manual API calls needed.

> [!NOTE]
>
> Using ChatGPT, Claude, Claude Code or Codex? Sign in with your AKOOL account
> instead of using API credentials. See [Plugin](https://docs.akool.com/plugin.md).

## Credentials

MCP uses the same credentials as the CLI. Get them from your [AKOOL dashboard](https://akool.com/workspace/current/api/credentials):

| Header | Description |
| - | - |
| `x-client-id` | Your Client ID (`clientId`) |
| `x-client-secret` | Your Client Secret (`clientSecret`) |

## Server Config

```json theme={null}
{
  "mcpServers": {
    "akool-mcp": {
      "type": "http",
      "url": "https://openapi.akool.com/mcp/v1",
      "headers": {
        "x-client-id": "YOUR_CLIENT_ID",
        "x-client-secret": "YOUR_CLIENT_SECRET"
      }
    }
  }
}
```

***

## Available Tools

| Category | Description | Tool |
| - | - | - |
| **Account** | Get account credit balance | `account_credit` |
| | List available AI models | `account_models` |
| **Image** | Generate image from text or reference image | `image_create` |
| | Get image generation result | `image_info` |
| **Voice** | List available TTS voices | `voice_list` |
| | Convert text to speech | `audio_tts` |
| | Get TTS result | `voice_result` |
| **Face Swap** | Swap face in an image | `faceswap_image` |
| | Face swap in images or videos (multi-face) | `faceswap_plus` |
| | Get face swap result | `faceswap_result` |
| | Delete a face swap record | `faceswap_delete` |
| **Avatar** | List digital avatars | `avatar_list` |
| | Get avatar detail | `avatar_detail` |
| **Video** | Generate a video from a text prompt | `video_text2video_create` |
| | Create a talking photo video | `video_talking_photo_create` |
| | Create a talking avatar video | `video_talking_avatar_create` |
| | Get video generation result | `video_result` |
| **Image to Video** | Create a video from an image | `video_image2video_create` |
| | Get image-to-video result | `video_image2video_results` |
| | List available video effects | `video_image2video_effects` |
| | Update audio on a video | `video_image2video_update_audio` |
| | Delete an image-to-video record | `video_image2video_delete` |
| **Motion Swap** | List motion swap models | `video_motion_swap_models` |
| | Animate a person with a video's motion | `video_motion_swap_create` |
| **Video Editing** | Get the video editing guide | `video_edit_guide` |
| | Analyze a video | `video_analyze` |
| | Look at frames of a video | `video_frames` |
| | Render an edited video | `video_render` |
| | Get video analysis or render result | `video_edit_result` |
| **Face Detection** | Detect faces in an image | `facedetect_detect` |
| | Analyze faces across multiple frames | `facedetect_analyze` |
| **Files** | Upload a local file | `file_upload` |
| | Show results in the chat | `show_result` |

***

## Setup Guides

> [!NOTE]
>
> **CLI quick-add** is only supported by **Claude Code**. All other clients
> (Cursor, Windsurf, Codex, Kiro) require editing a config file.

### Claude Code

**Install**

```bash theme={null}
npm install -g @anthropic-ai/claude-code
```

**Add AKOOL MCP**

```bash theme={null}
claude mcp add --transport http akool-mcp https://openapi.akool.com/mcp/v1 \
  --header "x-client-id: YOUR_CLIENT_ID" \
  --header "x-client-secret: YOUR_CLIENT_SECRET"
```

Verify:

```bash theme={null}
claude mcp list
# akool-mcp   http   https://openapi.akool.com/mcp/v1
```

***

### Claude Desktop

**Install**

Download and install from [claude.ai/download](https://claude.ai/download).

**Add AKOOL MCP**

1. Go to **Customize** → **Connectors** → **+ Add** → **Add custom connector**.
2. Name it `akool-mcp` and enter `https://openapi.akool.com/mcp/v1` as the URL.
3. Under **Request headers**, add `x-client-id` and `x-client-secret` with your credentials.
4. Choose **No sign in**, then add the connector.

***

### Cursor

**Install**

Download from [cursor.com](https://www.cursor.com/), install and open.

**Add AKOOL MCP**

Go to **Settings** → **MCP** → **Add new global MCP server**, or edit `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "akool-mcp": {
      "type": "http",
      "url": "https://openapi.akool.com/mcp/v1",
      "headers": {
        "x-client-id": "YOUR_CLIENT_ID",
        "x-client-secret": "YOUR_CLIENT_SECRET"
      }
    }
  }
}
```

Restart Cursor. In the **Agent** panel, AKOOL tools will appear under **Available Tools**.

***

### Windsurf

**Install**

Download from [codeium.com/windsurf](https://codeium.com/windsurf), install and open.

**Add AKOOL MCP**

Go to **Windsurf Settings** → **MCP** → **Add Server**, or edit `~/.codeium/windsurf/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "akool-mcp": {
      "type": "http",
      "url": "https://openapi.akool.com/mcp/v1",
      "headers": {
        "x-client-id": "YOUR_CLIENT_ID",
        "x-client-secret": "YOUR_CLIENT_SECRET"
      }
    }
  }
}
```

Restart Windsurf and open the **Cascade** panel. AKOOL tools will be listed under available tools.

***

### OpenAI Codex

**Install**

```bash theme={null}
npm install -g @openai/codex
```

**Add AKOOL MCP**

Edit `~/.codex/config.toml`:

```toml theme={null}
[mcp_servers.akool-mcp]
url = "https://openapi.akool.com/mcp/v1"
http_headers = { "x-client-id" = "YOUR_CLIENT_ID", "x-client-secret" = "YOUR_CLIENT_SECRET" }
```

Codex will automatically load MCP servers on startup.

***

### Kiro

**Install**

Download from [kiro.dev](https://kiro.dev), install and open.

**Add AKOOL MCP**

Create or edit `~/.kiro/settings/mcp.json` (global) or `.kiro/settings/mcp.json` in your project root:

```json theme={null}
{
  "mcpServers": {
    "akool-mcp": {
      "type": "http",
      "url": "https://openapi.akool.com/mcp/v1",
      "headers": {
        "x-client-id": "YOUR_CLIENT_ID",
        "x-client-secret": "YOUR_CLIENT_SECRET"
      }
    }
  }
}
```

Restart Kiro. In the **Agent** panel, AKOOL tools will be listed under **MCP Tools**.

***

## Usage Examples

Once configured, describe tasks in natural language:

**Face swap (image)**

```
Swap the face in source.jpg onto target.jpg using AKOOL, save the result URL
```

**Face swap (video)**

```
Use AKOOL to swap the face from face.jpg onto video.mp4, then wait for the result
```

**Enhanced face swap**

```
Use AKOOL faceswap_plus to swap multiple faces in group.jpg with the source face
```

**Generate image**

```
Ask AKOOL to generate an image: cinematic portrait of an astronaut on Mars, golden hour
```

**Image to video**

```
Use AKOOL to turn hero.jpg into a video clip with the "zoom" effect
```

**Text to speech**

```
List available AKOOL voices, then convert this script to speech using a female English voice:
"Welcome to our annual product showcase."
```

**Face detection**

```
Use AKOOL to detect all faces in photo.jpg and return their bounding boxes
```

**Check account**

```
Check my AKOOL credit balance and list available AI models
```

***

## Tips

* Never commit `x-client-id` / `x-client-secret` to source control. Store them in environment variables and reference via your MCP client's env substitution (e.g. `$AKOOL_CLIENT_ID`).
* Run `akool-cli credit` first to confirm your credentials are valid before configuring any MCP client.
* Most AKOOL tools are **async** — the assistant will call `*_result` tools automatically to poll until the job completes.
* If a tool call returns `401 Unauthorized`, verify credentials at the [AKOOL dashboard](https://akool.com/workspace/current/api/credentials).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.