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
}
Fetch trending tweets
{
"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.