Skip to content

YouTube

Implemented

Connect a channel, review videos and read upload results.

Open as Markdown

Connect a channel with start_youtube_connection. The owner goes straight to Google to grant channel access. Use prepare_youtube_publication for exact owner review and get_youtube_status to read saved delivery. These tools never grant upload approval.

Quoted text is the tool description your client receives from tools/list.

Tools on this page#


start_youtube_connection#

Title
Connect YouTube Channel as sent in tools/list
Transport
Streamable HTTP at /mcp
Annotations
readOnlyHint true destructiveHint false idempotentHint true openWorldHint false as sent in tools/list
Owner handoff
Yes. /connect/youtube from connectionUrl
Idempotency key
None
Revision guard
None

Return the owner's YouTube connection link (/connect/youtube) for this workspace. The owner signs in if needed, then goes straight to Google to grant channel access. The first channel is saved when Google returns it; after data deletion, every reconnect needs destination confirmation. This read creates no OAuth state or publication approval. Read get_youtube_status to check saved progress.

When to call it

Give the returned connectionUrl to the owner. The link is /connect/youtube. The owner signs in if needed, then goes straight to Google authorization. There is no intermediate ShipContent page or checkbox. The URL grants no access. The first channel is saved when Google returns it. After data deletion, every reconnect waits for the owner's destination confirmation. Read get_youtube_status afterward.

Input#

Table: Field, Type, Required, Constraints
FieldTypeRequiredConstraints
workspaceIdstring (UUID)yes

Unknown fields are rejected.

Result#

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
connectionUrlstring (URL)yes
requiresOwneralways trueyes

The result carries no other fields.

Every successful result is also returned as structuredContent.

Errors#

  • AUTH_REQUIRED
  • FORBIDDEN
  • DATABASE_UNAVAILABLE

Errors return isError: true and { code, error } in structuredContent. See Error codes.

Owner handoff#

The owner URL is connectionUrl for /connect/youtube. Give that URL to the owner and stop. The URL grants no access by itself.

  • What the owner does: Authorize my YouTube channel at Google. Confirm the destination on a reconnect.
  • What the agent reads: get_youtube_status.

get_youtube_status#

Title
Get YouTube Status as sent in tools/list
Transport
Streamable HTTP at /mcp
Annotations
readOnlyHint true destructiveHint false idempotentHint true openWorldHint false as sent in tools/list
Owner handoff
No
Idempotency key
None
Revision guard
None

Read saved YouTube channel and publication status in this workspace. Saved connection status is not a live provider access check. Private, unlisted and public delivery remain distinct. No credentials are returned.

When to call it

Read connections and jobs. Private uploads, unlisted videos and public publication have separate statuses. This tool does not contact YouTube or return credentials.

pending.failureCode identifies a failed account connection. YOUTUBE_CHANNEL_REQUIRED means the owner must create a YouTube channel or choose another account. YOUTUBE_ACCESS_REVOKED means Google refused the saved token; give the owner start_youtube_connection again. Deleted receipts have no videoId; inspect YouTube Studio instead of starting a replacement upload.

jobs[].error is null or a note. A failed job means that YouTube holds no video of the upload. An unknown job means that a video can exist: inspect YouTube Studio and do not upload again. When YouTube answered a failed call, the note is followed by YouTube said: and the call, the HTTP status, the reason and the message. While a job still uploads, error shows the last failed call and the worker tries again. A failure that is not an answer of YouTube shows a note with no YouTube said: part. See upload results.

Input#

Table: Field, Type, Required, Constraints
FieldTypeRequiredConstraints
workspaceIdstring (UUID)yes

Unknown fields are rejected.

Result#

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
connectionsarray of objectyes
jobsarray of objectyes
pendingobject or nullyes

The result carries no other fields.

connections[]

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
accountIdstringyespattern ^UC[A-Za-z0-9_-]{22}$
titlestringyes
status"connected" | "reconnect-required" | "disconnected"yes

The result carries no other fields.

jobs[]

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
postIdstring (UUID)yes
status"queued" | "uploading" | "processing" | "published" | "private" | "unlisted" | "failed" | "unknown" | "cancelled"yes
videoIdstring or nullyes
errorstring or nullyes

The result carries no other fields.

pending.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
requestIdstring (UUID)yes
statusstringyes
channelIdstring or nullyes
titlestring or nullyes
failureCodestring or nullno

The result carries no other fields.

Every successful result is also returned as structuredContent.

Errors#

  • AUTH_REQUIRED
  • FORBIDDEN
  • DATABASE_UNAVAILABLE

Errors return isError: true and { code, error } in structuredContent. See Error codes.


prepare_youtube_publication#

Title
Request YouTube Upload Review as sent in tools/list
Transport
Streamable HTTP at /mcp
Annotations
readOnlyHint true destructiveHint false idempotentHint true openWorldHint false as sent in tools/list
Owner handoff
Yes. /posts/review from reviewUrl
Idempotency key
None
Revision guard
None

Return owner review for one saved post. The owner saves YouTube metadata, verifies the video and approves the exact upload in the browser. This tool does not upload, approve, or schedule a video.

When to call it

