MCP Integration

Documentation by X-Pilot

Connect your assistant

1. Open connector settings

In your AI tool, open the MCP or Connectors settings and choose to add a custom (remote) server.

2. Paste the MCP URL

Name it X Pilot and paste the URL below. Transport: Streamable HTTP. Click Connect, sign in to X Pilot and approve the requested access. No API key is needed, and you can disconnect at any time from the developer console.

4. Start creating

Ask for a video in plain language. Generation uses your existing credits, exactly like the web app.

https://mcp.x-pilot.ai/mcp

Use the actual deployment URL shown in your Developer Console.

Client setup

Pick your AI tool for the exact place to add X Pilot and how to sign in.

Name  X Pilot
URL   https://mcp.x-pilot.ai/mcp

Works in Claude on the web and desktop. Click Connect, then sign in and approve on the X Pilot page. On Team and Enterprise plans an owner adds the connector first.

{
  "mcpServers": {
    "x-pilot": {
      "url": "https://mcp.x-pilot.ai/mcp"
    }
  }
}

Click Add to Cursor or save this to mcp.json. Then open Settings → MCP and click Connect next to x-pilot to sign in.

claude mcp add --transport http x-pilot https://mcp.x-pilot.ai/mcp

Run this once, then type /mcp inside Claude Code, choose x-pilot and Authenticate.

codex mcp add x-pilot --url https://mcp.x-pilot.ai/mcp
codex mcp login x-pilot

The second command opens the browser to sign in. Restart Codex if the tools do not appear.

code --add-mcp '{"name":"x-pilot","type":"http","url":"https://mcp.x-pilot.ai/mcp"}'

Or add the same server to .vscode/mcp.json. VS Code asks you to sign in the first time the agent uses it.

gemini mcp add --transport http x-pilot https://mcp.x-pilot.ai/mcp

Then run /mcp auth x-pilot inside Gemini CLI to sign in.

API key fallback

Use an API Key when a client does not support OAuth, or for CI and servers. Create the key in the developer console and keep it in the XPILOT_API_KEY environment variable — never paste it into a config file or repository. The key’s scopes and monthly budget still apply.

Cursor · ~/.cursor/mcp.json

{
  "mcpServers": {
    "x-pilot": {
      "url": "https://mcp.x-pilot.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XPILOT_API_KEY}"
      }
    }
  }
}

Codex · Terminal

codex mcp add x-pilot --url https://mcp.x-pilot.ai/mcp --bearer-token-env-var XPILOT_API_KEY

Tool reference

These 31 definitions come from the same tool registry used by the MCP server. Available tools depend on your granted scopes. Upload file bytes through REST assets.

check_credits

Read the shared wallet balance in credits. Call before paid operations.Scope: account:read

{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}

check_capacity

Read available concurrency slots and the remaining monthly budget of this credential. Call before create_conversation or send_message.Scope: account:read

{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}

list_conversations

List owned video conversations, newest first. status is one of queued, running, stopping, paused, completed, failed, stopped; next_action tells what a paused conversation needs. Times are Unix seconds.Scope: video_agents:read

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Items per page. Default 20."
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "description": "Items to skip. Default 0."
    }
  },
  "required": [],
  "additionalProperties": false
}

get_conversation

Read one conversation summary with status, next_action, cost_credits and preview_video_url. Use list_messages for per-message detail.Scope: video_agents:read

{
  "type": "object",
  "properties": {
    "conversation_id": {
      "type": "string",
      "minLength": 1,
      "description": "conversation_id returned by create_conversation or list_conversations."
    }
  },
  "required": [
    "conversation_id"
  ],
  "additionalProperties": false
}

create_conversation

