Referencia de herramientas MCP

Herramientas MCP de TwexAPI para descubrir endpoints, hacer llamadas de solo lectura a datos de X, publicar, entregar flujos y ejecutar agentes de forma segura.

El servidor MCP de la API de TwexAPI en https://api.twexapi.io/mcp ofrece tres herramientas: explore, twexapi_request y twexapi_write. Conéctate iniciando sesión o con una API key.

Los agentes deben llamar primero a explore para encontrar un endpoint y luego a la herramienta que explore indica para ese endpoint. Las lecturas y escrituras usan herramientas separadas, para que clientes como Claude puedan ejecutar lecturas libremente y pedir confirmación en cada escritura.

Herramientas

twexapi_write está oculta cuando el usuario inició sesión en modo de solo lectura (scope mcp:read) o cuando las escrituras están desactivadas en el servidor.

explore

Busca en el catálogo de endpoints. No llama a X/Twitter y no usa créditos, así que funciona aunque la cuenta no tenga créditos. Sí requiere iniciar sesión o una API key.

Entrada

Devuelve hasta 50 resultados.

Entrada del catálogo

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
}

Ejemplos

{ "category": "trending" }

{ "query": "advanced search" }

{ "query": "create tweet", "include_writes": true }

twexapi_request

Llama a un endpoint de solo lectura. La autenticación se inyecta desde la conexión MCP, así que el agente solo pasa el método, la ruta relativa y, opcionalmente, query y body.

Entrada

Respuesta

La herramienta devuelve metadatos MCP junto con la respuesta REST:

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

Un status_code que no es 2xx marca el resultado de la herramienta como error. Conserva los IDs, cursores, IDs de tareas y campos de créditos de result. Cuando una página incluye has_more y next_cursor, pasa el cursor al endpoint de seguimiento que devuelve explore.

twexapi_write

Llama a un endpoint de escritura. La entrada y la respuesta tienen el mismo formato que twexapi_request. Hoy el catálogo MCP tiene un solo endpoint de escritura, POST /twitter/tweets/create, que publica un tweet o una respuesta:

{
  "method": "POST",
  "path": "/twitter/tweets/create",
  "body": {
    "tweet_content": "Hello from TwexAPI MCP",
    "cookie": "auth_token=...; ct0=...",
    "reply_tweet_id": null,
    "media_url": null
  }
}

Cada llamada a twexapi_write lleva un Idempotency-Key derivado de su método, ruta y body. Si un cliente repite exactamente la misma llamada en menos de 10 minutos, por ejemplo tras un timeout, recibe el primer resultado en lugar de publicar dos veces. Consulta Reintentar publicaciones de forma segura.

Otras escrituras, como likes, retweets, follows, marcadores, eliminaciones, DMs y publicación de artículos, solo están disponibles en la API REST.

Llamar a un endpoint de escritura con twexapi_request, o a uno de lectura con twexapi_write, falla con un mensaje que indica la herramienta correcta.

Ejemplos de flujos

Estos son ejemplos de las solicitudes que debería construir un agente. En uso real, haz que el agente ejecute explore primero para obtener el schema actual.

Buscar tweets

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

Pide al agente que devuelva un objeto de handoff compacto:

{
  "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
}

Obtener tweets en tendencia

{
  "method": "GET",
  "path": "/twitter/global-trending/tweets",
  "query": {
    "country": "united-states",
    "topic": "technology",
    "content": "AI",
    "count": 20
  }
}

Exportar seguidores

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

Para exportaciones grandes, usa POST /twitter/followers/page con cursores, o los endpoints de tareas que devuelve explore (/twitter/followers/task/{task_id}/status y /next).

Leer un artículo de X como Markdown

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

Categorías de endpoints

El catálogo tiene 54 endpoints de solo lectura y 1 endpoint de escritura.

Manejo de errores

Si la conexión no está autorizada, no se ejecuta ninguna herramienta y el cliente recibe un error JSON-RPC con HTTP 401 o 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."
  }
}

Cuando la cuenta se queda sin créditos, la conexión sigue abierta. explore devuelve resultados y las demás llamadas a herramientas devuelven un resultado de error sin llamar a la API:

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

Cuando una herramienta se ejecuta y la API REST devuelve una respuesta que no es 2xx, conserva los metadatos MCP y el error de la API:

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

Consulta Manejo de errores y Rate limits para ver cómo recuperarte.