> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.shipcontent.com/llms.txt
> Use this file to discover all available pages before exploring further.

---
title: YouTube
description: Connect a channel, review videos and read upload results.
section: reference
order: 75
status: implemented
mode: both
generated: true
sourceOfTruth: [src/lib/mcp/agent-tools.ts, src/lib/server/mcp/AgentMcp.ts, src/lib/docs/handoffs.ts, src/lib/docs/channels.ts]
tools: [start_youtube_connection, get_youtube_status, prepare_youtube_publication, publish_youtube_video]
---

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`](#start_youtube_connection)
- [`get_youtube_status`](#get_youtube_status)
- [`prepare_youtube_publication`](#prepare_youtube_publication)
- [`publish_youtube_video`](#publish_youtube_video)

---

### start_youtube_connection {#start_youtube_connection}

<div class="doc-fact-strip"><dl><dt>Title</dt><dd>Connect YouTube Channel <em>as sent in tools/list</em></dd><dt>Transport</dt><dd>Streamable HTTP at <code>/mcp</code></dd><dt>Annotations</dt><dd><span class="doc-chip" data-kind="annotation" data-value="readOnlyHint:true">readOnlyHint true</span> <span class="doc-chip" data-kind="annotation" data-value="destructiveHint:false">destructiveHint false</span> <span class="doc-chip" data-kind="annotation" data-value="idempotentHint:true">idempotentHint true</span> <span class="doc-chip" data-kind="annotation" data-value="openWorldHint:false">openWorldHint false</span> <em>as sent in tools/list</em></dd><dt>Owner handoff</dt><dd>Yes. <code>/connect/youtube</code> from <code>connectionUrl</code></dd><dt>Idempotency key</dt><dd>None</dd><dt>Revision guard</dt><dd>None</dd></dl></div>

> 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

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `workspaceId` | string (UUID) | yes |  |

Unknown fields are rejected.

#### Result

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `connectionUrl` | string (URL) | yes |  |
| `requiresOwner` | **always** `true` | yes |  |

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](/docs/contracts/errors).

#### 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`.

#### Related

- [YouTube](/docs/channels/youtube)

---

### get_youtube_status {#get_youtube_status}

<div class="doc-fact-strip"><dl><dt>Title</dt><dd>Get YouTube Status <em>as sent in tools/list</em></dd><dt>Transport</dt><dd>Streamable HTTP at <code>/mcp</code></dd><dt>Annotations</dt><dd><span class="doc-chip" data-kind="annotation" data-value="readOnlyHint:true">readOnlyHint true</span> <span class="doc-chip" data-kind="annotation" data-value="destructiveHint:false">destructiveHint false</span> <span class="doc-chip" data-kind="annotation" data-value="idempotentHint:true">idempotentHint true</span> <span class="doc-chip" data-kind="annotation" data-value="openWorldHint:false">openWorldHint false</span> <em>as sent in tools/list</em></dd><dt>Owner handoff</dt><dd>No</dd><dt>Idempotency key</dt><dd>None</dd><dt>Revision guard</dt><dd>None</dd></dl></div>

