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

Agent MCP Handoff

Instructions for safely handing Twexapi MCP access to AI agents and downstream workflows.

Use this page when you are giving Twexapi MCP access to an AI coding agent, research agent, workflow agent, or internal assistant.

The short version: connect the API MCP server by signing in or with an API key, instruct the agent to call explore before any other tool, use twexapi_request for reads and twexapi_write only for confirmed writes, and require durable handoff output instead of chat-only summaries.

Handoff checklist

Connect the API MCP server

Add https://api.twexapi.io/mcp to your MCP client and sign in with your TwexAPI account, or send an API key with x-api-key or Authorization: Bearer. Clear the write checkbox at sign-in if the agent never needs to post.

Connect the Docs MCP server

Add https://docs.twexapi.io/mcp when the agent should search Twexapi documentation before choosing API routes.

Discover before calling

Instruct the agent to call explore first, using a query or category that matches the task.

Require relative paths

Instruct the agent to call the tool explore names for each endpoint (twexapi_request or twexapi_write), using only relative paths returned by explore.

Preserve handoff fields

Require IDs, cursors, task IDs, route names, status, and credit fields in the final output.

Handle writes carefully

Require explicit user confirmation before every twexapi_write call.

Agent route checklist

Read docs first

Use Docs MCP at https://docs.twexapi.io/mcp for public documentation, API parameters, setup instructions, error codes, SDK guidance, and examples.

Discover the API route

Use API MCP explore to find the exact endpoint, method, request schema, category, and safety flag.

Execute the API call

Use API MCP twexapi_request for read-only endpoints and twexapi_write for write endpoints, with the exact method and relative path returned by explore. Each explore result names its tool. Pass only the documented query and body fields.

Persist outside chat

Use REST, SDKs, a queue, or a workflow tool when a backend must own retries, cursor storage, file downloads, scheduled jobs, or batch orchestration.

Hand off results

Store the endpoint path, request parameters, returned IDs, has_more, next_cursor, task IDs, write action IDs, charged credits, and any export or poll route before ending the agent run.

Copy-paste agent instruction

Paste this into your agent’s system instructions, project instructions, or task prompt:

You have access to Twexapi MCP servers.

Use Twexapi Docs MCP first when you need product documentation, setup instructions, endpoint docs, authentication details, examples, or error-code explanations.

Use the API MCP tool `explore` before making API calls. Search by query or category to find the correct Twexapi endpoint. Then call the tool named in the catalog entry's `tool` field (`twexapi_request` for reads, `twexapi_write` for writes) with the exact method and a relative path from that entry.

Rules:
- Never call absolute URLs through `twexapi_request` or `twexapi_write`.
- Never call paths that were not returned by `explore`.
- Do not call `/openapi.json`, docs pages, dashboards, or hidden framework routes through API MCP.
- Treat every `twexapi_write` call as a production action. Ask for explicit user confirmation before posting or replying.
- Never repeat an X cookie or auth_token back in your answer.
- Preserve tweet IDs, user IDs, task IDs, cursors, write action IDs, status, credit fields, and response metadata in your final answer when they are useful for auditability.
- If a request fails, report the HTTP status, endpoint name, method, path, and Twexapi error message.
- If a tool returns "No credits left on this TwexAPI account", stop and tell the user to top up; do not retry.
- For downstream workflows, return compact JSON with route_used, request, rows or ids, has_more, next_cursor, and next_step.

Common workflows

Use Twexapi MCP to find trending countries, choose the United States, fetch AI-related trending tweets, and summarize the top themes with tweet IDs.

Recommended route:

  1. explore(category="trending")
  2. twexapi_request for /twitter/global-trending/countries
  3. twexapi_request for /twitter/global-trending/topics
  4. twexapi_request for /twitter/global-trending/tweets

Handoff fields: country, topic, content, tweet_id, author_username, created_at, engagement metrics, has_more, next_cursor.

Search tweets

Search recent posts from @openai that mention AI agents and return the most relevant tweets with IDs, author metadata, and a short summary.

Recommended route:

  1. explore(query="advanced search tweets")
  2. twexapi_request for /twitter/advanced_search/page
  3. Use /twitter/advanced_search/page if the catalog returns a pagination flow