Create a video conversation and start the first paid message immediately. Check credits and capacity first. Outline modes: by default (require_outline_confirmation omitted or false) the video is generated straight through without pausing. With require_outline_confirmation=true the message pauses with status=paused and next_action=confirm_outline; show the returned outline to the user, then call send_message with outline_action=confirm (no prompt needed) or outline_action=revise plus a prompt describing the change. Poll list_messages every 5 seconds or more; there is no streaming. Billing matches the app: the platform reserve is held, released at the end, then actual usage is charged (clamped to the balance). cost_credits is the held reserve until the message settles, then the actual charge.Scope: video_agents:write

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20000,
      "description": "The lesson or video brief: audience, goal, then # title and ## sections with concrete facts, numbers, formulas, dates or ordered steps. Do not name visual components."
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 8,
      "maxLength": 128,
      "pattern": "^[\\w.:-]{8,128}$",
      "description": "Retry key for this conversation. Generate a UUID once and reuse it only when retrying the same input; a different input with the same key is rejected. Never ask the user for it."
    },
    "require_outline_confirmation": {
      "type": "boolean",
      "description": "Default false (generate straight through). Set true only when the user wants to review the outline first."
    },
    "video_config": {
      "type": "object",
      "description": "Video settings applied when the conversation is created. They cannot be changed by send_message.",
      "properties": {
        "target_language": {
          "type": "string",
          "pattern": "^[A-Za-z]{2,3}([-_][A-Za-z0-9]{2,8})*$",
          "description": "Narration and subtitle language as an ISO 639-1 code or BCP-47 tag, for example en, zh or zh-CN. Default en. Decide before creating; changing it later means a new video."
        },
        "video_duration": {
          "type": "string",
          "enum": [
            "short",
            "deep",
            "long"
          ],
          "description": "short: 1–3 minutes (default). deep: 3–10 minutes. long: 10–20 minutes."
        },
        "video_style": {
          "type": "string",
          "enum": [
            "auto",
            "clean_lecture",
            "science_explainer",
            "professional_training",
            "product_showcase",
            "cinematic_story"
          ],
          "description": "auto (default) lets the agent choose. clean_lecture: courses. science_explainer: science processes. professional_training: workplace training. product_showcase: product demos. cinematic_story: history and narrative."
        },
        "voice_id": {
          "type": "string",
          "description": "Narration voice id from list_voices. Default picks a voice for target_language."
        },
        "voice_version": {
          "type": "integer",
          "enum": [
            1,
            2
          ],
          "description": "Version of voice_id: 1 (Voice I, default) or 2. Requires voice_id."
        },
        "locale": {
          "type": "string",
          "description": "Optional native locale of voice_id, for example en-US. Requires voice_id."
        },
        "avatar_id": {
          "type": [
            "string",
            "integer"
          ],
          "description": "Presenter avatar id from list_avatars. The avatar must have selectable=true; otherwise create fails with avatar_not_ready."
        },
        "brand_kit_id": {
          "type": [
            "string",
            "integer"
          ],
          "description": "Brand kit id from list_brand_kits for colors, logo and tone."
        },
        "enable_initial_ai_video": {
          "type": "boolean",
          "description": "Generate an AI opening clip when the plan allows it. Default false."
        }
      },
      "additionalProperties": false
    },
    "files": {
      "type": "array",
      "maxItems": 5,
      "description": "Up to 5 attachments. Each item uses an owned asset_id or a caller-supplied public http(s) URL. Third-party URLs are archived to the caller’s storage before use.",
      "items": {
        "type": "object",
        "description": "An attachment with asset_id or a public url and its own role.",
        "properties": {
          "asset_id": {
            "type": [
              "string",
              "integer"
            ],
            "description": "id returned by POST /v1/assets or list_assets."
          },
          "url": {
            "type": "string",
            "pattern": "^https?://",
            "description": "Caller-supplied public http(s) URL. Third-party content is archived before use."
          },
          "name": {
            "type": "string",
            "maxLength": 255,
            "description": "Optional display name; inferred from the source when omitted."
          },
          "type": {
            "type": "string",
            "enum": [
              "document",
              "image",
              "video"
            ],
            "description": "Optional; inferred from the file when omitted."
          },
          "files_role": {
            "type": "string",
            "enum": [
              "primary",
              "reference"
            ],
            "description": "How this file shapes the video: primary or reference. Omit to let the agent decide."
          }
        },
        "additionalProperties": false
      }
    },
    "callback_url": {
      "type": "string",
      "maxLength": 2048,
      "description": "Optional public HTTPS URL notified once when this message reaches completed, paused, failed or stopped. Signed with the workspace callback secret (X-XPilot-Signature). Only set it when the user runs a receiving service."
    },
    "callback_id": {
      "type": "string",
      "pattern": "^[\\w.:-]{1,128}$",
      "description": "Optional reference echoed back as data.callback_id. Requires callback_url."
    }
  },
  "required": [
    "prompt",
    "idempotency_key"
  ],
  "additionalProperties": false
}

