Skip to content

X

Implemented

Connect X, prepare owner review and read publication results.

Open as Markdown

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#

Title
Connect X Account 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/x from connectionUrl
Idempotency key
None
Revision guard
None

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#

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.

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.

get_x_status#

Title
Get X 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 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#

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

Unknown fields are rejected.

Result#

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
connectionAttemptobject or nullyes
connectionsarray of objectyes
publicationsarray of objectyes

The result carries no other fields.

connectionAttempt.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
status"pending" | "exchanging" | "connected" | "denied" | "unknown"yes
expiresAtstringyes

The result carries no other fields.

connections[]

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
accountIdstringyes
usernamestringyes
status"connected" | "disconnected" | "reconnect-required"yes
expiresAtstringyes

The result carries no other fields.

publications[]

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
postIdstring (UUID)yes
status"queued" | "running" | "published" | "unknown" | "failed" | "cancelled"yes
providerPostIdstring or nullyes
urlstring or nullyes
verifiedbooleanyes
failurestring or nullyes
createdAtstringyes

The result carries no other fields.

Every successful result is also returned as structuredContent.


prepare_x_publication#

Title
Request X Post 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

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#

Table: Field, Type, Required, Constraints
FieldTypeRequiredConstraints
postIdstring (UUID)yes
workspaceIdstring (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.

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.

publish_x_post#

Title
Publish an X Post 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 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#

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

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
publicationobject or nullyes
reviewobject or nullyes

The result carries no other fields.

publication.*

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.

Errors#

  • AUTH_REQUIRED
  • FORBIDDEN
  • INVALID_INPUT
  • NOT_FOUND
  • X_UNAVAILABLE
  • IDEMPOTENCY_CONFLICT

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

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

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