Referencia de herramientas MCP

Herramientas MCP de Twexapi para descubrimiento de endpoints, llamadas autenticadas a la API, handoff de flujos y ejecución segura de agentes.

El servidor MCP de la API de Twexapi expone 2 herramientas: explore y twexapi_request. Conéctate a https://api.twexapi.io/mcp con x-api-key o auth Bearer OAuth 2.1.

Los agentes deben usar explore para inspeccionar el catálogo de la API antes de llamar a twexapi_request. Esto mantiene la selección de endpoints explícita, ayuda al agente a preservar los esquemas de solicitud y evita llamadas accidentales a rutas no disponibles mediante MCP.

Herramientas

explore

Busca en el catálogo de endpoints de la API. Solo lectura, sin llamadas de red a X/Twitter y sin consumo de créditos de endpoints. La llamada aún requiere autenticación MCP mediante API key o token Bearer OAuth.

Usa explore para descubrir endpoints disponibles, verificar parámetros, comparar categorías y encontrar la ruta de API correcta antes de ejecutar llamadas.

Entrada

Forma del catálogo

interface EndpointInfo {
  name: string;
  method: string;
  path: string;
  category: string;
  description: string;
  read_only: boolean;
  parameters_schema?: Record<string, unknown>;
  example?: {
    method: string;
    path: string;
    query?: Record<string, unknown>;
    body?: unknown;
  };
}

Ejemplos

Encuentra endpoints de tendencias:

{
  "category": "trending"
}

Busca por palabra clave:

{
  "query": "advanced search tweets"
}

Incluye endpoints con capacidad de escritura:

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

twexapi_request

Ejecuta llamadas a la API contra tu cuenta de Twexapi. La autenticación se inyecta automáticamente desde la solicitud MCP, así que los agentes solo pasan el método del endpoint, la ruta relativa y datos opcionales de query/body.

Entrada

Contrato de respuesta

twexapi_request devuelve metadatos de ejecución MCP más la respuesta REST subyacente:

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

Preserva campos duraderos de result, incluyendo IDs, cursors, task IDs, campos de créditos e IDs de acciones de escritura. Cuando una página incluye has_more y next_cursor, pasa el cursor al endpoint de seguimiento o parámetro de query documentado devuelto por explore.

Ejemplos de flujos de trabajo

Estos ejemplos muestran la forma que un agente debe producir. Ejecuta explore primero en uso real para que el agente pueda confirmar el esquema actual.

Buscar tweets con filas de handoff

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

Pide al agente que devuelva un objeto compacto de handoff:

{
  "source": "twexapi_mcp",
  "job": "tweet_search",
  "route_used": "/twitter/advanced_search/page",
  "query": "from:openai AI agents",
  "rows": [
    {
      "tweet_id": "1803006263529541838",
      "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
  }
}

Almacena country, topic, content, tweet IDs, usernames de autores, campos de engagement, has_more y next_cursor cuando estén presentes.

Exportar seguidores a un CRM

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

Almacena user_id, username, name, description, followers_count, la cuenta fuente y campos de paginación/tarea. Si el endpoint devuelve un task ID, almacénalo y consulta el endpoint de status/next documentado.

Leer un artículo de X como Markdown

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

Almacena el ID del artículo, título, autor, cuerpo Markdown, enlaces extraídos y URL fuente.

Publicar un tweet o respuesta

{
  "method": "POST",
  "path": "/twitter/tweets/create",
  "body": {
    "tweet_content": "Hello from Twexapi MCP",
    "reply_tweet_id": null,
    "media_url": null
  }
}

Almacena tweet_id, write_action_id, status, charged_credits, el objetivo de la respuesta, URLs de medios y el registro de confirmación del usuario.

Patrones de handoff de agentes

MCP devuelve JSON. Para colas de agentes, CRMs, hojas de cálculo, data warehouses y flujos no-code, devuelve un objeto duradero pequeño con el job original, la ruta usada, filas o IDs normalizados para almacenar y el siguiente cursor o tarea a consultar.

Buscar tweets a JSON

Llama a POST /twitter/advanced_search/page. Almacena tweet IDs, texto, metadatos del autor, hora de creación, enlaces, has_more, next_cursor y la query original.

Extraer respuestas

Llama a GET /twitter/tweets/{tweet_id}/replies/{count} para una página acotada o GET /twitter/tweets/{tweet_id}/replies/page para paginación por cursor. Almacena reply IDs, usernames de autores, texto, métricas, has_more y next_cursor.

Exportar seguidores

Llama a GET /twitter/followers/{screen_name}/{count} o los endpoints page/task devueltos por explore. Almacena user IDs, usernames, nombres, bios, cantidades de seguidores, cuenta fuente, task ID y siguiente cursor.

Rastrear acciones de escritura

Para endpoints de escritura, almacena la ruta del endpoint, hash del body o texto de confirmación, tweet ID o write action ID devuelto, status, créditos cobrados y referencias de medios.

Enviar DMs

Llama al endpoint de DM solo después de la confirmación del usuario. Almacena message ID, user ID del destinatario, cuenta, referencias de medios y status de entrega. Mantén los cuerpos completos de DM fuera de las salidas MCP compartidas.

Categorías de endpoints

Manejo de errores

Cuando falla la autenticación MCP, la herramienta no se ejecuta. El cliente recibe un error JSON-RPC:

{
  "jsonrpc": "2.0",
  "error": {
    "code": 401,
    "message": "Missing MCP API token"
  }
}

Cuando twexapi_request se ejecuta y la API subyacente de Twexapi devuelve una respuesta no 2xx, preserva los metadatos MCP y el error de Twexapi:

{
  "status_code": 403,
  "endpoint": "get_global_trending_tweets",
  "method": "GET",
  "path": "/twitter/global-trending/tweets",
  "result": {
    "detail": "Credits exhausted or action not allowed."
  }
}

Consulta Error Handling y Rate Limits para patrones de recuperación REST y MCP.