send_message

Send a follow-up turn to a conversation that is not running. Paid. Use it to edit the video, answer the assistant (next_action=reply), or confirm/revise the outline (next_action=confirm_outline). Outline modes: by default (require_outline_confirmation omitted or false) the video is generated straight through without pausing. With require_outline_confirmation=true the message pauses with status=paused and next_action=confirm_outline; show the returned outline to the user, then call send_message with outline_action=confirm (no prompt needed) or outline_action=revise plus a prompt describing the change. video_config cannot be changed here.Scope: video_agents:write

{
  "type": "object",
  "properties": {
    "conversation_id": {
      "type": "string",
      "minLength": 1,
      "description": "conversation_id returned by create_conversation or list_conversations."
    },
    "prompt": {
      "type": "string",
      "maxLength": 20000,
      "description": "The instruction or answer. Required unless outline_action=confirm."
    },
    "outline_action": {
      "type": "string",
      "enum": [
        "confirm",
        "revise"
      ],
      "description": "Only when next_action=confirm_outline. confirm continues with the outline; revise needs a prompt describing the change."
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 8,
      "maxLength": 128,
      "pattern": "^[\\w.:-]{8,128}$",
      "description": "Retry key for this message. Generate a UUID once and reuse it only when retrying the same input; a different input with the same key is rejected. Never ask the user for it."
    },
    "files": {
      "type": "array",
      "maxItems": 5,
      "description": "Up to 5 attachments. Each item uses an owned asset_id or a caller-supplied public http(s) URL. Third-party URLs are archived to the caller’s storage before use.",
      "items": {
        "type": "object",
        "description": "An attachment with asset_id or a public url and its own role.",
        "properties": {
          "asset_id": {
            "type": [
              "string",
              "integer"
            ],
            "description": "id returned by POST /v1/assets or list_assets."
          },
          "url": {
            "type": "string",
            "pattern": "^https?://",
            "description": "Caller-supplied public http(s) URL. Third-party content is archived before use."
          },
          "name": {
            "type": "string",
            "maxLength": 255,
            "description": "Optional display name; inferred from the source when omitted."
          },
          "type": {
            "type": "string",
            "enum": [
              "document",
              "image",
              "video"
            ],
            "description": "Optional; inferred from the file when omitted."
          },
          "files_role": {
            "type": "string",
            "enum": [
              "primary",
              "reference"
            ],
            "description": "How this file shapes the video: primary or reference. Omit to let the agent decide."
          }
        },
        "additionalProperties": false
      }
    },
    "callback_url": {
      "type": "string",
      "maxLength": 2048,
      "description": "Optional public HTTPS URL notified once when this message reaches completed, paused, failed or stopped. Signed with the workspace callback secret (X-XPilot-Signature). Only set it when the user runs a receiving service."
    },
    "callback_id": {
      "type": "string",
      "pattern": "^[\\w.:-]{1,128}$",
      "description": "Optional reference echoed back as data.callback_id. Requires callback_url."
    }
  },
  "required": [
    "conversation_id",
    "idempotency_key"
  ],
  "additionalProperties": false
}

list_messages

List messages of a conversation in order. Poll this for status, next_action, outline (when an outline exists), cost_credits and preview_video_url. completed, paused, failed and stopped are terminal for that message.Scope: video_agents:read

{
  "type": "object",
  "properties": {
    "conversation_id": {
      "type": "string",
      "minLength": 1,
      "description": "conversation_id returned by create_conversation or list_conversations."
    }
  },
  "required": [
    "conversation_id"
  ],
  "additionalProperties": false
}

stop_conversation

Stop the running message. Poll list_messages until it is stopped; cost already incurred may still be charged.Scope: video_agents:write

{
  "type": "object",
  "properties": {
    "conversation_id": {
      "type": "string",
      "minLength": 1,
      "description": "conversation_id returned by create_conversation or list_conversations."
    }
  },
  "required": [
    "conversation_id"
  ],
  "additionalProperties": false
}

delete_conversation

Delete an owned conversation and stop any running message. Only when the user asks.Scope: video_agents:write

