---
title: MCP tools
description: Reference for 10 core and 5 capability-dependent Clipia MCP tools for AI agents, plus 7 app-only helpers for interactive result cards.
---
Clipia MCP always exposes 10 core tools to the AI agent plus seven app-only helpers that stay outside the model context. `chat`, `generate_scenario`, `compose_video`, `generate_presentation` and `edit_presentation` are added only when their capabilities are enabled. Every generate call returns its cost in credits; `get_balance` reports the remaining balance. Check the live [MCP server card](https://clipia.ai/.well-known/mcp/server-card.json) for the current runtime tool list.
`generate_image` / `generate_video` submits the job. If the response is non-terminal (status `IN_QUEUE` / `IN_PROGRESS`), call `wait_generation` with the `request_id` until status `COMPLETED`. Images often come back ready in a single call; video renders in 1–10 minutes.
## Reference
| Tool | Purpose | Key parameters |
| --- | --- | --- |
| `generate_image` | Image from text or editing by reference. Usually returns a finished result in a single call, with a preview | `prompt`, `model` (opt.), `image_url` (opt., I2I), `num_images` (1–4), `seed` |
| `generate_video` | Video from text or a start frame (image-to-video). Returns `request_id` and cost immediately | `prompt`, `model` (opt.), `image_url` (opt., switches to I2V), `seed` |
| `generate_audio` | Text-to-speech with a selected voice and language. Returns an MP3 when complete | `text`, `model` (opt.), `voice` (opt.), `language` (opt.) |
| `generate_music` | Background music or a soundtrack from a mood, genre and tempo description | `prompt`, `model` (opt.), `instrumental` (opt.) |
| `wait_generation` | Long-poll until a terminal status (≤30s per call) | `request_id` |
| `get_generation` | Instant status and result: webp preview + full-quality `original_url` | `request_id`, `include_preview` (opt.) |
| `list_models` | Model catalog: slug, type, capabilities, price in credits | `type` (opt.), `search` (opt.) |
| `get_model` | A model's parameters (`input_schema`) and price | `model` |
| `get_balance` | Credit balance and 30-day usage for the key | — |
| `search_templates` | Hybrid search over 3500+ prompts exposed to MCP from the wider template library (RU/EN) | `query`, `limit` (opt.) |
## Capability-dependent agent tools
| Tool | Purpose | Availability |
| --- | --- | --- |
| `chat` | Chat with a text model and return reply text, usage and credit cost | LLM gateway enabled |
| `generate_scenario` | Turn a video brief into structured scenes, English generation prompts and a soundtrack prompt | LLM gateway enabled |
| `compose_video` | Join 2–20 finished video scenes with optional narration, music and subtitles | Server-side composition enabled |
| `generate_presentation` | Create a new editable PPTX, PDF and PNG previews from a deck specification | Presentation generation enabled |
| `edit_presentation` | Edit an existing deck and reuse illustrations that did not change | Presentation generation enabled |
## App-only helpers
These seven helpers power interactive result, rerun and composition cards. They are hidden from the model and do not consume the AI agent's tool context.
| Tool | Purpose |
| --- | --- |
| `app_get_generation` | Poll one generation from a live result card |
| `app_get_generations` | Poll several generation cards in one request |
| `app_get_rerun_options` | Load safe rerun settings for a finished generation |
| `app_rerun_generation` | Rerun from an interactive card after explicit user action |
| `app_get_compose_editor` | Load the composition editor state |
| `app_recompose_video` | Rebuild a composed video after an explicit edit |
| `app_report_event` | Report card lifecycle and interaction events |
## Descriptions
**generate_image** — text-to-image and image-to-image by reference (`image_url`). The `num_images` parameter (1–4) returns several variants as a single tiled result. Set `seed` for reproducibility.
**generate_video** — text-to-video and image-to-video; passing `image_url` switches the default to an I2V model. Video has no batch — for multiple variants make separate calls with a different `seed` each.
**generate_audio** — text-to-speech with a selected voice and language. When status reaches `COMPLETED`, the MP3 is available at `output.audio.url`; its `request_id` can be used as `voiceover_request_id` in `compose_video` when that tool is enabled.
**generate_music** — creates background music or a soundtrack from a text description. It is instrumental by default; the completed MP3 is available at `output.audio.url`.
**wait_generation** — waits for an active generation to finish; call it between other work until the status becomes terminal.
**get_generation** — an instant snapshot of status and result with no waiting: an optimized webp preview plus an `original_url` for downloading full quality.
**list_models** / **get_model** — the model catalog with prices and capabilities, and the detailed parameter schema of a specific model.
**get_balance** — remaining credits and 30-day usage for the current key.
**search_templates** — hybrid (full-text + semantic) search over the library of ready-made prompts in Russian and English.
`chat` and `generate_scenario` are available when the LLM gateway is enabled; `compose_video` requires server-side composition; `generate_presentation` and `edit_presentation` require Presentation Agent. They are not part of the 10 core tools.
Video models work best with English prompts (Russian is fine for images). Don't bake on-screen text into a video prompt — it renders with artifacts; overlay captions in post instead. For a static camera add "static locked camera, no zoom, no pan".
A key prefixed `clipia_test_` puts every tool in test mode: `generate_image` / `generate_video` return a deterministic mock result instantly and charge no credits. It is handy for debugging polling and response parsing in CI; use a `clipia_live_` key for real generations.
The server address and client setup are in [Use Clipia with AI agents](/en/docs/mcp).