# Podcast Robot - guide for agents that build their own client
# https://podcastindexrobot.com/llms.txt  (also /agents)

Podcast Robot is a remote MCP server on top of Podcast Index (4+ million podcasts), Podcasting 2.0 tags and
Podping. It makes an AI agent smart about podcasts: discovery, people, places, podrolls, clips with jump links,
what's new, live streams, Value4Value, and a feed grader for podcasters. Part of Podcast Index.

ENDPOINT
  POST https://podcastindexrobot.com/mcp
  Transport: MCP Streamable HTTP, stateless, JSON responses. No auth, no key, no session needed.
  Headers:  Content-Type: application/json
            Accept: application/json, text/event-stream
  Rate limit: 60 requests per minute per IP (burst 30); HTTP 429 + Retry-After above that.
  Logging: We record which tools are used and the search words, with no IP addresses and nothing that identifies you, only to improve Podcast Robot. Records are deleted after 30 days.
  Every response is one JSON-RPC 2.0 object. Tool results carry `structuredContent` (JSON) and `content[0].text`.

HANDSHAKE (optional on this server, but good manners; it returns the server instructions)
  curl -s -X POST https://podcastindexrobot.com/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-agent","version":"1"}}}'

LIST TOOLS
  curl -s -X POST https://podcastindexrobot.com/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

CALL A TOOL - start here (a live menu + onboarding checklist)
  curl -s -X POST https://podcastindexrobot.com/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"start_here","arguments":{"prefs":{"app":"fountain","city":"Austin"}}}}'

MORE EXAMPLES
  search:      {"name":"search_podcasts","arguments":{"query":"No Agenda","mode":"title","max_results":3}}
  what's new:  {"name":"whats_new","arguments":{"feeds":["41504","920666"],"since":"7d"}}
  a clip:      {"name":"transcript_search","arguments":{"episode":"61124290178","query":"bitcoin","max_hits":2}}
  then:        {"name":"make_clip","arguments":{"episode":"61124290178","start":4577,"duration":45}}
  near a place:{"name":"podcasts_near","arguments":{"place":"Austin"}}
  grade a feed:{"name":"grade_feed","arguments":{"feed":"https://feeds.podcastindex.org/pc20.xml"}}
  live now:    {"name":"podping_events","arguments":{"since":"30m","reason":"live"}}

PREFERENCES (the server stores nothing; you keep these and pass them on every call)
  "prefs": {"app":"fountain","city":"Austin","follows":["41504"],"topics":["bitcoin"],"language":"en","clean_only":false,"v4v_only":false}
  With prefs.app set, every show and episode in a result carries open.app (a link that opens in the owner's app),
  open.universal (a page offering all apps) and open.podcastindex. Apps: fountain, castamatic, podverse,
  curiocaster, podcastguru, apple, overcast, pocketcasts, castro, antennapod, podcastaddict, breez, truefans,
  podfriend, steno, youtubemusic. Spotify has no deep link.

KEEPING WATCH (scheduled / recurring checks)
  Pass the time of your last check as `since` and only incremental tools run:
    new episodes in followed shows:  whats_new {"feeds":[...],"since":"<ISO or epoch of last check>"}
    did a feed change at all:        feed_activity {"feeds":[...],"since":"..."}   (Podping, cheapest)
    something went live:             podping_events {"since":"15m","reason":"live"} or live_now
    new shows / episodes on a topic: search_podcasts or search_people once a day; diff against your last report
  Interval: every 15 minutes is good; never faster than 5 minutes; daily digests once a day.
  One check = 1-3 calls. Limit: 60 calls per minute per IP.

HOW TO BEHAVE
  1. Call start_here the first time podcasts come up. Offer the owner 2-3 concrete things from its live menu.
  2. Onboard once: ask the owner their podcast app, city, the shows they follow, topics they like. Save in YOUR memory.
  3. Every result ends with `hints`: 2-3 follow-up calls. End your answers with one line of next-step ideas.
  4. Errors come back inside the result. kind "fault" = our bug: it has an errorId and a message saying it is
     logged and being fixed - tell your owner, quote the id, retry once. kind "input" = not a bug: follow
     whatToTry / closestMatches / howToAdd. Identifiers: feedId / podcastGuid for shows, episodeId / guid for
     episodes; feed URLs work too. Times: ISO 8601 or relative like "7d", "12h".
  5. HTTP 502/503/504 with a JSON-RPC error body means Podcast Robot is restarting; honour Retry-After (3 s).

TOOLS
  start_here         START HERE. Call this the first time podcasts come up, or when the user asks what you can do.
  get_clips          Ready-made clips and structure for an episode: the podcaster's own `soundbites` (as
  transcript_search  Find where an episode talks about something. Reads the episode's Podcasting 2.0
  make_clip          Build a shareable clip reference: audio URL, start, duration, a `playUrl` with a media
  feed_tags          The full Podcasting 2.0 view of a show, read live from its feed: hosts and regular cast
  podroll_walk       Follow a show's `podroll` — the shows its creator recommends — and the podrolls of those
  podcasts_near      Find shows by place, using every feed in the index that carries a `podcast:location` tag
  recommendations    The podroll graph around a show, from the index-wide recommendation dataset (every
  most_recommended   The shows most often placed in other podcasters' podrolls — a human-curated popularity
  grade_feed         Ask Engine Optimization report for a podcaster: grades the feed's Podcasting 2.0 tag use
  index_stats        How big is podcasting, right now: Podcast Index totals (feeds, episodes), how many feeds published in the
  add_to_index       Add a podcast feed to Podcast Index (or ask the index to re-read it now). ONLY call this when the
  search_podcasts    Find podcasts (or music / video / audiobook / film feeds) in Podcast Index.
  search_people      Find episodes where a person appears, by name — across every show in the index.
  get_podcast        Get one show by Podcast Index `feedId`, `podcastGuid`, feed URL, or `itunes:<id>`.
  get_episodes       List episodes of a show, newest first. `feed` = feedId, podcastGuid or feed URL.
  get_episode        Get one episode with full show notes by Podcast Index `episodeId` or episode `guid`.
  trending           What is hot right now across the index, by trend score.
  surprise_me        Serendipity: random episodes from the whole index, optionally filtered by language and
  recent             The newest things in the index, in reverse chronological order.
  live_now           Shows that are streaming LIVE right now (Podcasting 2.0 `liveItem`), with the stream link.
  whats_new          "What's new for me?" — for a list of shows the user follows, return new episodes since a
  value_info         How to support a show: its Podcasting 2.0 value block (Lightning / Value4Value recipients
  podping_events     Real-time feed activity from Podping: which feeds announced an `update` (new episode or
  feed_activity      For specific shows: the Podping events (update / live / liveEnd) since a time, resolved

Landing page with per-app connect steps: https://podcastindexrobot.com/   Health: https://podcastindexrobot.com/healthz   Source patterns for links: github.com/Podcastindex-org/podcast-platform-links