x-mcp

This server is the agent-facing surface for working with X (Twitter). The factual shape: agents can draft — posts and threads, with updates and cancellation — and every draft lands in a review queue inside the app, where publishing is a human action. The approve, reject, and master-pause controls are deliberately not exposed as agent tools; an agent can prepare and check, and only you can publish. The server itself holds no credentials — account tokens stay in the platform's own store, and the tools proxy the automation daemon that does the work.

Around drafting sit three groups of supporting tools. Pre-flight checks are pure computation with no side effects: estimate the cost of a payload before drafting it, check content against the compliance rules, check posting cadence, and read the budget state. Local reads answer "what is drafted, scheduled, or configured" entirely from the local database. Analytics reads return locally stored metric snapshots and benchmarks for what has been published.

Two scope notes, stated plainly. First, five inbound tools — live search and reading from X — are release-gated: they ship disabled by default behind a configuration switch and do not register as tools until you enable them. Second, this page documents the tool surface as it exists; the broader social-publishing feature set around it is still being rolled out, and its documentation lands when it does.

How your agents use it

• "Draft a thread about the release notes." — the agent pre-flights with x_check_compliance, x_check_cadence, and x_estimate_cost, then calls x_draft_thread. The draft waits in your review queue; only your approval in the app publishes it.
• "What is pending, and what did the last posts do?" — x_list_drafts and x_get_scheduled_jobs for the pipeline, x_get_post_metrics_history and x_get_benchmarks for stored performance data.

Prerequisites

A connected X account, authorized through the app's integration settings, and the automation daemon running (Dashboard ▸ Platform Health). The inbound tool group requires its explicit configuration switch. Settings live in the configuration reference.

Tool reference

Tool	Parameters	What it does
x_draft_post	account_id*: string, text*: string, media_paths: array, in_reply_to_tweet_id: string, poll_options: array, poll_duration_minutes: integer, content_type: string, language: string, extras: object	Create a single-tweet draft on X. Goes into the HITL queue (status='drafted' or 'blocked' if compliance fails). A human reviews + approves via the Command Center's PostReviewSurface — agents do NOT auto-approve. Supports optional media attachments, reply context (in_reply_to_tweet_id), or a poll. For threads use x_draft_thread instead. Quote tweets are not available (PPU-removed Apr 20, 2026). Cost preview: call x_estimate_cost first if the post will contain a URL.
x_draft_thread	account_id*: string, tweets*: array, content_type: string, language: string, extras: object	Create a multi-tweet thread draft on X. Each tweet's text + optional media is specified independently. The thread is posted as in-reply-to chain on approval. COST OPTIMIZATION: putting URLs only in the LAST tweet costs $0.20 + N×$0.015 instead of N×$0.20. Call x_estimate_cost on the payload first to see the optimization hint. Maximum 25 tweets. Goes into HITL queue.
x_update_draft	post_id*: string, body_text: string, sidecar: object, recompute_compliance: boolean	Edit an existing draft's body text and/or sidecar payload. Optionally re-runs C01-C13 compliance checks. Used to iterate on a draft before human approval. The post must still be in a non-terminal status.
x_cancel_draft	post_id*: string	Cancel/withdraw a draft post. Allowed from drafted, blocked, review_pending, approved, or scheduled status. Moves filesystem to archive/cancelled/. If the post was scheduled, also removes the APScheduler job. Distinct from x_reject_draft (HUMAN-only via CC) which writes a reviewer rejection audit entry.
x_list_drafts	status: string, content_type: string, limit: integer	List X posts (drafts, scheduled, published, etc.) with optional filters. DB-only read — no X API call, no cost.
x_get_draft	post_id*: string	Get a single post's full detail (row + metric snapshots + media list). DB-only read.
x_list_accounts	—	List configured X accounts (status, oauth_kind, warmup_phase, monthly_budget_cap). Token data is NOT returned — only public account metadata. DB-only read.
x_get_account	account_id*: string	Get a single X account's metadata. Token data is NOT returned. DB-only read.
x_get_master_pause	—	Get the current master pause state. When paused, all approve+publish flows are blocked across all platforms. Set/unset is HUMAN-only via CC AutoPublishMatrix.
x_get_scheduled_jobs	—	List currently-pending APScheduler social-publish jobs (post_id, scheduled_at, job_id). Includes jobs for all platforms — filter client-side by post_id after fetching x_get_draft if you need X-only.
x_estimate_cost	payload*: object	Estimate publishing cost for a hypothetical X payload. Returns per-tweet breakdown + total + thread cost optimization hint when applicable. PPU pricing (post Apr 20, 2026): $0.20 URL post / $0.015 standard / $0.001 owned-read. Pure computation — no DB write, no API call.
x_check_compliance	body_text*: string, sidecar*: object, content_type: string, account_id: string	Run C01-C13 deterministic compliance checks against a hypothetical X payload. Returns a ComplianceReport with findings grouped by check. No DB write. Useful before x_draft_post to preview compliance state.
x_check_cadence	account_id*: string	Get the cadence-ramp state for an X account (warmup phase A/B/steady/mature, days since creation, posts today, daily cap). Per R1 §7.4: cap is 1-2/day first 7 days, 2-4 days 8-30, 3-5 days 31-90, 3-7 mature. Auto-promotion of warmup_phase fires inside check_cadence_allowed when actually disposing a publish — reading state via this tool does not modify state.
x_get_budget_status	account_id*: string	Get the current calendar month's running spend vs the account's monthly_budget_cap. Default cap is $50/month per account. Pure DB read.
x_get_post_metrics_history	post_id*: string	Get all engagement metric snapshots for a published post (+1h / +24h / +7d polling windows). Returns recorded snapshot history — does NOT trigger a fresh API poll. DB-only read.
x_get_account_snapshots	account_id*: string, since: string, limit: integer	Get follower-count snapshots for an X account (nightly cron at 03:00 UTC). DB-only read — does NOT trigger a fresh API call.
x_get_benchmarks	platform: string, content_type: string, window_days: integer	Get performance benchmarks per (platform, content_type, window_days). Computed nightly at 04:00 UTC; skipped when post_count < 5 per window. Filters optional.
x_search	account_id*: string, query*: string, max_results: integer, since_id: string	[INBOUND] Tweepy search_recent_tweets — search the last 7 days. Cost: $0.005/tweet returned. Inbound calls are GATED — only available when X_MCP_INBOUND_ENABLED=1 in the MCP env.
x_get_tweet	account_id*: string, tweet_id*: string	[INBOUND] Single tweet lookup by ID. Cost: $0.001 owned-read for own tweets / $0.005 non-owned for others.
x_get_user_tweets	account_id*: string, username*: string, max_results: integer	[INBOUND] Recent tweets from a specific user (excludes retweets and replies). Cost: 1 owned-read for username lookup + N non-owned reads. For bulk feed harvesting, prefer Nitter RSS via observer.
x_list_mentions_live	account_id*: string, since: string	[INBOUND] Live pull of the authenticated account's recent mentions. Cost: $0.001 (owned-read for /users/me) + reads for mentions. For passive monitoring use observer's Nitter pipeline.
x_account_health_live	account_id*: string	[INBOUND] Live /users/me health check. Returns auth_status, rate-limit headroom, and resets-at. Cost: $0.001 (owned-read).

Where to go next

• The operator model — the approval gate every outbound draft sits behind
• Configuration — integration settings and the inbound switch