Docs / MCP

Toolsets and progressive disclosure

4 minute read · Updated 2026-09-11

Remote clients get all ninety-eight tools by default. If that is too much for your context window, request a subset with ?toolsets=, or use dynamic mode and let the agent open folders on demand.

Why this exists

Every tool schema a server advertises costs tokens in the client’s context, on every turn. Ninety-eight of them is a lot to carry when the task at hand is "make a lyric video".

So the registry is grouped into folders, and you can choose how much of it to load. Full surface is the default because it needs no configuration and most clients handle it comfortably.

The three modes

Mode	Query	Behaviour
all	?toolsets=all	Every tool enabled at connect. The default for remote clients.
dynamic	?toolsets=dynamic	Only jobs plus two navigation tools. Everything else is registered but hidden until opened.
explicit	?toolsets=library,generation	Only the folders you name, plus the always-on jobs folder.

Connect with a narrowed surface

claude mcp add --transport http artifex-studio \
  "https://app.artifexstudio.app/api/mcp?toolsets=library,generation" \
  --header "Authorization: Bearer artk_your_token_here"

Dynamic mode

In dynamic mode the agent starts with a nearly empty toolbox and two navigation tools. It opens what it needs, when it needs it — and the server notifies the client that the tool list changed, so a capable client refetches automatically.

Navigation tools

list_toolsetsno arguments: Lists the folders, their tool counts, and whether each is currently enabled.
enable_toolset{ toolset: string }required: Reveals every tool in a folder. Takes a folder id such as "library" or "generation".

The folders

98 tools · 9 folders · generated from the running server

Jobs

jobs3 tools · always enabled

Poll 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

library29 tools

Artists, songs, section favorites, artstyles — find / read / update.

Tool	Mode	Description
`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

generation18 tools

Studio pipelines, lyric videos, boomerangs, quick + clip-assembly video.

Tool	Mode	Description
`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 → Runway → assembly → copywriter posts. Runs as a background job — returns { job_id }; poll get_job until done.
`run_quick_video_inline`	job	Lightweight pipeline: ordered images → Runway motion → 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 (Runway clips from images for a song). 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.

Media

media15 tools

Media assets, images, and clips — list / get / create / update / extend.

Tool	Mode	Description
`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.
`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.

Strategy

strategy11 tools

Brand 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 tools

Content 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	Gemini drafts N ideas for a given category and persists them as ContentIdea rows. Returns the new ideas.
`generate_batch_ideas`	sync	Generate a balanced multi-category batch of ideas. No params; uses defaults.
`list_content_posts`	sync	List content posts, optionally scoped to a single artist.
`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	Calls Gemini to draft caption + hashtags for a content idea targeted at one platform; persists as a PostContent.

Discography

discography4 tools

Releases / discography entries.

Tool	Mode	Description
`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 tools

Artist 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

settings1 tools

App settings and integration configuration.

Tool	Mode	Description
`health_check`	sync	Check Supabase + S3 storage connectivity.

Keep going

Tool referenceEvery tool the Artifex Studio MCP server exposes, with its mode and description — generated from the running registry.MCP overviewA remote Model Context Protocol server that exposes the entire Artifex Studio tool surface to Claude, Cursor, or any MCP client.JobsHow Artifex Studio runs renders asynchronously — launching, polling, reading progress, cancelling, and what a failure looks like.

Why this exists

Every tool schema a server advertises costs tokens in the client’s context, on every turn. Ninety-eight of them is a lot to carry when the task at hand is "make a lyric video".

So the registry is grouped into folders, and you can choose how much of it to load. Full surface is the default because it needs no configuration and most clients handle it comfortably.

The three modes

Mode	Query	Behaviour
all	?toolsets=all	Every tool enabled at connect. The default for remote clients.
dynamic	?toolsets=dynamic	Only jobs plus two navigation tools. Everything else is registered but hidden until opened.
explicit	?toolsets=library,generation	Only the folders you name, plus the always-on jobs folder.

Connect with a narrowed surface

claude mcp add --transport http artifex-studio \
  "https://app.artifexstudio.app/api/mcp?toolsets=library,generation" \
  --header "Authorization: Bearer artk_your_token_here"

Dynamic mode

Navigation tools

list_toolsetsno arguments: Lists the folders, their tool counts, and whether each is currently enabled.
enable_toolset{ toolset: string }required: Reveals every tool in a folder. Takes a folder id such as "library" or "generation".

The folders

98 tools · 9 folders · generated from the running server

Jobs

jobs3 tools · always enabled

Poll 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

library29 tools

Artists, songs, section favorites, artstyles — find / read / update.

Tool	Mode	Description
`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

generation18 tools

Studio pipelines, lyric videos, boomerangs, quick + clip-assembly video.

Tool	Mode	Description
`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 → Runway → assembly → copywriter posts. Runs as a background job — returns { job_id }; poll get_job until done.
`run_quick_video_inline`	job	Lightweight pipeline: ordered images → Runway motion → 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 (Runway clips from images for a song). 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.

Media

media15 tools

Media assets, images, and clips — list / get / create / update / extend.

Tool	Mode	Description
`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.
`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.

Strategy

strategy11 tools

Brand 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 tools

Content 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	Gemini drafts N ideas for a given category and persists them as ContentIdea rows. Returns the new ideas.
`generate_batch_ideas`	sync	Generate a balanced multi-category batch of ideas. No params; uses defaults.
`list_content_posts`	sync	List content posts, optionally scoped to a single artist.
`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	Calls Gemini to draft caption + hashtags for a content idea targeted at one platform; persists as a PostContent.

Discography

discography4 tools

Releases / discography entries.

Tool	Mode	Description
`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 tools

Artist 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

settings1 tools

App settings and integration configuration.

Tool	Mode	Description
`health_check`	sync	Check Supabase + S3 storage connectivity.

Why this exists

The three modes

Dynamic mode

The folders

Jobs

Library

Generation

Media

Strategy

Content

Discography

Artist

Settings

Related pages

Why this exists

The three modes

Dynamic mode

The folders

Jobs

Library

Generation

Media

Strategy

Content

Discography

Artist

Settings

Related pages