Connect your AI assistant
Podcasto exposes a Model Context Protocol (MCP) server so Claude, ChatGPT, Cursor, Codex or any MCP-capable client can list, create and manage your podcasts — acting as you, inside your own plan limits and credit balance.
How it works
A bearer token identifies your agent
A personal access token (created in Settings) or an OAuth-issued token, sent as an Authorization: Bearer header on every call.
Every call is scope-checked
The token's scopes decide which tools it can call. A call outside its scopes is refused with the missing scope named in the error.
It runs as you — nothing more
Every tool call goes through the same entitlement, ownership and Telegram validation the web app uses. An agent can't see or touch another user's data.
Your plan and credits still apply
An agent cannot unlock a feature your plan does not already allow, and episode generation still spends your credit balance.
Connecting from each client
For your own account always use https://app.podcasto.org/api/mcp — never the bare podcasto.org apex, which redirects to www and drops the Authorization header. The public discovery tools live on their own endpoint, https://app.podcasto.org/api/mcp/public, and need no credentials at all.
Personal access token, sent as a bearer header.
Claude Code connection command
claude mcp add --transport http podcasto https://app.podcasto.org/api/mcp \
--header "Authorization: Bearer pk_..."Scopes
A token can only call the tools its scopes cover. Grant the fewest scopes that get the job done.
| Scope | Grants |
|---|---|
podcasts:readRead podcasts | List your podcasts and read their settings. |
podcasts:writeManage podcasts | Create, update, pause and resume your podcasts. |
sources:pushAdd content to an inbox | Push text, notes and links into the manual inbox of your own podcasts, for a later episode to be written from. |
episodes:readRead episodes | List episodes and read their status, audio URL and timeline. |
episodes:generateGenerate episodes | Start episode generation. This spends your credits. |
credits:readRead credits | Read your credit balance and plan entitlements. |
adminAdminister the platform | Operate admin tooling (health, users, failed episodes, runtime settings). Only available to admins, and re-checked on every call. |
The admin scope is available only to personal access tokens, only while the holder is actually an admin — losing admin access invalidates any old admin token immediately. OAuth-issued access (Claude.ai, ChatGPT, Cursor connectors) never carries it, regardless of the account's role.
Tools
Every tool answers with a single JSON result. A caller always sees every tool name in `tools/list` — authorization happens when a tool is called, not when the list is built.
Public tools — no account needed
No tokenServed from a separate endpoint, https://app.podcasto.org/api/mcp/public, with no sign-in at all. It sees only what the website already shows: public podcasts and published episodes, plus a playable audio link served by Podcasto itself — the same one the episode page uses. The app re-checks the episode on each request, though a copy already cached at the CDN can keep playing for a while after it stops being public.
| Tool | Purpose |
|---|---|
search_podcastsno token | Search the public podcast directory by text and language. |
list_public_episodesno token | List published episodes of public podcasts, newest first, with a paging cursor. |
get_public_episodeno token | Read one published episode and get a playable audio URL — no account needed. |
play_episodeno token | Same as get_public_episode, plus an inline player in clients that render MCP Apps. |
User tools
| Tool | Purpose |
|---|---|
get_meany valid token | Identity, plan, entitlements and (with credits:read) credit balance. |
list_my_podcastspodcasts:read | List your podcasts and their basic status. |
get_podcastpodcasts:read | Read one podcast plus its full configuration. |
preview_telegram_channelpodcasts:write | Check a Telegram channel is reachable before creating a podcast from it. |
create_podcastpodcasts:write | Create a podcast from Telegram, RSS and/or inbox sources (counts against the plan's podcast limit; no credit charge). |
update_podcastpodcasts:write | Update title, description, schedule or auto-generation for a podcast you own. |
pause_podcastpodcasts:write | Stop scheduled generation for a podcast. |
resume_podcastpodcasts:write | Resume scheduled generation and clear the auto-pause failure streak. |
list_episodesepisodes:read | List a podcast’s episodes, newest first. |
get_episodeepisodes:read | Read one episode’s status, audio URL (once published) and failure details. |
generate_episodeepisodes:generate | Start generation for a podcast. Charges credits; requires confirm: true. |
add_content_itemssources:push | Push text, notes or links into a podcast's manual inbox for its next episode. |
get_credit_balancecredits:read | Read available, used and total credits. |
Admin tools
Admin-onlyRequire the admin scope and an admin account at call time. Only reachable via a personal access token — never via OAuth.
| Tool | Purpose |
|---|---|
admin_system_healthadmin | Fast health subset: cron freshness, episode-outcome SLI, refund-queue depth. |
admin_list_usersadmin | Newest-first user list with effective plan, role, credits and activity; truncated at a safety cap. |
admin_list_podcastsadmin | List every podcast on the platform (basic fields, paginated). |
admin_list_failed_episodesadmin | List failed episodes with failure class and timing. |
admin_get_episode_logsadmin | Read processing log lines for one episode. |
admin_generate_episodeadmin | Generate an episode without charging the owner’s credits. Requires confirm: true. |
admin_regenerate_audioadmin | Re-run synthesis for an existing episode. Requires confirm: true. |
admin_get_runtime_settingsadmin | Read managed runtime settings (value, source, bounds); secrets omitted. |
admin_set_runtime_settingadmin | Update one managed runtime setting. Requires confirm: true; audit-logged. |
admin_cost_summaryadmin | Per-episode production cost vs credits charged for a given month. |
Security model, in plain words
Tokens are hashed at rest
Podcasto never stores your personal access token in a readable form — only a one-way hash and a short prefix to recognize it in your token list.
Revocation is immediate
Revoking a token in Settings takes effect on the next call — there's no caching window where a revoked token still works.
Admin access is PAT-only, re-checked every call
The admin scope requires being an admin both when a token is minted and when each admin tool is called. OAuth connections never carry it, regardless of role.
No destructive or payment actions
Nothing over MCP can delete an account, podcast or episode, or charge a card or move money. Generation spends the same credit balance you already manage.
FAQ
Ready to connect an agent?
Create a personal access token, or read the full reference for building against the tool surface.