Tools, scopes and connectors
Every MCP tool with its inputs and scope, the agent skill, and the ChatGPT connector.
13 tools, grouped the way an agent walks them. An asterisk marks a required input, and "Plan" is the subscription gate; scopes are listed further down, since you pick those once when minting the key. A tool refused for either reason names the reason. Every result also names the next step: transcribe_podcast returns an id and tells the model to poll.
Discovery
Turn a show name or a store link into the RSS feed and audio URL everything else needs. YouTube and TikTok links resolve straight to their single video; Spotify shows are refused here, with an explanation the model can act on.
| Tool | What it does | Inputs | Plan |
|---|---|---|---|
| get_rss_feed | Resolve a show name, Apple Podcasts link or Spotify link to its RSS feed. A Spotify link is resolved through the Apple directory, since Spotify publishes no feed of its own. Returns several candidates when the name is ambiguous rather than guessing. YouTube and TikTok have no feed, send those straight to transcribe_podcast. | podcast, url | Any |
| lookup_podcast | Read a feed into show metadata and recent episodes, each with the direct audio URL that transcribe_podcast needs. A Spotify link resolves to the show's public feed first, and to the episode it named. A YouTube or TikTok link resolves to its single video instead. | url*, episode | Any |
Transcription
The core loop. Transcription is asynchronous: you get an id back immediately and poll for the result, so a long episode never blocks the conversation.
| Tool | What it does | Inputs | Plan |
|---|---|---|---|
| transcribe_podcast | Start transcribing a direct audio URL, or a YouTube, TikTok, Spotify or Apple Podcasts link. Returns an id straight away: it never waits for the audio. YouTube comes back already completed, read from the video's caption track, and costs nothing; everything else spends the account's credits. | audio_url*, title, language | Any |
| get_transcript | Fetch one transcription and its status. Returns a 1,500-character preview unless you ask for the full body, so a long episode cannot flood the context window by accident. | id*, full | Any |
| list_transcripts | Browse the account's transcriptions, newest first. Metadata only, never transcript bodies. | limit, status | Any |
| search_my_transcripts | Find an episode by keyword across titles and generated show notes: the "which episode was about X" question. Does not search the full transcript text. | query*, limit, include_unfinished | Any |
Manage
Destructive operations, kept in their own group so a model reading the list sees that they are not part of the ordinary flow.
| Tool | What it does | Inputs | Plan |
|---|---|---|---|
| delete_transcript | Permanently delete one transcript and its stored file. Not undoable and does not refund credits. Confirm with the user first. | id* | Any |
Account
What the account has left, so an agent can check before committing to a long episode or a batch.
| Tool | What it does | Inputs | Plan |
|---|---|---|---|
| get_usage | Report the plan and remaining transcription credits, in minutes. | — | Any |
AI content
Everything you would otherwise write by hand from a finished transcript. They run against the API key's owner, and all but translation cache their result.
| Tool | What it does | Inputs | Plan |
|---|---|---|---|
| generate_show_notes | A summary plus bullet points for a completed transcription. Cached, so a second call is cheap. | id* | Paid plan |
| generate_chapters | Timestamped chapter markers: a title and a start time per section. | id*, force | Paid plan |
| translate_transcript | Translate a completed transcript into another language, returned directly. Cached per language, so a repeat request is free. Each transcript may hold a limited number of distinct languages; the response reports the limit. | id*, language*, force | Paid plan |
Publish
Tools that act on something outside the transcript itself: a public page, or an endpoint that gets told when things happen.
| Tool | What it does | Inputs | Plan |
|---|---|---|---|
| publish_episode | Put an episode's transcript on a public page at /p/{show}/{episode}. Refused for shows whose ownership has not been verified, because it publishes under the user's name. | episode_id* | Any |
| manage_webhook | List, create or delete webhook endpoints, so an agent is told when work finishes instead of polling for it. The signing secret is shown once, on create. | action*, url, events, id | Any |
The rules behind the shapes
- Nothing blocks on audio.
transcribe_podcastreturns an id in under a second and is polled withget_transcript. - A full transcript is opt-in.
get_transcriptreturns a ~1,500-character preview and the total length. Passfull=trueonly when you need the body: a two-hour episode is comfortably 60,000 characters. - Ambiguity comes back as candidates. Two shows share a name more often than you would expect, so
get_rss_feedreturns several with their authors rather than picking one. - A refusal is an instruction. A Spotify *show* link cannot be resolved to a feed and a YouTube link is not a feed at all; both return what to do instead. Retrying fails the same way.
- Failed transcriptions are not charged. Successful ones spend credits at the same rate as REST; see Usage.
Scopes
Read this as “what a key carrying this scope unlocks”. Hand an unproven agent a read-only key and widen once you have watched it work; a refusal names the missing scope.
| Scope | Unlocks |
|---|---|
| ai:write | generate_show_notes, generate_chapters, translate_transcript |
| shows:write | publish_episode, manage_webhook |
| transcriptions:read | get_transcript, list_transcripts, search_my_transcripts |
| transcriptions:write | transcribe_podcast, delete_transcript |
| none needed | get_rss_feed, lookup_podcast, get_usage. Any valid key reaches these. |
Tool calls draw on the same rate-limit budget as the REST API, per key; see Usage. Agents fan out more than handwritten clients, so a research-style client hitting several tools a turn is the case most likely to meet them.
The agent skill
Connecting the server tells an assistant which tools exist, not what order to call them in or what will cost the user money. The skill is that second document: one markdown file generated from the same catalog, at `/skill.md`. Point any agent that can read a URL at it; clients with a skills installer get the same file packaged as a plugin.
It exists because most of what goes wrong on a first agent run is sequencing. An assistant polls get_transcript once, sees processing after four seconds and reports failure; or it pulls a full transcript it has no use for and spends its context on it. The skill states both, plus the rule that matters commercially: transcribing spends credits, so get_usage comes before a long episode or a batch.
ChatGPT connector
/api/mcp/chatgptscope: transcriptions:readChatGPT's research surfaces call exactly two tools (search and fetch) and ignore everything else a server exposes, so there is a second endpoint at https://podcaststotext.com/api/mcp/chatgpt that speaks only those two. Same key, same transcripts, different door: add it as a connector and it appears in research mode.
| Tool | Takes | Returns |
|---|---|---|
| search | A query string | Matching episodes as {id, title, text, url} with an excerpt. Searches titles and generated show notes, not the full body. |
| fetch | An id from search | One transcript in full, deliberately unlike get_transcript: a research citation built on a truncated document misrepresents it. |
It sees only completed transcripts on the key’s own account. Published episodes are cited with their public /p/ URL; unpublished ones fall back to a dashboard URL only you can open. Everything else, transcribing, show notes, chapters, translation, stays on the main endpoint, because nothing on that surface would call it.
