MCP tool reference

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

ToolsCopy Anchor Link

Read contentCopy Anchor Link

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. Filter by gender, language, voice_type, or an exact accent, or pass a plain-text query such as irish male storyteller: a voice matches when any word appears in its description, accent, or style tags, and male or female filters by gender. Results are not ranked by how many words match. 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. Pass include_transcript: true to read a rendered episode's transcript: outputs.transcript then carries the speaker-attributed text inline, capped at 100,000 characters at a speaker turn, with truncated and total_characters showing whether it was cut. Without it, an episode's transcript reads not_requested. During a regeneration the previous render's transcript stays available; an episode with no transcript yet reads preparing while it generates or renders, and unavailable once settled. Every other content kind reads unavailable. When progress.poll_after_seconds is greater than zero, wait that long and poll again. progress.needs_attention counts the gaps a usable episode or video still has (unvoiced_lines, missing_visuals, skipped_sources), and is null when nothing is missing; failed means nothing usable exists. 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 updateCopy Anchor Link

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. save_podcast also sets author, primary_category, and an optional secondary_category (Apple Podcasts category or subcategory names, which the RSS feed nests under their parent category). A podcast created without a category gets one chosen from its title and description. Character Voice changes and archiving require Studio. update_content resolves an episode, video, short, or voiceover from its ID and changes descriptive metadata, caption visibility and style (captions_enabled, caption_style_id), and the watermark corner (watermark). Caption and watermark values override the podcast default for an episode and the organization default for a video; null returns a field to its default. Production edits such as scripts, narration, cast, sources, visuals, timeline, and new watermark images 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. A video or short script's speakers can resolve to at most four distinct Characters; give extra speakers a Character already in the script.

For episodes, videos and shorts, 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.

Every generation tool renders its output once generation finishes, so an episode's audio_stream is ready to play when get_content reports it complete.

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.

AutomationsCopy Anchor Link

list_automations returns every automation, newest first, with its name, prompt, enabled state, paused_reason, trigger_type, schedule or inbound_address, output_type (episode, video, or short), output settings, and linked podcast_id or character_id. Automations with the same prompt are all returned. Filter by podcast_id and follow nextCursor.

save_automation creates without id and updates with id. An update changes only the fields supplied; schedule, episode_settings, and video_settings merge key by key. trigger_type and output_type cannot change after creation. Setting enabled to false pauses an automation. An automation paused because Credits ran out returns code: "credit_recovery_required" with a Studio link instead of resuming. If other fields saved but pausing or resuming failed, the error says so and the same request can be retried. delete_automation stops future runs; a run in progress still finishes.

PublishCopy Anchor Link

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.

DeleteCopy Anchor Link

delete_content permanently deletes a podcast, episode, video, short, or voiceover by ID and cannot be undone. Deleting a published episode removes it from the podcast feed, and deleting a podcast deletes all of its episodes. Agents call it only when the creator explicitly asks to delete a named item. The receipt carries id, kind, and operation: "delete", plus the episode's prior publication_state or the podcast's deleted episode_count. An ID that is unknown or already deleted returns not_found.

Results and errorsCopy Anchor Link

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. A video or short script past the four-Character ceiling returns code: "host_ceiling". Invalid tool arguments return the standard MCP InvalidParams error.

See the agent guide for complete request sequences.