MCP - Akool open api documents

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.

Using ChatGPT, Claude, Claude Code or Codex? Sign in with your AKOOL account instead of using API credentials. See Plugin.

Credentials

MCP uses the same credentials as the CLI. Get them from your AKOOL dashboard:

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

Server Config

{
  "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

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

Claude Code

Install

npm install -g @anthropic-ai/claude-code

Add AKOOL MCP

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:

claude mcp list
# akool-mcp   http   https://openapi.akool.com/mcp/v1

Claude Desktop

Install Download and install from claude.ai/download. Add AKOOL MCP

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

Cursor

Install Download from cursor.com, install and open. Add AKOOL MCP Go to Settings → MCP → Add new global MCP server, or edit ~/.cursor/mcp.json:

{
  "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, install and open. Add AKOOL MCP Go to Windsurf Settings → MCP → Add Server, or edit ~/.codeium/windsurf/mcp_config.json:

{
  "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

npm install -g @openai/codex

Add AKOOL MCP Edit ~/.codex/config.toml:

[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, install and open. Add AKOOL MCP Create or edit ~/.kiro/settings/mcp.json (global) or .kiro/settings/mcp.json in your project root:

{
  "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.

​Overview

​Credentials

​Server Config

​Available Tools

​Setup Guides

​Claude Code

​Claude Desktop

​Cursor

​Windsurf

​OpenAI Codex

​Kiro

​Usage Examples

​Tips

Overview

Credentials

Server Config

Available Tools

Setup Guides

Claude Code

Claude Desktop

Cursor

Windsurf

OpenAI Codex

Kiro

Usage Examples

Tips