> ## 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 customer publishing
description: Connect your X account, approve an exact post, and read saved publication evidence from the worker.
section: channels
order: 30
status: implemented
mode: both
reviewed: 2026-11-19
sources: [db/migrations/20261119T0400_agent_connected_account.sql, db/publishing.sql, src/components/marketing/post-card.tsx, src/components/marketing/marketing-workspace.tsx, src/lib/x/x-tools.ts, src/lib/x/x.ts, src/lib/server/x/XPublishing.ts, src/lib/server/x/x-owner-approval.ts, src/lib/server/x/XApi.ts, src/lib/server/x/XConfig.ts, src/lib/server/x/XPrivateDatabase.ts, src/lib/server/x/XWorkerDatabase.ts, src/lib/server/x/x-callback.ts, src/lib/server/x/x-agent-tools.ts, src/lib/server/x/x-database.ts, src/worker/XPublicationWorker.ts, src/components/owner/channel-tiles.tsx, src/components/owner/x-panel.tsx, src/app/integrations/x/callback/route.ts, src/lib/server/owner/OwnerHandler.ts, db/x.sql, src/lib/social/connect-path.ts, src/lib/server/social/connect-start.ts, src/components/owner/channel-actions.ts, src/lib/marketing/post-catalogue.ts, src/lib/marketing/post-scheduling.ts, src/lib/server/marketing/PostScheduling.ts, src/components/owner/post-schedule-controls.tsx, src/lib/server/x/XScheduledPublication.ts, .env.example, src/lib/server/marketing/post-metrics-agent-tools.ts, src/lib/mcp/agent-post-metrics-tools.ts, src/lib/server/marketing/post-metric-mapping.ts]
tools: [start_x_connection, get_x_status, prepare_x_publication, publish_x_post, edit_post, prepare_post_schedule, get_post_schedule, publish_post, get_post_metrics, refresh_post_metrics]
next: [/docs/workflows/post-draft, /docs/contracts/approval-model, /docs/start/owner-handoff]
---

Connect a customer-owned X account to a workspace. Prepare posts through the post tools. The owner selects the account and approves the exact post in the browser. A queued job is not a provider receipt. Live customer publication has not been verified.

## Connect

Call `start_x_connection` and give `connectionUrl` to the owner. The link is `/connect/x`. The owner signs in if needed, and goes straight to X. On the Connections page and in setup, **Connect** is the same link. The owner grants account identity reads, post reads and writes, media uploads, and refresh access at X. X returns the owner to Connections or to setup, with a connected or error notice. **Manage** shows reconnect and disconnect. Read `get_x_status` after the callback. This read returns saved state and does not contact X.

One active X account is supported per workspace. X and Instagram use separate credentials and worker records. Reconnect replaces the X connection generation. Disconnect blocks new provider work and attempts provider revocation. A request already sent cannot be recalled.

