Docs / Reference
MCP tool reference
12 minute read · Updated 2026-09-11
The complete tool surface, grouped by folder. This page is generated from the same registry the server registers at runtime, so it cannot drift from what your client actually sees.
01
How to read this
Each folder below is a toolset — a group you can enable or ignore independently. Within a folder, the mode tells you how the tool behaves when called.
| Mode | Behaviour |
|---|---|
| sync | Returns its result directly. Reads, record writes, single-image generation. |
| job | Returns { job_id, kind } and runs on the render worker. Poll get_job until status is completed. |
Input schemas are published by the server itself: call tools/list, or let your MCP client show them. They are not duplicated here, because a schema copied into prose is a schema that goes stale.
02
The registry
129 tools · 12 folders · generated from the running server
Jobs
jobs3 tools · always enabledPoll and cancel background jobs (pipelines, renders). Always available.
| Tool | Mode | Description |
|---|---|---|
list_jobs | sync | List currently running or pending pipeline jobs (visible in the JobDock). Returns job ids needed to cancel. |
get_job | sync | Polls studio_pipeline_jobs for a single job. Returns status, latest log event, result, and error. |
cancel_job | sync | Request cancellation of a running pipeline job. The pipeline aborts at its next progress checkpoint (usually within a few seconds). Use list_jobs first if you need the job_id. |
Library
library30 toolsArtists, songs, section favorites, artstyles — find / read / update.
| Tool | Mode | Description |
|---|---|---|
delete_song | sync | Delete a song with its audio, lyrics and timings. Videos and images already made for it stay in the library. |
list_artists | sync | List every artist in the library. |
list_songs | sync | List songs for an artist (or all songs if neither input nor context carries one). |
find_song | sync | Case-insensitive substring match against song titles. Returns minimal fields. |
get_song | sync | Fetch the full song record by id. |
find_song_cover | sync | Returns the most recent MediaAsset linked to the song whose name starts with "cover_" (1:1 cover art). |
list_media_assets | sync | List media assets with optional filters (artist, type, song, idea). |
list_song_assets | sync | List image OR video assets linked to a song. |
list_media_assets_paginated | sync | Paginated listing with optional filters. Useful when total > a few hundred. |
get_media_asset | sync | Fetch a single MediaAsset record by id. |
list_videos | sync | List publishable video assets in the artist library (excludes raw clips). |
list_images | sync | List ready image assets (for use in video pipelines). |
list_clips | sync | List raw clip assets (clip_*). Use with start_clip_assembly. |
list_pillars | sync | List content pillars for an artist. |
get_pillar | sync | Get a pillar. |
create_pillar | sync | Create content pillar. |
update_pillar | sync | Update pillar. |
list_campaigns | sync | List campaigns for an artist. |
get_campaign | sync | Get a campaign. |
create_campaign | sync | Create campaign. |
update_campaign | sync | Update campaign. |
list_briefs | sync | List content briefs. |
get_brief | sync | Get a content brief. |
create_brief | sync | Create content brief. |
update_brief | sync | Update content brief. |
list_song_section_favorites | sync | List a song's saved waveform regions (start/end seconds + optional name). Returns ids you can pass to start_studio_with_favorites. |
create_song_section_favorite | sync | Save a waveform region for a song. Returns the new favorite record. |
update_song_section_favorite | sync | Rename or retime a saved waveform region. |
delete_song_section_favorite | sync | Delete a saved waveform region. |
start_studio_with_favorites | job | Run the full studio pipeline using saved favorite sections as the snippet regions. Music Director is skipped. Returns { job_id } — poll get_job until done. |
Generation
generation20 toolsStudio pipelines, lyric videos, boomerangs, quick + clip-assembly video.
| Tool | Mode | Description |
|---|---|---|
run_plan_video | job | Planned video: for each song region you pick, animate its images into clips (org default video model, or video_model) and assemble them over the song. The storyboard flow in the app. Reserves credits up front; background job — returns { job_id }; poll get_job. |
generate_image | sync | Uses the configured image provider (Imagen/Nano Banana/GPT Image 2) to produce one image and saves it as a MediaAsset. |
extend_image | sync | Resize or AI-extend an existing image asset into a different aspect ratio. Use "resize" for instant center-crop/letterbox (free, lossy); use "ai_extend" for outpainting that fills new areas with continued scene (Nano Banana, ~15s, paid). Saves a new image asset with source_asset_id lineage. |
preview_cover_image | sync | Generate a cover image preview (square 1:1, no storage). Returns base64 image and enhanced prompt — user accepts before save_cover_image stores it. |
save_cover_image | sync | Save an accepted cover image (upscales to 3000×3000). |
preview_photo_studio | sync | Platform-specific image preview (Spotify avatar/header/canvas, YouTube thumbnail/background). Returns base64 — no DB write yet. |
save_photo_studio | sync | Save an accepted Photo Studio image (resized to exact platform spec). |
run_studio_pipeline_inline | job | Multi-agent pipeline: brand strategist → creative director → storyboard → art director → image generation → motion director → image-to-video (org default video model, or video_model) → assembly → copywriter posts. Runs as a background job — returns { job_id }; poll get_job until done. |
start_code_video | job | Code video: an AI artist writes the video as code (canvas / WebGL / three.js), driven by the song window's measured beats, energy bands, sections and word-timed lyrics; it renders stills, a critic reviews them, it revises, then the full render is saved to the library with the song muxed in. mode=hybrid also generates images/clips and composites them. Runs as a background job — returns { job_id }; poll get_job. Takes several minutes. |
run_quick_video_inline | job | Lightweight pipeline: ordered images → image-to-video motion (org default video model, or video_model) → audio mux. clip_duration_seconds=5 (15s preset) or 10 (30s preset). Runs as a background job — returns { job_id }; poll get_job until done. |
run_clip_assembly_inline | job | Stitches existing video clips (ordered) into one or more output videos with audio. Runs as a background job — returns { job_id }; poll get_job until done. |
run_youtube_static_inline | job | Loops a single image for the full song length and muxes audio. Faster than boomerang (~1–2 min). Runs as a background job — returns { job_id }; poll get_job until done. |
run_youtube_boomerang_inline | job | Runs Runway image-to-video (10s), then ffmpeg forward/backward loop to fill the song length, then audio mux. Runs as a background job — returns { job_id }; poll get_job until done. |
run_lyric_video_inline | job | Renders a lyric video via Remotion: backgrounds (images and/or videos) + word-aligned lyric overlay + audio mux. audio_start_seconds/audio_end_seconds (or audio_windows for non-contiguous) limits the section rendered; defaults to full song. Runs Whisper alignment on first call per song, cached after. Provide at least one image or video background. Runs as a background job — returns { job_id }; poll get_job until done. |
run_lyric_videos_for_favorites_inline | job | Loads every saved favorite for a song and renders a lyric video per section. Same backgrounds and font apply to every section. Runs Whisper alignment once if needed, then renders sequentially to avoid Remotion/Drive contention. Individual failures are reported per-section without aborting the rest. Runs as a background job — returns { job_id }; poll get_job until done. |
start_studio_pipeline | job | Full studio pipeline for a song (multi-video, multi-shot generation). |
start_quick_video | job | Enqueue a quick-video pipeline (image-to-video clips from images for a song; optional video_model). Returns job_id immediately; user watches JobDock. |
start_clip_assembly | job | Stitch existing clips into finished videos. |
start_youtube_video | job | Long-form YouTube video from a single source image. |
start_youtube_boomerang | job | Looping boomerang YouTube video from a single source image. |
Editing
editing10 toolsVideo-editor timelines (create, edit clips, render), region edits on images, lyric timing.
| Tool | Mode | Description |
|---|---|---|
list_video_edits | sync | List saved video-editor timelines for an artist (optionally one song): id, name, song, clip count. |
get_video_edit | sync | Read one video-editor timeline: every clip with its clip_id, position, length, in-point, crossfade and Ken Burns, plus any gaps. |
create_video_edit | sync | Start a new video-editor timeline for a song, optionally with clips (same operations as edit_video_timeline). Returns the timeline with clip ids. |
edit_video_timeline | sync | Change a saved video-editor timeline the way a person would in the editor: append, insert, move, trim, split, delete clips, set Ken Burns, close gaps, fit to a length, rename, change font or lyric offset. Saves and returns the new timeline. |
render_video_edit | sync | Render a saved video-editor timeline to a lyric video (clips as placed, lyrics overlaid, song audio). Starts a background job and returns { job_id }; poll get_job. |
delete_video_edit | sync | Delete a saved video-editor timeline. Rendered videos made from it stay in the library. |
edit_image_region | sync | Change only part of an image: give the area(s) as rectangles or ellipses in fractions of the image, and what should appear there. Everything outside stays pixel-identical. Saves a new image linked to the original (the original is kept). Paid like one image generation. |
get_lyric_timings | sync | Read a song's lyric line timings (start/end seconds per line) and where they came from (aligned or manual). |
align_song_lyrics | sync | Align a song's lyrics to its audio (word timings). Needed before lyric videos; cached afterwards. Manual timings are never overwritten. |
set_lyric_timings | sync | Correct lyric line timings by line index (from get_lyric_timings). Saved as manual timings, which automatic alignment never overwrites. Word timings inside a line are shifted and scaled with it. |
Media
media18 toolsMedia assets, images, and clips — list / get / create / update / extend.
| Tool | Mode | Description |
|---|---|---|
delete_media_asset | sync | Delete a media asset (image, video or clip) from the library. Images and videos made from it are kept. |
delete_artstyle | sync | Delete an artstyle. Images already generated with it are kept. |
create_song | sync | Manual song create. Usually populated from /api/media/songs after the user pastes a Drive URL. |
update_song | sync | Use this to fix typos in lyrics, set bpm/mood/notes, attach an artstyle, etc. |
create_media_asset | sync | Most assets are auto-created by generation pipelines. Use this only when registering an externally produced file. |
update_media_asset | sync | Patch a media asset. |
get_asset_provenance | sync | How a media asset was made: model, quality, cost, the prompt, every setting recorded at generation (generation params) and what it was made from (source images, clips it composes, references). Assets made before 2026-10-13 have model and cost only. |
list_artstyles | sync | List artstyles for an artist. |
get_artstyle | sync | Get an artstyle. |
create_artstyle | sync | Manual create. Most flows generate definitions via generate_artstyle_definition first. |
update_artstyle | sync | Update artstyle (full record). |
patch_artstyle | sync | Use when only updating a few fields and you do not need the updated row back. |
generate_artstyle_definition | sync | Gemini drafts an artstyle (name/description/prompt_suffix/cover_suffix/full_block/preview_scene) from a text description and/or a reference image asset. Output is structured — call create_artstyle with these fields to persist. |
generate_artstyle_preview | sync | Generates a 9:16 image using the artstyle's preview_scene + prompt_suffix, stores it as a MediaAsset, and links it back to the artstyle. |
refine_artstyle | sync | Sends current artstyle + chat history + new user feedback to Gemini; patches the artstyle with the refined definition AND renders a new preview image. |
get_campaign_artstyle | sync | Get the artstyle associated with a campaign. |
set_campaign_artstyle | sync | Associate (or replace) the artstyle on a campaign. |
update_campaign_artstyle | sync | Patch campaign artstyle overrides. |
Catalogue & updates
catalog6 toolsApple Music release catalogue (link, sync) and turning "what's new" messages into artist events.
| Tool | Mode | Description |
|---|---|---|
get_catalog_status | sync | Is this artist linked to an Apple Music profile, and when was the release catalogue last synced? |
search_catalog_artists | sync | Search Apple Music for an artist profile by name, to find the id link_catalog needs. |
link_catalog | sync | Link an artist to their Apple Music profile and import every release into the discography. A daily sync keeps it current afterwards. |
sync_catalog | sync | Re-read the linked Apple Music catalogue now and import new releases. |
unlink_catalog | sync | Stop syncing the artist's Apple Music catalogue. Releases already imported stay in the discography. |
add_artist_update | sync | Turn a casual "what's new" message into timeline changes that feed captions: new dated events, moves or cancellations of events already on the timeline ("the Lido show moved to Saturday"), or a question when it is unclear which event is meant. By default returns the drafts for the artist to confirm, as the app does; call again with save=true to apply them. Never invents dates. |
Publishing
publishing4 toolsPost to the artist's connected Instagram and Facebook, schedule, cancel, see where posts went.
| Tool | Mode | Description |
|---|---|---|
list_social_accounts | sync | The artist's connected Instagram, Facebook Page and TikTok accounts, and whether agents may post to each. Accounts are connected by a person on the artist page. |
list_publications | sync | Where the artist's posts went or are scheduled to go: platform, status (scheduled, publishing, published, failed), time and link. |
publish_post | sync | Post a video post to the artist's connected Instagram, Facebook Page or YouTube channel, now or at a time. Public and visible to the artist's audience: confirm with the user first. Only works for accounts a person opened to agents. |
cancel_publication | sync | Cancel a scheduled post that has not gone out yet. |
Strategy
strategy11 toolsBrand guide, audience personas, platform strategies, content pillars.
| Tool | Mode | Description |
|---|---|---|
list_personas | sync | List audience personas. |
get_persona | sync | Get a persona. |
create_persona | sync | Create audience persona. |
update_persona | sync | Update persona. |
list_platform_strategies | sync | List platform strategies. |
get_platform_strategy | sync | Get a platform strategy. |
upsert_platform_strategy | sync | Create or update a platform strategy. |
update_platform_strategy | sync | Patch a platform strategy by id. |
get_brand_guide | sync | Get the brand guide for an artist. |
upsert_brand_guide | sync | Create or update the brand guide. |
update_brand_guide | sync | Patch the brand guide by id. |
Content
content11 toolsContent ideas, briefs, campaigns, and post copy.
| Tool | Mode | Description |
|---|---|---|
list_content_ideas | sync | List content ideas, optionally scoped to a single artist. |
get_content_idea | sync | Get a content idea by id. |
create_content_idea | sync | Create a content idea (manual). |
update_content_idea | sync | Update a content idea. |
generate_content_ideas | sync | Drafts N ideas for a given category and persists them as ContentIdea rows. Returns the new ideas. Runs on the org text model unless text_model is given. |
generate_batch_ideas | sync | Generate a balanced multi-category batch of ideas. Optional text_model; otherwise uses defaults. |
list_content_posts | sync | List an artist's posts, newest first. Use `query` to find one by words from its title or caption (an artist can have hundreds of posts). |
get_content_post | sync | Get a content post by id. |
create_content_post | sync | Create a content post (manual). |
update_content_post | sync | Update a content post. |
generate_post_from_idea | sync | Drafts caption + hashtags for a content idea targeted at one platform; persists as a PostContent. Runs on the org text model unless text_model is given. |
Discography
discography5 toolsReleases / discography entries.
| Tool | Mode | Description |
|---|---|---|
delete_discography_entry | sync | Remove a release from the discography. A release linked from Apple Music comes back on the next catalogue sync unless the catalogue is unlinked. |
list_discography | sync | Releases for an artist (singles, EPs, albums). |
get_discography_entry | sync | Get a single discography entry by id. |
create_discography_entry | sync | Create a discography entry (single, EP, or album). |
update_discography_entry | sync | Update a discography entry. |
Artist
artist6 toolsArtist records and artist events.
| Tool | Mode | Description |
|---|---|---|
get_artist | sync | Fetch the full artist record. |
find_artist | sync | Case-insensitive substring match against artist name or slug. |
create_artist | sync | Create a new artist. |
update_artist | sync | Patch artist fields. Send only the fields you want to change. |
list_artist_events | sync | Returns the full event timeline (milestones, releases, performances, etc.). |
create_artist_event | sync | Append an event (milestone, release, performance, personal note, etc.). |
Settings
settings5 toolsApp settings and integration configuration.
| Tool | Mode | Description |
|---|---|---|
health_check | sync | Check Supabase + S3 storage connectivity. |
list_ai_models | sync | List the selectable AI models per task (text, image, lyric_align, video) with their provider and price in credits, and the org default currently in use for each. Model ids from here go into set_ai_model, or into the per-call text_model / video_model / image_model parameters of the generation tools. |
set_ai_model | sync | Set the org's default model for a task. Applies to every later generation that doesn't pass its own model. The image default is the same setting as Settings → Image defaults. |
get_credits | sync | Credit balance, and generation spend by model over the last N days (default 30). Check before starting paid work. |
image_defaults | sync | Read this organisation's default image model and quality, or change them by passing new values. |
Keep going
Related pages
ToolsetsThe nine tool folders, how to load only the ones you need, and how dynamic mode keeps small context windows usable.JobsHow Artifex Studio runs renders asynchronously — launching, polling, reading progress, cancelling, and what a failure looks like.Agent SkillA downloadable Agent Skill that teaches any skills-compatible AI agent how to drive the Artifex Studio MCP server properly — workflows, polling discipline, and the traps.