AI agents

MCP server

Point an MCP client at this site and send your partner API key. The client calls tools for characters, voices, estimates, and videos — quoting, idempotency, and polling follow the same rules as the REST API.

What it is

This site serves an MCP server at /mcp. Connect a client with your partner API key and it calls these tools instead of raw HTTP. A tool result is the API's JSON. When a call fails, that JSON includes error_code and message.

The key is the same pmat_…bearer token as the rest of the API. Send it on every request, and don't paste it into a chat. See Authentication for how keys are issued and replaced.

Connect a client

Copy your key

Reveal it in the partner dashboard. The whole pmat_… string is the credential.

Add the server

Give the client this URL and header. Put the key in the client config or in an environment variable.

Remote MCP server

{
  "mcpServers": {
    "promoat": {
      "url": "https://platform.promoat.ai/mcp",
      "headers": {
        "Authorization": "Bearer pmat_…"
      }
    }
  }
}

Check the connection

Call get_balance. That is GET /usage/summary — free, and a 401 means the key is missing or wrong.

Tools

Tool	What it does
`get_balance`	Credit balance and usage in a date range
`list_characters`	List your characters
`get_character`	Get a character
`create_character`	Create a character from selfies, or invent one from a description
`regenerate_character`	Re-render a character's sheet with an optional tweak
`delete_character`	Delete a character
`list_voice_presets`	List the studio voices
`list_voices`	List your voices
`clone_voice`	Clone a voice from samples, or pick a studio voice
`reclone_voice`	Clone a voice again from new samples (a new voice_id)
`delete_voice`	Delete a voice
`synthesize_speech`	Synthesize speech with one of your own voices
`create_first_frame`	Generate a 9:16 still of a character
`plan_scenes`	Preview the scenes a script will become (free)
`estimate_video`	Price a video request without queueing it
`create_video`	Queue a talking-head or scene video
`get_job`	Poll a job's status
`get_scenes`	The scenes of a finished video
`fix_scene`	Fix one scene (makes a new video)
`edit_script`	Give scenes new lines in the video's voice (makes a new video)
`fix_sound`	Put a new voice take on a video (makes a new video)
`list_assets`	List everything you've generated
`get_asset`	Get one asset
`list_jobs`	Paginated job history

create_video, fix_scene, edit_script, and fix_sound take idempotency_key. The server sends it as the Idempotency-Key header. Field names match /openapi.yaml.

Make a video

Confirm the key

get_balance. Note credits_balance.

Character and voice

Reuse an existing id, or create one with create_character and clone_voice. See Characters and Voices.

Quote, then queue

Call estimate_video with the exact request you will send. Then call create_video with that same request, expected_credits set to credits_required, and a fresh idempotency_key. The tool returns a workflow_id at once — it does not wait for the video. Prices are on Credits & pricing.

Poll and deliver

Call get_job until completed or failed, then hand over video_url. Polling, phases, and failure codes are on Jobs & polling.

The key spends real credits

A client holding your key can charge your balance. Keep it in the client config or an environment variable, and ask Promoat support to replace it if it leaks. Quote with estimate_video before create_video or an edit.

← PreviousAI agent skill Next →Changelog