`get_x_status` lists saved connections. An empty `connections` list means no X account is connected: start `start_x_connection` and give the owner its `connectionUrl`. Status `reconnect-required` on a saved connection means reconnect. `X_NOT_CONNECTED` and `X_RECONNECT_REQUIRED` come from Dashboard post performance, not from this read. See [X publishing errors](/docs/contracts/errors#x-publishing-errors).

## Prepare and approve

1. Create a post and edit a draft with the existing post tools.
2. Call `prepare_x_publication` with the `postId`.
3. Give `reviewUrl` to the owner. The URL grants no permission.
4. The owner selects **Use account on X** and checks the text, media, and account in the preview.
5. The owner selects **Publish on X**, checks the text, media, and account in the confirmation, then selects **Publish now**. This approves the saved post exactly as shown.
6. Read `get_x_status` with `postId`. Keep `providerPostId`, `url`, and `verified` separate from queue status.

A repeated approval uses the same request ID and identical input. If a concurrent call queues it during preparation, the server reads and returns that saved operation. It does not queue a second publication.

Approval locks the draft. The worker must finish within ten minutes of approval. New provider calls stop 30 seconds before the permit ends. An owner can withdraw queued work. Changed content, account, or media stops publication. A lost provider response produces an unknown outcome; the worker does not repeat that write.

Updated 2026-10-28. **Publish now** sends the review digest of the post that the owner opened. If the saved post changed after that, for example after an agent edit, the approval is refused with [`CONTENT_CHANGED`](/docs/contracts/errors#recovery-by-kind). Nothing is queued. The page reads the post again: the owner checks it, then publishes again.

Updated 2026-10-13. When the worker stops a step before it sends the request to X, for example because the permit has too little time left, the publication is `failed`, not `unknown`. Nothing was posted. The saved failure keeps the exact internal error code for support.

## Automatic publishing

The owner can give this agent Publish across all owned workspaces in Agents, with typed confirmation `allow agent`. Read `list_workspaces.access.canPublish`. The post must also have `publishMode: "automatic"`. Set it, and `channel: "x"`, with `edit_post` from the user's instruction. The server fills the connected account. Then call `publish_x_post`. It runs the same checks and worker as an owner approval, and saves the approval with the agent's permission. Without the mode or the permission, it saves nothing and returns `mode: "owner_review"` with `reason` and `review.url`. Turning off Publish keeps queued and scheduled posts. Disconnecting the agent cancels its unsent work in all workspaces; disconnecting X stops new provider work. ShipContent sets no daily post limit; X rate limits still apply.

## Insights

Updated 2026-11-19: `get_post_metrics` returns views (impressions), likes, comments (replies), shares (reposts) and `quotes` for each published post. `refresh_post_metrics` reads them from X with the saved X connection. The connection already holds the `tweet.read` permission, so the owner has nothing more to allow. If X asks for a new login, the row fails with `reconnect`. See [Read post performance](/docs/workflows/metrics).

## Limits

- Text is required, with at most 280 weighted characters. Mentions are excluded.
- Use text only, one JPEG/PNG image up to 5 MB, or one MP4 video up to 50 MB and 140 seconds.
- Media uploads use bounded segments and at most 20 processing checks.
- Link-format, carousel and thread publication are Coming soon. Replies, quotes, polls, recurring schedules, automatic analytics and paid X Ads are not included.
- A provider acknowledgement records publication. Failed readback leaves verification pending; it never triggers another post.
- Publication history remains immutable after cancellation or failure. Read an unknown outcome before preparing another post.

## Operator setup

Register a confidential X web app with the exact callback URL `https://<mcp-host>/integrations/x/callback`. The server builds it from the origin of `SHIPCONTENT_MCP_AUDIENCE`; production uses `https://mcp.shipcontent.com/integrations/x/callback`. The browser return on the MCP host redirects to the owner host, where the owner is signed in. Store client credentials and the X vault key ring on the server. Use separate restricted connection and worker database logins. Publication is on when the client credentials are set. X bills API use, including posts with URLs and media uploads, to the developer account; ShipContent sets no API budget. Verify app eligibility and the payment method on the X developer account before a live pilot. See [local setup](/docs/start/connect-local) and [hosted setup](/docs/start/connect-hosted).

## Scheduled delivery

The owner checks the exact saved content and destination, then confirms its time in the [post editor](/docs/workflows/post-draft#automatic-schedules). An agent with Publish can save an automatic post schedule through `prepare_post_schedule`; otherwise the owner confirms the proposal. Updated 2026-11-19: the agent schedule uses the one connected account of the workspace, so the owner does not select it for each post. Before this date, the schedule of a post that an agent made failed until the owner selected the account. `publish_post` publishes an automatic post now through the same checks. Scheduled work uses the existing provider worker, current account/media checks and durable recovery. A planned date never publishes.

Updated 2026-10-14. Scheduled X posts need a connected account. When billing enforcement is enabled, the current plan must also allow publishing and scheduling, except for an owner on the billing enforcement bypass. See [billing](/docs/workflows/billing). No provider-verification flag controls them. A linked job keeps its existing recovery path. No controlled live delivery or intended-customer approval is recorded for this feature. See [scheduling errors](/docs/contracts/errors#scheduling-errors).

Scheduled X supports text, one JPEG/PNG image or one MP4 under the same limits above. `X_NOT_CONFIGURED` needs operator setup. It does not ask for an account reconnect.

Updated 2026-10-16. When billing enforcement is enabled, approval reserves one X publication place. The worker checks the current plan and usage period before it sends the post. A provider acknowledgement uses that place once. A definite unsent failure or cancellation releases it; an unknown publication keeps it for reconciliation. `PLAN_LIMIT_REACHED` includes the named limit and a Billing recovery link. Existing saved results remain readable after a plan change.