Handoff fields: original query, sort mode, tweet_id, text, author metadata, created time, direct URL, has_more, next_cursor.

Export followers

Export a page of followers for @openai in CRM-ready JSON.

Recommended route:

  1. explore(category="followers")
  2. twexapi_request for /twitter/followers/{screen_name}/{count} or a page/task endpoint returned by explore

Handoff fields: source account, user_id, username, name, bio, follower count, verified status, task ID, has_more, next_cursor.

Scrape replies

Fetch replies for a tweet and return reply IDs, author usernames, text, and engagement fields.

Recommended route:

  1. explore(query="tweet replies")
  2. twexapi_request for /twitter/tweets/{tweet_id}/replies/{count} or /twitter/tweets/{tweet_id}/replies/page

Handoff fields: source tweet ID, reply ID, author username, text, metrics, page index, has_more, next_cursor.

Fetch X articles

Fetch this X article as Markdown and turn it into a concise brief.

Recommended route:

  1. explore(category="articles")
  2. twexapi_request for /x/article/{tweet_id}/markdown

Handoff fields: article ID, title, author, Markdown body, extracted links, source URL, generated summary.

Run a write action

Draft a reply to this tweet, ask me for confirmation, then post only after I approve.

Recommended route:

  1. explore(query="create tweet", include_writes=true)
  2. Present the exact tweet text and reply target to the user
  3. Wait for explicit confirmation
  4. twexapi_write for POST /twitter/tweets/create, with the user’s X cookie in cookie

Posting is the only write available through MCP. Other write actions use the REST API.

Handoff fields: confirmation text, method, path, tweet text, tweet_id, status, charged credits, reply target, media URLs. Never include the cookie.

Handoff output contract

For durable workflows, ask the agent to return compact JSON:

{
  "source": "twexapi_mcp",
  "job": "tweet_search",
  "route_used": "/twitter/advanced_search/page",
  "request": {
    "method": "POST",
    "path": "/twitter/advanced_search/page",
    "query": null,
    "body": {
      "searchTerms": ["from:openai AI agents"],
      "maxItems": 20,
      "sortBy": "Latest"
    }
  },
  "rows": [],
  "ids": [],
  "has_more": false,
  "next_cursor": null,
  "next_step": null
}

Use rows for records that should go into a CRM, spreadsheet, database, or queue. Use ids when the next worker only needs durable identifiers.

Safety model

Twexapi MCP has three guardrails:

Guardrail Behavior
Account auth Sign-in tokens and API keys go through the same API key validation, credit checks, and account controls as the REST API. Sign-in tokens work only on MCP.
Allowlisted paths twexapi_request and twexapi_write reject endpoints outside the MCP catalog.
Separate write tool Writes run only through twexapi_write, which clients mark as destructive and confirm before each call. It is hidden for read-only sign-ins.

Error handling

When MCP authentication fails, no tool runs. Preserve the JSON-RPC error:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": 401,
    "message": "Access token is invalid or expired"
  }
}

When the account has no credits left, the connection still works and explore is free, but other tool calls return:

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

When a tool runs and the underlying Twexapi API returns a non-2xx response, ask the agent to preserve the tool result:

{
  "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": []
  }
}

Useful interpretations:

Status Meaning
401 Authentication failed before any tool ran. Sign in again, or check the API key.
403 The API key is disabled, or the signed-in account has no usable API key.
429 Rate limit exceeded. Retry after the limit window.
5xx Service-side failure or upstream X/Twitter fetch issue.

See the MCP tools reference for every error message.

Production guidance

  • Connect read-only (clear the write checkbox at sign-in) when the agent does not need to post.
  • Prefer read-only workflows for autonomous agents.
  • Log prompts, request bodies, route names, and MCP responses for write workflows.
  • Require human approval before every twexapi_write call.
  • Keep cookies, auth tokens, API keys, and private DM text out of final user-visible messages.
  • Store cursors and task IDs outside chat when another worker needs to continue the job.
  • Use direct REST or generated SDKs for scheduled production jobs that need retries, queueing, and durable storage.

Was this page helpful?