> ## 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: X
description: Connect X, prepare owner review and read publication 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_x_connection, get_x_status, prepare_x_publication, publish_x_post]
---

Prepare owner review and read saved X publication state. These tools do not approve posts or expose provider credentials. A queued job is not delivery evidence.

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

## Tools on this page

- [`start_x_connection`](#start_x_connection)
- [`get_x_status`](#get_x_status)
- [`prepare_x_publication`](#prepare_x_publication)
- [`publish_x_post`](#publish_x_post)

---

### start_x_connection {#start_x_connection}

<div class="doc-fact-strip"><dl><dt>Title</dt><dd>Connect X Account <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/x</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 X connection link (/connect/x) for a customer-owned X account. This call does not contact X, exchange credentials, or authorize publication. The owner signs in if needed and goes straight to X in the browser. Read get_x_status afterward.

**When to call it**

Call this to get the owner's X authorization link. Give `connectionUrl` to the owner. The link is `/connect/x`. The owner signs in if needed and goes straight to X. After the callback the owner returns to Connections. Then read `get_x_status`.

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

#### Owner handoff

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

- What the owner does: Authorize my X account at X.
- What the agent reads: `get_x_status`, field `connections`.

#### Related

- [X customer publishing](/docs/channels/x)
- [Approval model](/docs/contracts/approval-model)

---

### get_x_status {#get_x_status}

<div class="doc-fact-strip"><dl><dt>Title</dt><dd>Get X 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 X connections and up to 100 recent publication records in this workspace, optionally for one post. This does not call X. A queued job is not a published post. Unknown submissions must not be sent again. Credentials are never returned.

**When to call it**

Read saved connection and publication state. Use `postId` to select one post. An unknown outcome must not trigger another submission.

#### Input

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

Unknown fields are rejected.

#### Result

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `connectionAttempt` | object or null | yes |  |
| `connections` | array of object | yes |  |
| `publications` | array of object | yes |  |

The result carries no other fields.

**`connectionAttempt.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `status` | `"pending"` \| `"exchanging"` \| `"connected"` \| `"denied"` \| `"unknown"` | yes |  |
| `expiresAt` | string | yes |  |

The result carries no other fields.

**`connections[]`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `accountId` | string | yes |  |
| `username` | string | yes |  |
| `status` | `"connected"` \| `"disconnected"` \| `"reconnect-required"` | yes |  |
| `expiresAt` | string | yes |  |

The result carries no other fields.

**`publications[]`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `postId` | string (UUID) | yes |  |
| `status` | `"queued"` \| `"running"` \| `"published"` \| `"unknown"` \| `"failed"` \| `"cancelled"` | yes |  |
| `providerPostId` | string or null | yes |  |
| `url` | string or null | yes |  |
| `verified` | boolean | yes |  |
| `failure` | string or null | yes |  |
| `createdAt` | string | yes |  |

The result carries no other fields.

Every successful result is also returned as `structuredContent`.

#### Related

- [X customer publishing](/docs/channels/x)
- [Approval model](/docs/contracts/approval-model)

---

### prepare_x_publication {#prepare_x_publication}

<div class="doc-fact-strip"><dl><dt>Title</dt><dd>Request X Post 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>

> Check the saved post and return the owner's review page for X. The owner selects the X account, reviews text and media, and approves immediate publication there. This tool does not approve, schedule, spend, or publish. Read get_x_status after owner review.

**When to call it**

Call this with the `postId` of a saved post. Give `reviewUrl` to the owner. Read `get_x_status` after owner approval.

#### Input

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `postId` | string (UUID) | yes |  |
| `workspaceId` | 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`.

#### 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 this exact X post.
- What the agent reads: `get_x_status`, field `publications`.

#### Related

- [X customer publishing](/docs/channels/x)
- [Approval model](/docs/contracts/approval-model)

---

### publish_x_post {#publish_x_post}

<div class="doc-fact-strip"><dl><dt>Title</dt><dd>Publish an X Post <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 X post when its publishMode is automatic and this agent has Publish (list_workspaces access.canPublish). Set channel x with edit_post first. With both, this call validates the text and media, saves an agent_publish approval and queues one job; read get_x_status with postId for the result. 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 publication. Do not use a new requestId to hide an unknown result.

**When to call it**

Call this for a post with `publishMode: "automatic"` and channel `x`. Set both
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 an approval and queues one job. Read `get_x_status` with `postId`
for the result. A queued job is not a published post.

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. A replay returns the original publication.

#### Input

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `postId` | string (UUID) | yes |  |
| `workspaceId` | string (UUID) | yes |  |
| `requestId` | string (UUID) | 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 |  |
| `publication` | object or null | yes |  |
| `review` | object or null | yes |  |

The result carries no other fields.

**`publication.*`**

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

#### Errors

- `AUTH_REQUIRED`
- `FORBIDDEN`
- `INVALID_INPUT`
- `NOT_FOUND`
- `X_UNAVAILABLE`
- `IDEMPOTENCY_CONFLICT`

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 X post when it is not automatic or the agent has no permission.
- What the agent reads: `get_x_status`, field `publications`.

#### Related

- [X customer publishing](/docs/channels/x)
- [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-28.