{
  "type": "object",
  "properties": {
    "conversation_id": {
      "type": "string",
      "minLength": 1,
      "description": "conversation_id returned by create_conversation or list_conversations."
    }
  },
  "required": [
    "conversation_id"
  ],
  "additionalProperties": false
}

list_renders

List MP4 exports of a conversation. status is queued, running, completed, failed or superseded. progress is a 0–100 percentage when known, otherwise null.Scope: video_agents:read

{
  "type": "object",
  "properties": {
    "conversation_id": {
      "type": "string",
      "minLength": 1,
      "description": "conversation_id returned by create_conversation or list_conversations."
    }
  },
  "required": [
    "conversation_id"
  ],
  "additionalProperties": false
}

create_render

Export an MP4 after preview_video_url is available. A preview is not an export. Poll get_render and report its 0–100 progress until completed, then return video_url.Scope: video_agents:write

{
  "type": "object",
  "properties": {
    "conversation_id": {
      "type": "string",
      "minLength": 1,
      "description": "conversation_id returned by create_conversation or list_conversations."
    },
    "message_id": {
      "type": "string",
      "minLength": 1,
      "description": "Message to export. Default: the latest message with a preview."
    },
    "force": {
      "type": "boolean",
      "description": "Re-export even when a completed export exists. Default false."
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 8,
      "maxLength": 128,
      "pattern": "^[\\w.:-]{8,128}$",
      "description": "Retry key for this export. Generate a UUID once and reuse it only when retrying the same input; a different input with the same key is rejected. Never ask the user for it."
    }
  },
  "required": [
    "conversation_id",
    "idempotency_key"
  ],
  "additionalProperties": false
}

get_render

Read one export: status, progress (0–100 or null when unavailable), and video_url when completed.Scope: video_agents:read

{
  "type": "object",
  "properties": {
    "conversation_id": {
      "type": "string",
      "minLength": 1,
      "description": "conversation_id returned by create_conversation or list_conversations."
    },
    "render_id": {
      "type": "string",
      "minLength": 1,
      "description": "render_id returned by create_render or list_renders."
    }
  },
  "required": [
    "conversation_id",
    "render_id"
  ],
  "additionalProperties": false
}

delete_render

Delete an export record. Only when the user asks.Scope: video_agents:write

{
  "type": "object",
  "properties": {
    "conversation_id": {
      "type": "string",
      "minLength": 1,
      "description": "conversation_id returned by create_conversation or list_conversations."
    },
    "render_id": {
      "type": "string",
      "minLength": 1,
      "description": "render_id returned by create_render or list_renders."
    }
  },
  "required": [
    "conversation_id",
    "render_id"
  ],
  "additionalProperties": false
}

list_brand_kits

List owned brand kits. Pass an id as video_config.brand_kit_id.Scope: brand_kits:read

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Items per page. Default 20."
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "description": "Items to skip. Default 0."
    }
  },
  "required": [],
  "additionalProperties": false
}

get_brand_kit

Read one owned brand kit.Scope: brand_kits:read

{
  "type": "object",
  "properties": {
    "brand_kit_id": {
      "type": [
        "string",
        "integer"
      ],
      "description": "Brand kit id returned by list_brand_kits or create_brand_kit."
    }
  },
  "required": [
    "brand_kit_id"
  ],
  "additionalProperties": false
}

create_brand_kit

Create a brand kit for logos, theme colors and tone. Only when the user asks.Scope: brand_kits:write

{
  "type": "object",
  "properties": {
    "brand_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Brand name shown in videos."
    },
    "brand_logo": {
      "type": "string",
      "maxLength": 2048,
      "description": "Logo URL, preferably one returned by POST /v1/assets."
    },
    "content_style_description": {
      "type": "string",
      "maxLength": 20000,
      "description": "Tone and style guidance for scripts, for example \"friendly, concise, avoid jargon\"."
    },
    "theme_color": {
      "type": "object",
      "description": "Theme colors. Each value is #rgb, #rrggbb, #rrggbbaa or rgb()/rgba(); null clears a color.",
      "properties": {
        "primary": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "primary color."
        },
        "secondary": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "secondary color."
        },
        "accent": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "accent color."
        },
        "background": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "background color."
        },
        "text": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "text color."
        },
        "textSecondary": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "textSecondary color."
        },
        "success": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "success color."
        },
        "warning": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "warning color."
        },
        "error": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "error color."
        },
        "surface": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "surface color."
        },
        "surfaceLight": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "surfaceLight color."
        },
        "shadow": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "shadow color."
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "brand_name"
  ],
  "additionalProperties": false
}

