How to connect Descript MCP with Python

Import media into a Descript project via URLs (direct links, Google Drive, Dropbox) or direct file upload. Pass URLs as-is. Pass empty add_media ({}) with project_name to create an empty project. ADDING TO COMPOSITION: When creating a new project, include add_compositions so imported media appears on the timeline — this is the expected default. Only omit add_compositions for new projects when the user explicitly asks to import without adding to the composition. When importing into an existing project, omit add_compositions unless the user requests it, to avoid disrupting existing edits. To append media to an EXISTING composition, use update_compositions (composition_id + append_clips) instead of add_compositions. DIRECT FILE UPLOAD (preferred): Provide content_type (MIME type) and file_size (bytes) instead of a url. The response includes upload_urls — a map of media key → { upload_url, asset_id, artifact_id }. PUT each file to its upload_url with header Content-Type: application/octet-stream. The uploaded file size must match the file_size declared in the request. Prefer this path: these upload URLs stay valid for hours. Some runtimes have no network access and cannot reach Descript storage, so the PUT fails. While this job is still running the file can go in through the failure report: call report_upload_status (status "failed") with the same attachment in that call's "files" parameter, and Descript fetches the file itself, so this job continues with it in the project it already created. A failure reported without the attachment is final for that file; adding it then needs a new import with the project_id from this response, once this job has stopped. A further import for the same project is rejected until this job stops. Returns immediately with a job_id, project_id, and project_url. Always display the project_url to the user so they can open the project in Descript. Please use the wait_for_job tool with the returned job_id to wait for the job to complete.

Import media files into the drive media library (not into a project). Use this when the user wants to add files to their media library without creating or editing a project. Supports URL imports and direct file uploads. DIRECT FILE UPLOAD: Only for local clients that can reach Google Cloud Storage. Hosted model runtimes cannot PUT to upload_urls; pass a url instead. For local clients: provide content_type (MIME type) and file_size (bytes). The response includes upload_urls — a map of media key → { upload_url, asset_id, artifact_id }. PUT each file to its upload_url with header Content-Type: application/octet-stream. Returns immediately with a job_id and drive_id. Please use the wait_for_job tool with the returned job_id to wait for the job to complete.

Agent Underlord, Descript's built-in AI editor, queries, creates, and edits Descript projects using natural language. Refer to it as Agent Underlord when telling the user what is doing the editing, since that is the name they see in the Descript app. Use project_id for existing projects, project_name to create new ones. Returns immediately with a job_id, project_id, and project_url. Always display the project_url to the user so they can open the project in Descript. Please use the wait_for_job tool with the returned job_id to wait for the job to complete. The response includes a conversation_id — pass it back on subsequent calls to the same project to continue the conversation with full context.

Publish a Descript project composition as video or audio, producing a shareable URL. Requires a project_id. Optionally specify a composition_id (defaults to the first composition). Publishing the same composition again automatically reuses the previous share URL, overwriting its content; Video and Audio publishes of the same composition get separate share URLs. If the composition has no video content: omitting media_type publishes it as audio (the result reports media_type="Audio"), while explicitly requesting media_type="Video" fails with a 422. Publishing an empty composition fails with a 400 that names the compositions which do have content; retry with one of those as composition_id, or use get_project to pick one. Returns immediately with a job_id. Please use the wait_for_job tool with the returned job_id to wait for the job to complete. When the job completes, always display the share_url and download_url from the result to the user.

Wait for a job to complete. Polls for completion by default (840s) and streams progress updates. Set wait_seconds to 0 to return immediately without waiting. Job states: queued, running, stopped, cancelled. A stopped job has a result object — check result.status for "success" or "error". These jobs routinely run for many minutes, so a long wait is normal rather than a stall. If the job is still going when the wait window elapses, the call still succeeds and returns a non-terminal job_state with wait_status "still_running". That is not a failure — call wait_for_job again with the same job_id and keep calling until job_state is "stopped" or "cancelled". While the job is running, progress.label contains a human-readable status (e.g. "Editing script", "Searching web") — display this to the user so they can see what the agent is doing. The response includes project_url — when a composition ID is available in the result, the URL includes a composition short ID suffix so it opens directly to the right composition. Always display project_url to the user. A completed export_timeline job returns a time-limited result.download_url (valid until result.download_url_expires_at); always display this URL to the user so they can download the file directly.