> 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](/docs/channels/youtube#upload-results).

#### Input

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `workspaceId` | string (UUID) | yes |  |

Unknown fields are rejected.

#### Result

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `connections` | array of object | yes |  |
| `jobs` | array of object | yes |  |
| `pending` | object or null | yes |  |

The result carries no other fields.

**`connections[]`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `accountId` | string | yes | pattern `^UC[A-Za-z0-9_-]{22}$` |
| `title` | string | yes |  |
| `status` | `"connected"` \| `"reconnect-required"` \| `"disconnected"` | yes |  |

The result carries no other fields.

**`jobs[]`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `postId` | string (UUID) | yes |  |
| `status` | `"queued"` \| `"uploading"` \| `"processing"` \| `"published"` \| `"private"` \| `"unlisted"` \| `"failed"` \| `"unknown"` \| `"cancelled"` | yes |  |
| `videoId` | string or null | yes |  |
| `error` | string or null | yes |  |

The result carries no other fields.

**`pending.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `requestId` | string (UUID) | yes |  |
| `status` | string | yes |  |
| `channelId` | string or null | yes |  |
| `title` | string or null | yes |  |
| `failureCode` | string or null | no |  |

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](/docs/contracts/errors).

#### Related

- [YouTube](/docs/channels/youtube)

---

### prepare_youtube_publication {#prepare_youtube_publication}

<div class="doc-fact-strip"><dl><dt>Title</dt><dd>Request YouTube Upload Review <em>as sent in tools/list</em></dd><dt>Transport</dt><dd>Streamable HTTP at <code>/mcp</code></dd><dt>Annotations</dt><dd><span class="doc-chip" data-kind="annotation" data-value="readOnlyHint:true">readOnlyHint true</span> <span class="doc-chip" data-kind="annotation" data-value="destructiveHint:false">destructiveHint false</span> <span class="doc-chip" data-kind="annotation" data-value="idempotentHint:true">idempotentHint true</span> <span class="doc-chip" data-kind="annotation" data-value="openWorldHint:false">openWorldHint false</span> <em>as sent in tools/list</em></dd><dt>Owner handoff</dt><dd>Yes. <code>/posts/review</code> from <code>reviewUrl</code></dd><dt>Idempotency key</dt><dd>None</dd><dt>Revision guard</dt><dd>None</dd></dl></div>

> 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

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `workspaceId` | string (UUID) | yes |  |
| `postId` | string (UUID) | yes |  |

Unknown fields are rejected.

#### Result

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `reviewUrl` | string (URL) | yes |  |
| `requiresOwner` | **always** `true` | yes |  |

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](/docs/contracts/errors).

#### 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`.

#### Related

- [YouTube](/docs/channels/youtube)

---

### publish_youtube_video {#publish_youtube_video}

<div class="doc-fact-strip"><dl><dt>Title</dt><dd>Publish a YouTube Video <em>as sent in tools/list</em></dd><dt>Transport</dt><dd>Streamable HTTP at <code>/mcp</code></dd><dt>Annotations</dt><dd><span class="doc-chip" data-kind="annotation" data-value="readOnlyHint:false">readOnlyHint false</span> <span class="doc-chip" data-kind="annotation" data-value="destructiveHint:true">destructiveHint true</span> <span class="doc-chip" data-kind="annotation" data-value="idempotentHint:true">idempotentHint true</span> <span class="doc-chip" data-kind="annotation" data-value="openWorldHint:true">openWorldHint true</span> <em>as sent in tools/list</em></dd><dt>Owner handoff</dt><dd>When mode is owner_review; an automatic post with Publish queues without owner review. <code>/posts/review</code> from <code>review.url</code></dd><dt>Idempotency key</dt><dd><code>requestId</code></dd><dt>Revision guard</dt><dd>None</dd></dl></div>

> 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](/docs/channels/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

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `workspaceId` | string (UUID) | yes |  |
| `postId` | string (UUID) | yes |  |
| `requestId` | string (UUID) | yes |  |
| `metadata` | object | yes |  |

Unknown fields are rejected.

**`metadata.*`**

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `title` | string | yes | min length 1 |
| `description` | string | yes | max length 5000 |
| `privacyStatus` | `"private"` \| `"unlisted"` \| `"public"` | yes |  |
| `madeForKids` | boolean | yes |  |
| `containsSyntheticMedia` | boolean | yes |  |

Unknown fields are rejected.

#### Result

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `mode` | `"auto_publish"` \| `"owner_review"` | yes |  |
| `reason` | `"publish_off"` \| `"post_requires_review"` or null | yes |  |
| `job` | object or null | yes |  |
| `review` | object or null | yes |  |

The result carries no other fields.

**`job.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |

The result carries no other fields.

**`review.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `available` | **always** `true` | yes |  |
| `requiresOwner` | **always** `true` | yes |  |
| `url` | string (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](/docs/contracts/errors).

#### 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](/docs/contracts/request-ids).

#### 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`.

#### Related

- [YouTube](/docs/channels/youtube)
- [Approval model](/docs/contracts/approval-model)

---

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