Skip to content
Twexapi
English
Esc
↑↓navigate↵open⌘Jpreview
On this page

MCP tools reference

TwexAPI MCP tools for endpoint discovery, read-only X data calls, posting, workflow handoff, and safe agent execution.

The TwexAPI API MCP server at https://api.twexapi.io/mcp exposes three tools: explore, twexapi_request, and twexapi_write. Connect by signing in or with an API key.

Agents should call explore first to find the endpoint, then call the tool that explore names for it. Reads and writes are separate tools so clients such as Claude can run reads freely and ask before every write.

Tools

Tool Purpose Annotations Listed
explore Search the endpoint catalog: methods, paths, categories, parameters, examples, and the tool to call. Read-only, idempotent Always
twexapi_request Call a read-only endpoint with a relative path. Read-only Always
twexapi_write Call a write endpoint (posting a tweet or reply). Destructive, not idempotent Only with write access

twexapi_write is not listed when the user signed in read-only (scope mcp:read) or when write actions are turned off on the server.

explore

Search the API endpoint catalog. It makes no X/Twitter calls and uses no credits, so it works even when the account has no credits left. It still requires sign-in or an API key.

Input

Name Type Required Description
query string No Keyword search across endpoint name, path, and description.
category string No Exact category filter, such as trending, search, users, or write. See Endpoint categories.
include_writes boolean No Also return write endpoints. They are returned only when the connection has write access.

Results are capped at 50 entries.

Catalog entry

interface EndpointInfo {
  name: string;
  method: string;
  path: string; // may contain {placeholders}; replace them before calling
  category: string;
  description: string;
  read_only: boolean;
  tool: "twexapi_request" | "twexapi_write"; // the tool that calls this endpoint
  cursor_paginated: boolean;
  parameters_schema: Record<string, unknown>; // JSON Schema of method, path, query, body
  example: { method: string; path: string; query?: Record<string, unknown>; body?: unknown };
  mpp_eligible: boolean; // accepts pay-per-call on /mcp/pay
}

Examples

{ "category": "trending" }
{ "query": "advanced search" }
{ "query": "create tweet", "include_writes": true }

twexapi_request

Call a read-only endpoint. Authentication is injected from the MCP connection, so the agent passes only the method, a relative path, and optional query and body.

Input

Name Type Required Description
method string Yes HTTP method from explore, such as GET or POST.
path string Yes Relative path from explore, with placeholders replaced. Absolute URLs are rejected.
query object No Query parameters.
body object, array, or scalar No JSON body for non-GET requests.

Response

The tool returns MCP metadata plus the REST response:

{
  "status_code": 200,
  "endpoint": "list_global_trending_countries",
  "method": "GET",
  "path": "/twitter/global-trending/countries",
  "result": {
    "code": 200,
    "msg": "success",
    "data": []
  }
}

A non-2xx status_code marks the tool result as an error. Preserve IDs, cursors, task IDs, and credit fields from result. When a page includes has_more and next_cursor, pass the cursor to the follow-up endpoint returned by explore.

twexapi_write

Call a write endpoint. It takes the same input and returns the same response shape as twexapi_request. The MCP catalog currently has one write endpoint: POST /twitter/tweets/create, which posts a tweet or a reply.

{
  "method": "POST",
  "path": "/twitter/tweets/create",
  "body": {
    "tweet_content": "Hello from TwexAPI MCP",
    "cookie": "auth_token=...; ct0=...",
    "reply_tweet_id": null,
    "media_url": null
  }
}
Body field Required Description
tweet_content Yes Tweet or reply text.
cookie Yes X cookie or auth_token of the account that posts.
reply_tweet_id No Tweet ID to reply to.
media_url No Public media URL to attach.
schedule No ISO time to schedule the post.
community_name No Community name or ID to post in.
delegated_account_username No Delegated account to post as.
proxy No Proxy URL for the request.

Every twexapi_write call carries an Idempotency-Key derived from its method, path, and body. If a client repeats the exact same call within 10 minutes, for example after a timeout, it gets the first result instead of a second post. See Retry tweet posts safely.