Send the postId of a saved post. Give reviewUrl to the owner. The owner saves metadata, verifies media and approves the upload. Read get_youtube_status after approval.

Input#

Table: Field, Type, Required, Constraints
FieldTypeRequiredConstraints
workspaceIdstring (UUID)yes
postIdstring (UUID)yes

Unknown fields are rejected.

Result#

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
reviewUrlstring (URL)yes
requiresOwneralways trueyes

The result carries no other fields.

Every successful result is also returned as structuredContent.

Errors#

  • AUTH_REQUIRED
  • FORBIDDEN
  • DATABASE_UNAVAILABLE

Errors return isError: true and { code, error } in structuredContent. See Error codes.

Owner handoff#

The owner URL is reviewUrl for /posts/review. Give that URL to the owner and stop. The URL grants no access by itself.

  • What the owner does: Approve the exact YouTube upload after background saving completes.
  • What the agent reads: get_youtube_status, field jobs.

publish_youtube_video#

Title
Publish a YouTube Video as sent in tools/list
Transport
Streamable HTTP at /mcp
Annotations
readOnlyHint false destructiveHint true idempotentHint true openWorldHint true as sent in tools/list
Owner handoff
When mode is owner_review; an automatic post with Publish queues without owner review. /posts/review from review.url
Idempotency key
requestId
Revision guard
None

Publish one exact saved MP4 to the workspace's YouTube channel when the post's publishMode is automatic and this agent has Publish (list_workspaces access.canPublish). Set channel youtube with edit_post first. With both, this call saves the given title, description and privacy on the post, approves them with agent_publish and queues one upload with those exact settings; read get_youtube_status for the result and the visibility YouTube returned, which can differ from the request. Otherwise nothing is saved: mode is owner_review, reason is post_requires_review or publish_off, and review.url opens the owner's review. Reuse requestId after a lost response; a replay returns the original job.

When to call it

Call this for a post with publishMode: "automatic", channel youtube and one saved MP4. Set the mode and channel with edit_post from the user's instruction. The owner must give this agent Publish; read list_workspaces.access.canPublish. With both, the call saves your title, description and privacy on the post, approves them and queues one upload. Read get_youtube_status for the result.

YouTube decides the result. If it returns another visibility, the job shows it with a note. A public upload through ShipContent has not been tested. See YouTube limits.

Otherwise the call saves nothing. mode is owner_review, reason is post_requires_review or publish_off, and review.url opens the owner's review. Reuse requestId after a lost response.

Input#

Table: Field, Type, Required, Constraints
FieldTypeRequiredConstraints
workspaceIdstring (UUID)yes
postIdstring (UUID)yes
requestIdstring (UUID)yes
metadataobjectyes

Unknown fields are rejected.

metadata.*

Table: Field, Type, Required, Constraints
FieldTypeRequiredConstraints
titlestringyesmin length 1
descriptionstringyesmax length 5000
privacyStatus"private" | "unlisted" | "public"yes
madeForKidsbooleanyes
containsSyntheticMediabooleanyes

Unknown fields are rejected.

Result#

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
mode"auto_publish" | "owner_review"yes
reason"publish_off" | "post_requires_review" or nullyes
jobobject or nullyes
reviewobject or nullyes

The result carries no other fields.

job.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes

The result carries no other fields.

review.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
availablealways trueyes
requiresOwneralways trueyes
urlstring (URL)yes

The result carries no other fields.

Every successful result is also returned as structuredContent.

Example call#

json
{
  "name": "publish_youtube_video",
  "arguments": {
    "workspaceId": "00000000-0000-4000-8000-000000000001",
    "postId": "00000000-0000-4000-8000-000000000003",
    "requestId": "00000000-0000-4000-8000-000000000006",
    "metadata": {
      "title": "Northstar in 30 seconds",
      "description": "How Northstar shows weekly revenue.",
      "privacyStatus": "private",
      "madeForKids": false,
      "containsSyntheticMedia": false
    }
  }
}

Errors#

  • AUTH_REQUIRED
  • FORBIDDEN
  • INVALID_INPUT
  • NOT_FOUND
  • IDEMPOTENCY_CONFLICT
  • YOUTUBE_VIDEO_REQUIRED
  • YOUTUBE_RECONNECT_REQUIRED
  • MEDIA_CONTENT_MISMATCH

Errors return isError: true and { code, error } in structuredContent. See Error codes.

Replay and conflicts#

Reuse the same requestId with identical input to recover a lost response; the original result is returned. Changed input with the same ID is rejected. A new ID creates a new operation. See Request IDs, replay and recovery.

Owner handoff#

When mode is owner_review; an automatic post with Publish queues without owner review, use the owner handoff if returned. The owner URL is review.url for /posts/review. Give that URL to the owner and stop. The URL grants no access by itself.

  • What the owner does: Approve this exact video when it is not automatic or the agent has no permission.
  • What the agent reads: get_youtube_status, field jobs.

The schemas on this page are generated from the repository at build time. The guidance was last reviewed on 2026-09-30.

Status: Implemented · Generated from src/lib/mcp/agent-tools.ts, src/lib/server/mcp/AgentMcp.ts, src/lib/docs/handoffs.ts, src/lib/docs/channels.ts

Open as Markdown