update_brand_kit

Update fields of an owned brand kit. Omitted fields stay unchanged.Scope: brand_kits:write

{
  "type": "object",
  "properties": {
    "brand_kit_id": {
      "type": [
        "string",
        "integer"
      ],
      "description": "Brand kit id returned by list_brand_kits or create_brand_kit."
    },
    "brand_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Brand name shown in videos."
    },
    "brand_logo": {
      "type": "string",
      "maxLength": 2048,
      "description": "Logo URL, preferably one returned by POST /v1/assets."
    },
    "content_style_description": {
      "type": "string",
      "maxLength": 20000,
      "description": "Tone and style guidance for scripts, for example \"friendly, concise, avoid jargon\"."
    },
    "theme_color": {
      "type": "object",
      "description": "Theme colors. Each value is #rgb, #rrggbb, #rrggbbaa or rgb()/rgba(); null clears a color.",
      "properties": {
        "primary": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "primary color."
        },
        "secondary": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "secondary color."
        },
        "accent": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "accent color."
        },
        "background": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "background color."
        },
        "text": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "text color."
        },
        "textSecondary": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "textSecondary color."
        },
        "success": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "success color."
        },
        "warning": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "warning color."
        },
        "error": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "error color."
        },
        "surface": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "surface color."
        },
        "surfaceLight": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "surfaceLight color."
        },
        "shadow": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 50,
          "description": "shadow color."
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "brand_kit_id"
  ],
  "additionalProperties": false
}

delete_brand_kit

Delete an owned brand kit. Only when the user asks.Scope: brand_kits:write

{
  "type": "object",
  "properties": {
    "brand_kit_id": {
      "type": [
        "string",
        "integer"
      ],
      "description": "Brand kit id returned by list_brand_kits or create_brand_kit."
    }
  },
  "required": [
    "brand_kit_id"
  ],
  "additionalProperties": false
}

list_assets

List files uploaded to this account, newest first. Upload new files with REST multipart POST /v1/assets (field files, up to 5 files); MCP cannot carry file bytes.Scope: assets:read

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Items per page. Default 20."
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "description": "Items to skip. Default 0."
    }
  },
  "required": [],
  "additionalProperties": false
}

list_avatars

List owned presenter avatars and quota. Only avatars with selectable=true can be used as video_config.avatar_id.Scope: avatars:read

{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}

list_voices

Find public catalog voices or your own clones. Choose voice_id from the returned items; never guess provider identifiers. Use samples on list/detail items for fixed audition clips.Scope: voices:read

