MCP tool reference

Connect to https://mcp.jellypod.com/mcp. Call tools/list for the current input and output schemas.

Tools

Read content

Content kinds are podcast, episode, video, short, and voiceover.

list_content returns all content kinds by default, newest first. It can filter by kind, title, generation state, episode publication state, or parent podcast. Pass nextCursor as cursor for the next page.

list_characters returns each character's profile and voice details. list_voices returns built-in voice IDs. list_video_styles returns built-in style IDs, descriptions, and preview URLs.

get_content accepts an ID and resolves the content kind. It returns progress, the Studio URL, and the state of share, playback, stream, download, transcript, and caption outputs. outputs.audio_stream and outputs.video_stream are direct URLs for playback, separate from the audio_download and video_download links. When progress.poll_after_seconds is greater than zero, wait that long and poll again. Reading content never starts generation or rendering.

A client that supports MCP Apps renders get_content results in a native audio or video player, using audio_stream for episodes and video_stream for videos, shorts, and voiceovers by default, with a control to switch when both are available. A client without MCP Apps support should offer the available stream as a Listen or Watch link instead.

For an episode, a render started after generation completes can still delay its output. get_content keeps progress.status at generating until that render attaches or fails, then reports failed with an explanation if it fails; an older published output stays available in outputs throughout.

Create and update

save_podcast and save_character create without id and update with id. Creating a podcast requires title and character_ids, since a podcast cannot exist without a cast; find character IDs with list_characters. Character Voice changes and archiving require Studio. update_content resolves an episode, video, short, or voiceover from its ID and changes descriptive metadata only. Production edits such as scripts, narration, cast, sources, visuals, timeline, and presentation require Studio.

generate_episode, generate_video, and generate_short accept either prompt or script. Script speaker labels match saved Characters, or use speaker_characters: [{"label": "Narrator", "character_id": "..."}] to assign active Characters from list_characters. Create missing Characters with save_character first. Script mode does not accept prompt cast fields or sources. Video and short generation require style_id in both modes.

For Episodes, prompt always writes a new script from the supplied material. Use script to preserve finished narration, with speaker_characters when its labels differ from saved Character names.

Episode generation remains a draft unless auto_publish is true. Set it only when the creator explicitly asks to publish after a successful render.

Every generation tool returns id, kind, studio_url, and progress. generate_episode also returns publication_state, always draft at creation. Video and short results also return the settings Jellypod applied.

generate_episode's studio_url is the draft editing workspace. get_content returns the stable /episodes/<id> address for the same episode.

Episodes, videos, and shorts accept public webpage or YouTube URLs and plain text held by the client. MCP does not accept file uploads or saved source IDs. When a creator provides a file, the client can extract its text and pass that text inline. File-backed sources and voiceover creation remain in Studio.

Generation and metadata write tools accept an optional idempotency_key. Without one, each call starts a new operation. Save a key before the call when a resend must not run twice, reuse it with the same input after a lost response, and use a new key for a different request once work has started. A rejection before work starts can release its claim; follow recovery.idempotency_key to reuse that key with corrected input.

Publish

set_episode_publication accepts mode: "publish", "schedule", or "unpublish". Scheduling also requires scheduled_time; scheduling an already scheduled episode reschedules it. Publishing an episode does not make a private podcast public.

A publish or schedule receipt also carries episode_url and rss_feed_url, the public episode page and the parent podcast's RSS feed. Both are null while the podcast is private. Neither field is present after unpublish.

set_episode_publication refuses while the episode's newest render is still producing or attaching its output, and names get_content as the way to wait for it. A newest render that fails does not block publishing an already attached, working output.

Results and errors

Every tool returns structured or text output.

Jellypod domain and cross-field errors contain code, message, retry_with_same_input, recovery (next action and any key policy), and, when useful, field, studio_url, or speakers. A script naming a speaker with no matching character returns code: "unresolved_speakers" and the unmatched labels in speakers. Invalid tool arguments return the standard MCP InvalidParams error.

See the agent guide for complete request sequences.