// connections

X (Official API)

Post, reply, quote, delete posts, like, retweet, bookmark, follow and send direct messages as your own X account. Connect with your X developer app's four OAuth 1.0a keys.

8 mcp tools12 operations
rest
https://api.superagnt.com/v1/connections/x-official plus the vendor's own path, with your superagnt_ API key as Authorization: Bearer.
mcp
Tools named connection_x_official_* on https://mcp.superagnt.com/mcp, served once the account is connected.
billing
X (Official API) bills your own account. Calls cost no superagnt_ data credits.
rate limit
5 requests a second, 300 a minute: the vendor's ceiling as the registry records it, for sizing bursts. Your plan's own limit is on Connections.
vendor docs
https://docs.x.com/x-api/introduction

The X (Official API) connection lets an agent act as your X account through the official X API v2. It publishes posts, replies, quotes and polls, deletes the account's posts, likes, retweets and bookmarks posts and undoes them, follows and unfollows users, and sends direct messages.

reading public posts and profiles

This connection acts on the connected account only. To read public X data (profiles, posts, search), use the cheaper X data source and its data_x_users, data_x_posts and data_x_discover tools, which need no X developer app.

01

Setup

  1. Set the app permissions. In the X developer portal, open your app's User authentication settings and set app permissions to Read and write and Direct message.
  2. Copy the API key. Under Keys and tokens, copy the API Key and API Key Secret.
  3. Generate the access token. Under Keys and tokens, generate the Access Token and Secret after changing the permissions. A token made before the change stays read-only, and every post fails with a 403.
  4. Connect X. In the superagnt app open Integrations, pick X (Official API), paste all four keys and press Connect.

superagnt_ signs every request with the four keys (OAuth 1.0a), so there is no token to refresh. The keys do not expire, and X bills API usage to your developer account.

02

Things to know

  • Liking, retweeting, bookmarking and following take your own X user id in the path, not a @username. Get it once from connection_x_official_users_read action me.
  • A post is up to 280 characters on a standard account, more with X Premium. For a reply set reply.in_reply_to_tweet_id. For a quote set quote_tweet_id.
  • A poll takes 2 to 4 options and runs 5 minutes to 7 days (duration_minutes). It cannot be combined with media or a quote.
  • A direct message opens a one-to-one conversation if there is none, and reaches only a user who accepts direct messages from your account.
  • Deleting a post cannot be undone.
  • Posting, deleting a post, retweeting and sending a direct message always ask a person first by default. Liking, bookmarking, following and every undo ask. Reading the account runs without asking (Permissions).
  • The connection does not cover reading posts, timelines, search, followers or received messages, or uploading media: media.media_ids on a post must come from an upload made elsewhere.

03

Examples

Who is connected

the connected account and its idbash
curl "https://api.superagnt.com/v1/connections/x-official/2/users/me" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY"

Publish a post

post as the connected accountbash
curl -X POST "https://api.superagnt.com/v1/connections/x-official/2/tweets" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Our Q4 changelog is live."}'

Like a post

like with your own user idbash
curl -X POST "https://api.superagnt.com/v1/connections/x-official/2/users/<your user id>/likes" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tweet_id": "1850000000000000000"}'
04// mcp tools

8 tools, one per resource and risk

MCP servers and agents on the grouped surface list X (Official API) as these tools. Each takes an action, and the ones that work across record types an object. Every operation also keeps its own per-operation name, in the next table, which works on every server. How grouping works: Grouped tools.

ToolRiskActions
connection_x_official_users_read

Read the connected X account

Get the connected X account and its user id, which liking, retweeting, bookmarking and following (and undoing them) need. For public X data use the cheaper data tools: data_x_users for profiles, data_x_posts for posts and data_x_discover for search.

read
me
connection_x_official_posts_write

Post on X

Publish a post as the connected account: a post, a reply, a quote or a poll.

write
create
connection_x_official_posts_delete

Delete an X post

Delete one of the connected account's posts. Cannot be undone.

destructive
delete
connection_x_official_engagements_write

Like, retweet and bookmark on X

Like, retweet or bookmark a post as the connected account (id is its own user id).

write
likeretweetbookmark
connection_x_official_engagements_delete

Undo X likes, retweets and bookmarks

Undo a like, retweet or bookmark of the connected account.

destructive
unlikeunretweetunbookmark
connection_x_official_follows_write

Follow on X

Follow a user as the connected account.

write
follow
connection_x_official_follows_delete

Unfollow on X

Unfollow a user as the connected account.

destructive
unfollow
connection_x_official_dms_send

Send an X direct message

Send a direct message to a user as the connected account.

write
send
05// operations

All 12 operations

Each operation is a REST path under https://api.superagnt.com/v1/connections/x-official and an MCP tool. The per-operation tool name is the one permissions, approvals and usage records use.

OperationMCP tool
GET/2/users/me

Get the authenticated user

connection_x_official_getauthenticatedusergrouped: connection_x_official_users_read, action me
POST/2/tweets

Create a post

connection_x_official_createtweetgrouped: connection_x_official_posts_write, action create
DELETE/2/tweets/{id}

Delete a post

connection_x_official_deletetweetgrouped: connection_x_official_posts_delete, action delete
POST/2/users/{id}/likes

Like a post

connection_x_official_liketweetgrouped: connection_x_official_engagements_write, action like
DELETE/2/users/{id}/likes/{tweet_id}

Unlike a post

connection_x_official_unliketweetgrouped: connection_x_official_engagements_delete, action unlike
POST/2/users/{id}/retweets

Retweet a post

connection_x_official_retweettweetgrouped: connection_x_official_engagements_write, action retweet
DELETE/2/users/{id}/retweets/{source_tweet_id}

Undo a retweet

connection_x_official_unretweettweetgrouped: connection_x_official_engagements_delete, action unretweet
POST/2/users/{id}/following

Follow a user

connection_x_official_followusergrouped: connection_x_official_follows_write, action follow
DELETE/2/users/{source_user_id}/following/{target_user_id}

Unfollow a user

connection_x_official_unfollowusergrouped: connection_x_official_follows_delete, action unfollow
POST/2/users/{id}/bookmarks

Bookmark a post

connection_x_official_bookmarktweetgrouped: connection_x_official_engagements_write, action bookmark
DELETE/2/users/{id}/bookmarks/{tweet_id}

Remove a bookmark

connection_x_official_unbookmarktweetgrouped: connection_x_official_engagements_delete, action unbookmark
POST/2/dm_conversations/with/{participant_id}/messages

Send a direct message

connection_x_official_senddirectmessagegrouped: connection_x_official_dms_send, action send