{
  "type": "object",
  "properties": {
    "voice_version": {
      "type": "integer",
      "description": "Voice I (1, default) or Voice II (2) for the public catalog. Private clone listings include both versions.",
      "enum": [
        1,
        2
      ]
    },
    "type": {
      "type": "string",
      "description": "public shared catalog or private owned clones.",
      "enum": [
        "public",
        "private"
      ]
    },
    "language": {
      "type": "string",
      "description": "Optional language filter aligned with the platform catalog."
    },
    "page": {
      "type": "integer",
      "description": "Page, starting at 1.",
      "minimum": 1
    },
    "limit": {
      "type": "integer",
      "description": "Items per page, up to 100.",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [],
  "additionalProperties": false
}

get_voice

Read a public or owned voice, including readiness and samples. Private voices from another account are unavailable. Poll this after clone_voice: a Voice II clone moves from training to trained (selectable=true) or failed.Scope: voices:read

{
  "type": "object",
  "properties": {
    "voice_id": {
      "type": "string",
      "description": "Catalog or owned clone voice ID."
    },
    "voice_version": {
      "type": "integer",
      "description": "Voice version of the voice: Voice I (1, default) or Voice II (2).",
      "enum": [
        1,
        2
      ]
    }
  },
  "required": [
    "voice_id"
  ],
  "additionalProperties": false
}

generate_audio

Synthesize up to 1,000 characters with a catalog voice or one of your ready clones, in Voice I or Voice II. voice_version must match the voice. Returns MP3 audio_url (which may be a data URL). Uses platform TTS pricing; reuse the same idempotency_key for retries.Scope: audio:write

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "Spoken text.",
      "minLength": 1,
      "maxLength": 1000
    },
    "voice_id": {
      "type": "string",
      "description": "Catalog voice ID or owned ready clone ID."
    },
    "voice_version": {
      "type": "integer",
      "description": "Voice version of voice_id: Voice I (1, default) or Voice II (2). Never substitute one version for the other.",
      "enum": [
        1,
        2
      ]
    },
    "locale": {
      "type": "string",
      "description": "Speech locale. Voice II catalog voices accept their native or secondary locales; Voice II clones accept the locales they support."
    },
    "speed": {
      "type": "number",
      "description": "Playback speed.",
      "minimum": 0.5,
      "maximum": 2
    },
    "idempotency_key": {
      "type": "string",
      "description": "Retry key for this operation. Generate a UUID once and reuse it only when retrying the same input. Never ask the user for it.",
      "minLength": 8,
      "maxLength": 128,
      "pattern": "^[\\w.:-]{8,128}$"
    }
  },
  "required": [
    "text",
    "voice_id",
    "idempotency_key"
  ],
  "additionalProperties": false
}

get_voice_clone_config

Read Voice II clone requirements before clone_voice with voice_version 2: availability, the authorized company_name, supported locales with the consent_statement the speaker must read aloud, and sample duration/size limits. When voice_ii_available is false (for example voice_ii_unavailable_reason clone_disabled), do not attempt a Voice II clone; offer Voice I instead.Scope: voices:read

{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}

clone_voice

Clone a private voice from audio already uploaded to your account. Voice I (default) is an instant clone from one sample. Voice II needs the speaker’s consent: call get_voice_clone_config, have the speaker record the consent_statement for the chosen locale with their name and company_name filled in, upload it separately, then pass voice_talent_name, locale, consent_audio_url and consent_accepted=true. Never fabricate consent or set consent_accepted without the speaker’s explicit agreement. Voice II returns 403 voice_ii_unavailable while cloning is not open for the account. Poll get_voice until state is trained or failed. Reuse idempotency_key on retry.Scope: audio:write

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Voice title.",
      "minLength": 1,
      "maxLength": 80
    },
    "audio_url": {
      "type": "string",
      "description": "Owned uploaded training audio URL. Voice II: 5–90 seconds of the same speaker."
    },
    "cover_image_url": {
      "type": "string",
      "description": "Optional owned uploaded cover image URL. Voice I only."
    },
    "voice_version": {
      "type": "integer",
      "description": "Voice I (1, default) or Voice II (2, consent-based personal voice).",
      "enum": [
        1,
        2
      ]
    },
    "voice_talent_name": {
      "type": "string",
      "description": "Voice II only: the speaker's name exactly as spoken in the consent recording.",
      "minLength": 1,
      "maxLength": 128
    },
    "locale": {
      "type": "string",
      "description": "Voice II only: recording locale from get_voice_clone_config, for example en-US or zh-CN.",
      "maxLength": 16
    },
    "consent_audio_url": {
      "type": "string",
      "description": "Voice II only: owned uploaded recording of the speaker reading the consent_statement for locale. Must be a separate file from audio_url, at most 90 seconds."
    },
    "consent_accepted": {
      "type": "boolean",
      "description": "Voice II only: true when the speaker has explicitly agreed that their voice may be cloned. Required for Voice II."
    },
    "idempotency_key": {
      "type": "string",
      "description": "Retry key for this operation. Generate a UUID once and reuse it only when retrying the same input. Never ask the user for it.",
      "minLength": 8,
      "maxLength": 128,
      "pattern": "^[\\w.:-]{8,128}$"
    }
  },
  "required": [
    "name",
    "audio_url",
    "idempotency_key"
  ],
  "additionalProperties": false
}

delete_voice

Delete an owned cloned voice. Public catalog voices cannot be deleted. Reuse idempotency_key on retry.Scope: audio:write

