Use MCP to let your agent submit media, check progress and retrieve results from tldw.sh. It uses the same processing, credits and access rules as the REST API.
The hosted server uses Streamable HTTP at:
https://api.tldw.sh/mcpYou do not need to run an MCP server locally. Choose browser-based OAuth for an interactive client or a scoped API key for a headless integration.
Which connection should you use?
| Client or workflow | Setup |
|---|---|
| Claude web / Desktop | Add the remote connector and authorize your account with OAuth. No API key or CLI is needed. |
| Claude Code | Use its client-specific plugin/MCP setup. The downloadable plugin uses a private API key in the launch environment. |
| Codex | Use the downloadable plugin's Codex manifest and installation instructions. Its bearer key stays in your environment. |
| Cursor | Add a remote MCP entry in personal settings, or use the compatible plugin with its own variable configuration. |
| Scripts and other headless agents | Use a scoped API key with REST, the Python/JavaScript clients, or a bearer-capable MCP client. |
A plugin adds reusable instructions or workflows. The MCP connection exposes tools. An SDK gives your own code a convenient REST client. You can use the connection without installing all three.
Claude web and Desktop: authorize with OAuth
Create your tldw.sh account, finish its one-time verification, then open Claude's Customize → Connectors → Add custom connector. Enter the hosted server URL above.
If authentication choices appear, use Sign in now and Register automatically. tldw.sh supports dynamic client registration. It does not currently advertise the published-identity/CIMD registration method. Add the connector, choose Connect, sign in and review the requested access.
A connector's displayed name alone does not establish that its publisher is verified. Review the authorization details and approve only a client you trust. You can revoke its access later in Settings → Connected apps.
Custom-connector controls depend on your Claude account and workspace permissions. Follow Claude's current setup guide if its controls differ.
Coding assistants: follow the client's configuration
Start from the client chooser on Connect your agent. Claude Code, Codex and Cursor use different manifests and secret substitution; one generic configuration is not interchangeable across them.
The downloadable plugin contains workflows and configuration templates, not your token. Every client uses a literal endpoint that the verified installer on Connect your agent writes into the plugin; there is no endpoint environment variable that could redirect your token. Claude Code, Grok Build and Codex read only TLDW_API_TOKEN from the environment. Cursor's direct MCP configuration resolves the token from its launch environment with ${env:TLDW_API_TOKEN}.
Keep credentials in a private environment or the client's supported secret settings. Do not paste them into a model conversation or commit them with a project. The setup page links to the relevant Claude Code, Codex and Cursor instructions.
Headless agents: authenticate with an API key
After account activation, create an API key in Developers and grant only the permissions the integration needs. A bearer-capable MCP client sends it as an HTTP header:
Authorization: Bearer YOUR_TLDW_API_TOKENThis is a header template, not a real credential. Supply its value through your runtime's private configuration. Headless calls do not need interactive sign-in or a CAPTCHA after the account and credential are ready.
The standard analysis permissions are:
| Permission | Purpose |
|---|---|
jobs:write | Submit analysis work. |
jobs:read | Read job status and progress. |
summaries:read | Read your generated summaries and saved transcripts. |
account:read | Check account usage and read-only connection diagnostics. |
Other tools can require additional scopes. Keys and OAuth grants share the account's credits; creating another credential does not reset the allowance. A new analysis using cached captions still follows standard processing-credit rules. Reading an existing result is a separate, uncharged operation. These credentials do not permit billing changes or access to another user's private results.
Follow the asynchronous tool workflow
Ask the connected agent to use analyze_media with these arguments:
{
"media": "https://www.youtube.com/shorts/af3oL9JMA1g",
"instructions": "Explain the main claim and practical takeaway. Keep it concise.",
"max_credits": 30
}These are tool arguments, not a standalone HTTP request. The client wraps them in the MCP protocol.
Keep the accepted job_id. Use get_job or wait_job to check progress and honor the suggested polling delay. On completion, use get_summary with the result's summary_id. Use get_transcript separately when original captions or source text are needed.
If a wait times out, resume the job rather than submitting again. If retrying a submission with an unknown outcome, reuse its original idempotency key and unchanged arguments. Treat a failed job as a failure, not a completed analysis with missing text.
Browse saved transcripts
Submit one link to POST /v1/analyses or MCP analyze_media. The job saves both a summary and its original transcript. Poll the accepted job, then read GET /v1/summaries/SUMMARY_ID and GET /v1/summaries/SUMMARY_ID/transcript, or MCP get_summary and get_transcript, with the same summary ID. Reading saved results starts no new processing or model call. Use list_transcripts and get_saved_transcript to browse saved source pages.
list_transcripts lists the newest 50 saved sources with metadata, next_cursor, UTC since/until and unread_only filters. Reading or listing does not mark a source read. Use mark_transcript_read explicitly, or open a source in the web Transcripts & text library. Source submission requires jobs:write; progress uses jobs:read; saved-source reads and read-state updates require summaries:read and ownership.
Check the connection without spending processing credits
The versioned CLI's doctor command checks account access, MCP discovery and a read-only tool. Its installation and command are available under the API-key path on agent onboarding. It requires the appropriate scopes and does not submit media.
Then run a small authorized captioned-video example to test the complete workflow. A successful discovery check alone does not prove that a particular source has accessible captions.
Free includes 100 monthly caption/text credits, with plan limits shared across all clients. Omit transcription and force_asr: legacy controls do not enable audio. The service uses usable saved source or captions, at 1 credit per billable minute. Fresh audio transcription is unavailable on every plan. CAPTIONS_UNAVAILABLE releases the failed job hold without a processing-credit charge; stop or supply authorized source text rather than retrying automatically. Bound each job with max_credits. Give the agent llms.txt, OpenAPI and the error recovery guide.