Other write actions, such as likes, retweets, follows, bookmarks, deletions, direct messages, and article publishing, are available through the REST API only.

Calling a write endpoint with twexapi_request, or a read endpoint with twexapi_write, fails with a message that names the right tool.

Workflow examples

These examples show the request an agent should produce. Run explore first in real use so the agent confirms the current schema.

Search tweets

{
  "method": "POST",
  "path": "/twitter/advanced_search/page",
  "body": {
    "searchTerms": ["from:openai AI agents"],
    "maxItems": 20,
    "sortBy": "Latest"
  }
}

Ask the agent to return a compact handoff object:

{
  "source": "twexapi_mcp",
  "job": "tweet_search",
  "route_used": "/twitter/advanced_search/page",
  "query": "from:openai AI agents",
  "rows": [
    {
      "tweet_id": "2104354931595423762",
      "text": "...",
      "author_username": "openai",
      "created_at": "..."
    }
  ],
  "has_more": false,
  "next_cursor": null
}
{
  "method": "GET",
  "path": "/twitter/global-trending/tweets",
  "query": {
    "country": "united-states",
    "topic": "technology",
    "content": "AI",
    "count": 20
  }
}

Export followers

{
  "method": "GET",
  "path": "/twitter/followers/openai/50"
}

For large exports, use POST /twitter/followers/page with cursors, or the task endpoints (/twitter/followers/task/{task_id}/status and /next) returned by explore.

Read an X article as Markdown

{
  "method": "GET",
  "path": "/x/article/2104354931595423762/markdown"
}

Endpoint categories

The catalog has 55 read-only endpoints and 1 write endpoint:

Category Endpoints
trending Trend countries, topics, content tags, trending tweets, and per-country trends.
search Advanced search (single call and paginated), hashtags, and cashtags.
users Users by ID, user search, blue-verified and organization checks, and account status.
tweets Tweet lookup, threads, similar tweets, and replies (count-based and paginated).
followers Followers and following: latest, by count, paginated, long-running tasks, and follow relationship checks.
engagement Retweeters, favoriters, and quote tweets.
communities Community details, search, members, and tweets.
lists List search, tweets, members, and subscribers.
timeline User timelines and tweets-and-replies pages.
articles X articles by ID and as Markdown.
accounts Where accounts are based and their “About this account” details.
dm Direct message reachability for users (read-only).
write Posting a tweet or reply.

Error handling

When the connection is not authorized, no tool runs and the client receives a JSON-RPC error with HTTP 401 or 403:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": 401,
    "message": "Sign in through your MCP client, or send your TwexAPI API key in the Authorization header. For pay-per-call without an API key, use /mcp/pay."
  }
}
Error Meaning
401 “Sign in through your MCP client…” No credentials. Clients that support sign-in start it from this response.
401 “Invalid or unavailable MCP API token” The API key is not valid.
401 “Access token is invalid or expired” The sign-in expired or was revoked. Sign in again.
403 “This TwexAPI API key is disabled…” Re-enable the key in the dashboard.
403 “No usable API key on this account…” The signed-in account has no active API key. Create one in the dashboard.

When the account has no credits left, the connection still works. explore returns results, and other tool calls return an error result without calling the API:

{
  "error": "No credits left on this TwexAPI account. Top up at https://twexapi.io/dashboard and try again."
}

When a tool runs and the REST API returns a non-2xx response, preserve the MCP metadata and the API error:

{
  "status_code": 429,
  "endpoint": "get_global_trending_tweets",
  "method": "GET",
  "path": "/twitter/global-trending/tweets",
  "result": {
    "code": 429,
    "msg": "Rate limit exceeded. QPS limit: 2 requests per second",
    "data": []
  }
}
Status Meaning
4xx Invalid parameters, a resource that does not exist, or an action that is not allowed. Fix the request before retrying.
429 Rate limit exceeded. Retry after the limit window.
5xx Service-side failure or upstream X/Twitter fetch issue. Retry later.

See Error Handling and Rate Limits for recovery patterns.

Was this page helpful?