{
  "type": "object",
  "properties": {
    "voice_id": {
      "type": "string",
      "description": "Owned clone voice ID."
    },
    "idempotency_key": {
      "type": "string",
      "description": "Retry key for this operation. Generate a UUID once and reuse it only when retrying the same input. Never ask the user for it.",
      "minLength": 8,
      "maxLength": 128,
      "pattern": "^[\\w.:-]{8,128}$"
    }
  },
  "required": [
    "voice_id",
    "idempotency_key"
  ],
  "additionalProperties": false
}

get_avatar

Read an owned avatar. status is the overall state (draft, generating, ready, failed, deleting, migration_required); training_status and preview_status track training and the preview sample; selectable must be true before video generation can use it; stage names the step in progress (queued, generating_training_video, provider_processing, generating_preview, deleting_provider_asset) or null when idle; error is {code, message} on failure. Training ready alone does not mean it can be used in a video.Scope: avatars:read

{
  "type": "object",
  "properties": {
    "avatar_id": {
      "type": "string",
      "description": "Owned avatar ID."
    }
  },
  "required": [
    "avatar_id"
  ],
  "additionalProperties": false
}

create_avatar

Create an avatar from an owned asset_id or a public http(s) image/video URL. Third-party URLs are downloaded and archived to the caller’s owned storage before training. Requires platform entitlement. Poll get_avatar for preview_image_url and preview_video_url, or receive avatar.completed / avatar.failed through callback_url or a webhook subscription. Reuse idempotency_key on retry; never retrain automatically.Scope: avatars:write

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Avatar name.",
      "minLength": 1,
      "maxLength": 80
    },
    "avatar_type": {
      "type": "string",
      "description": "Training source.",
      "enum": [
        "human_video",
        "virtual_character"
      ]
    },
    "asset_id": {
      "type": "string",
      "description": "Owned asset ID returned by POST /v1/assets. human_video uses a video asset; virtual_character uses an image asset."
    },
    "image_url": {
      "type": "string",
      "description": "Public http(s) image URL. The backend archives third-party content to your owned storage before training. Use this or asset_id for virtual_character."
    },
    "video_url": {
      "type": "string",
      "description": "Public http(s) training video URL. The backend archives third-party content to your owned storage before training. Use this or asset_id for human_video."
    },
    "gender": {
      "type": "string",
      "description": "Required for image avatars.",
      "enum": [
        "Male",
        "Female"
      ]
    },
    "callback_url": {
      "type": "string",
      "description": "Optional public HTTPS URL notified once with avatar.completed or avatar.failed. Signed with the workspace callback secret (X-XPilot-Signature). Only set it when you run a receiving service.",
      "maxLength": 2048
    },
    "callback_id": {
      "type": "string",
      "description": "Optional reference echoed back as data.callback_id. Requires callback_url.",
      "maxLength": 128,
      "pattern": "^[\\w.:-]{1,128}$"
    },
    "idempotency_key": {
      "type": "string",
      "description": "Retry key for this operation. Generate a UUID once and reuse it only when retrying the same input. Never ask the user for it.",
      "minLength": 8,
      "maxLength": 128,
      "pattern": "^[\\w.:-]{8,128}$"
    }
  },
  "required": [
    "name",
    "avatar_type",
    "idempotency_key"
  ],
  "additionalProperties": false
}

delete_avatar

Delete an owned avatar. Poll get_avatar or list_avatars until it disappears. Reuse idempotency_key on retry.Scope: avatars:write

{
  "type": "object",
  "properties": {
    "avatar_id": {
      "type": "string",
      "description": "Owned avatar ID."
    },
    "idempotency_key": {
      "type": "string",
      "description": "Retry key for this operation. Generate a UUID once and reuse it only when retrying the same input. Never ask the user for it.",
      "minLength": 8,
      "maxLength": 128,
      "pattern": "^[\\w.:-]{8,128}$"
    }
  },
  "required": [
    "avatar_id",
    "idempotency_key"
  ],
  "additionalProperties": false
}

create_avatar_video

Synthesize a talking-presenter video with an owned avatar whose training_status is ready. Drive it with text + voice_id (platform TTS, Voice I or Voice II) or with your own speech audio (asset_id or a public http(s) audio_url) — exactly one source, up to 5 minutes of speech. Output is a transparent-background WebM (VP9 with alpha) for compositing. Billed per rendered second at the digital-human video rate; the balance must cover the estimate before dispatch. Poll get_avatar_video, or receive avatar-video.completed / avatar-video.failed through callback_url or a webhook subscription. Reuse idempotency_key on retry; never resubmit automatically.Scope: avatars:write