List recent jobs, optionally filtered by project or type. Job states: queued, running, stopped (check result.status), cancelled.

Cancel a queued or running job.

Report that a specific direct upload failed, was aborted, or was abandoned so the import job stops waiting on just that file (other files keep uploading). Use this after a PUT to an upload_url errors ("failed"), the user cancels an in-flight upload ("aborted"), or a file will never be uploaded ("abandoned", e.g. the upload UI was dismissed). media_id is the key from the import request's add_media / upload_urls map. A failed PUT is recoverable while that job is still running: supply the attachment in "files" in the same call that reports the failure, and Descript fetches the file server-side, so the reported job continues with it in the project it already created and reaches a normal result through wait_for_job. Without it, the job finishes with that file marked failed, and a later report carrying the attachment reaches a file the job has already settled; adding it then needs a new import_media into the same project, once the job has stopped.

List projects accessible to the authenticated user. Returns each project's id, name, created_at, updated_at, and folder_path (if the project is inside a folder). Use this to enumerate or page through every project, or to sort projects by created, updated, or last-viewed time. To find specific projects by name, topic, or content, use search_drive instead. Supports cursor-based pagination — pass the next_cursor from a previous response's pagination field to fetch the next page.

Get a detailed project summary including all media files, compositions, and existing publishes. Returns the project's id, name, drive_id, created_at, updated_at, folder_path (if in a folder), a map of media files (keyed by display path) with type and duration, a list of compositions with id, name, duration, and media type, and a list of existing publishes with share_url, access_level, media_type, and publish time. Use this to inspect a project's contents before editing or importing media, or to retrieve existing share URLs without triggering a republish.

List folders in the drive. Returns each folder's full path from the drive root. By default lists root-level folders. Pass parent_path to list child folders of a specific parent. Use this to browse the folder hierarchy before filtering projects by folder_path.

Export a project composition as a transcript document. Formats: txt, markdown, html, rtf, srt. Returns the exported content directly in the response.

Export a project composition as a timeline file for import into another DAW/NLE (Premiere, DaVinci Resolve, Final Cut Pro, Pro Tools, Logic, Audition, Reaper). Media files are never bundled — only the timeline/XML/EDL file itself. Returns immediately with a job_id. Use the wait_for_job tool with the returned job_id to wait for completion; when the job finishes, its result carries a time-limited download_url (valid until download_url_expires_at). Always display the download_url to the user so they can download the file directly. Large exports can take several minutes, so polling avoids connection timeouts. Formats: edl (Samplitude/Reaper), sesx (Adobe Audition), fcp (Final Cut Pro X .fcpxml), premiere (Premiere Pro XML), davinci_resolve (DaVinci Resolve XML), aaf (Pro Tools/Logic, binary).

Search the connected drive for projects, folders, layout packs, and media files by name, by what is spoken or written inside them, or (on drives with the Enterprise plan) by what appears in videos and images. The index covers project names, composition text, media transcripts, and media file names, across projects, the drive media library, and Brand Studio. Results are ranked by relevance by default and carry the ids other tools need (project_id, folder_id, asset_id) plus a url that opens the project, folder, or file in Descript. A file inside a project opens that project with the file highlighted. Thumbnails for the first 12 video and image results are returned as image content blocks, each preceded by a text block naming the asset_id it belongs to. Media file hits use type video, audio, or image. Prefer this over list_projects whenever the user is looking for a project or anything else in the drive, whether by a name fragment, a topic, or a phrase they remember. Use list_projects only to enumerate or page through every project in the drive, and list_folders to browse the folder hierarchy.

Returns the drive (workspace) connected to the current session, including its ID and name. Use this to confirm which drive your requests will operate on.