{
  "type": "object",
  "properties": {
    "avatar_id": {
      "type": "string",
      "description": "Owned avatar ID with training_status ready."
    },
    "text": {
      "type": "string",
      "description": "Spoken text for platform TTS. Use with voice_id; omit when sending audio.",
      "minLength": 1,
      "maxLength": 5000
    },
    "voice_id": {
      "type": "string",
      "description": "Catalog voice ID or owned ready clone ID from list_voices. Required with text."
    },
    "voice_version": {
      "type": "integer",
      "description": "Voice version of voice_id: Voice I (1, default) or Voice II (2).",
      "enum": [
        1,
        2
      ]
    },
    "locale": {
      "type": "string",
      "description": "Optional native locale for the voice."
    },
    "speed": {
      "type": "number",
      "description": "TTS playback speed.",
      "minimum": 0.5,
      "maximum": 2
    },
    "audio_url": {
      "type": "string",
      "description": "Public http(s) speech audio URL (≤20 MB). The backend archives third-party audio to your owned storage first. Use this or asset_id instead of text."
    },
    "asset_id": {
      "type": "string",
      "description": "Owned audio asset ID returned by POST /v1/assets. Use this or audio_url instead of text."
    },
    "callback_url": {
      "type": "string",
      "description": "Optional public HTTPS URL notified once with avatar-video.completed or avatar-video.failed. Signed with the workspace callback secret (X-XPilot-Signature). Only set it when you run a receiving service.",
      "maxLength": 2048
    },
    "callback_id": {
      "type": "string",
      "description": "Optional reference echoed back as data.callback_id. Requires callback_url.",
      "maxLength": 128,
      "pattern": "^[\\w.:-]{1,128}$"
    },
    "idempotency_key": {
      "type": "string",
      "description": "Retry key for this operation. Generate a UUID once and reuse it only when retrying the same input. Never ask the user for it.",
      "minLength": 8,
      "maxLength": 128,
      "pattern": "^[\\w.:-]{8,128}$"
    }
  },
  "required": [
    "avatar_id",
    "idempotency_key"
  ],
  "additionalProperties": false
}

get_avatar_video

Read an avatar video job: status (queued, processing, completed, failed), video_url (transparent WebM) once completed, duration_seconds, width, height and the settled cost_credits. Poll at least 5 seconds apart.Scope: avatars:read

{
  "type": "object",
  "properties": {
    "avatar_id": {
      "type": "string",
      "description": "Owned avatar ID."
    },
    "video_id": {
      "type": "string",
      "description": "Video ID returned by create_avatar_video."
    }
  },
  "required": [
    "avatar_id",
    "video_id"
  ],
  "additionalProperties": false
}

Access and billing

The sign-in page shows the account and the access being granted. Tokens only work for the X Pilot MCP server; access tokens last one hour and refresh automatically.
Disconnect a client any time from Developer console → Connected AI. Tasks already running continue.
MCP uses the same wallet as the web app: credits are reserved when a task starts, released when it ends, and the actual usage is charged. A task never takes your balance below zero.
The AI sees only the tools allowed by the access you approved. Upload files with REST POST /v1/assets.

Download MCP schemas.

Get started

Agent Skills

MCP Integration

Connect your assistant

1. Open connector settings

2. Paste the MCP URL

4. Start creating

Client setup

API key fallback

Cursor · ~/.cursor/mcp.json

Codex · Terminal

Tool reference

Access and billing

​Connect your assistant

​1. Open connector settings

​2. Paste the MCP URL

​3. Sign in with OAuth

​4. Start creating

​Client setup

​API key fallback

​Cursor · ~/.cursor/mcp.json

​Codex · Terminal

​Tool reference

​Access and billing

Connect your assistant

1. Open connector settings

2. Paste the MCP URL

3. Sign in with OAuth

4. Start creating

Client setup

API key fallback

Cursor · ~/.cursor/mcp.json

Codex · Terminal

Tool reference

Access and billing