Référence des outils MCP

Outils MCP de TwexAPI pour découvrir les endpoints, lire les données X, publier, transférer des workflows et exécuter des agents en toute sécurité.

Le serveur MCP de l’API TwexAPI à l’adresse https://api.twexapi.io/mcp expose trois outils : explore, twexapi_request et twexapi_write. Connectez-vous par connexion ou avec une clé API.

Les agents doivent d’abord appeler explore pour trouver un endpoint, puis l’outil que explore indique pour cet endpoint. Les lectures et les écritures utilisent des outils distincts, afin que des clients comme Claude puissent exécuter librement les lectures et demander une confirmation pour chaque écriture.

Outils

twexapi_write est masqué lorsque l’utilisateur s’est connecté en lecture seule (scope mcp:read) ou lorsque les écritures sont désactivées sur le serveur.

explore

Recherche dans le catalogue d’endpoints. Il n’appelle pas X/Twitter et ne consomme aucun crédit : il fonctionne donc même si le compte n’a plus de crédits. Il nécessite toutefois une connexion ou une clé API.

Entrée

Renvoie jusqu’à 50 résultats.

Entrée du catalogue

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
}

Exemples

{ "category": "trending" }

{ "query": "advanced search" }

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

twexapi_request

Appelle un endpoint en lecture seule. L’authentification est injectée depuis la connexion MCP : l’agent ne transmet que la méthode, le chemin relatif et, facultativement, query et body.

Entrée

Réponse

L’outil renvoie des métadonnées MCP avec la réponse 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 autre que 2xx marque le résultat de l’outil comme une erreur. Conservez les IDs, curseurs, IDs de tâches et champs de crédits de result. Lorsqu’une page contient has_more et next_cursor, transmettez le curseur à l’endpoint suivant renvoyé par explore.

twexapi_write

Appelle un endpoint d’écriture. L’entrée et la réponse ont le même format que twexapi_request. Aujourd’hui, le catalogue MCP contient un seul endpoint d’écriture, POST /twitter/tweets/create, qui publie un tweet ou une réponse :

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

Chaque appel à twexapi_write porte un Idempotency-Key dérivé de sa méthode, de son chemin et de son body. Si un client répète exactement le même appel dans les 10 minutes, par exemple après un timeout, il reçoit le premier résultat au lieu de publier une seconde fois. Voir Réessayer une publication en toute sécurité.

Les autres écritures, comme les likes, retweets, abonnements, signets, suppressions, messages privés et la publication d’articles, ne sont disponibles que via l’API REST.

Appeler un endpoint d’écriture avec twexapi_request, ou un endpoint de lecture avec twexapi_write, échoue avec un message qui indique le bon outil.

Exemples de workflows

Voici des exemples des requêtes qu’un agent doit construire. En pratique, faites d’abord exécuter explore à l’agent pour obtenir le schéma actuel.

Rechercher des tweets

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

Demandez à l’agent de renvoyer un objet de transfert compact :

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

Récupérer les tweets tendance

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

Exporter des abonnés

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

Pour les gros exports, utilisez POST /twitter/followers/page avec des curseurs, ou les endpoints de tâches renvoyés par explore (/twitter/followers/task/{task_id}/status et /next).

Lire un article X en Markdown

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

Catégories d’endpoints

Le catalogue contient 54 endpoints en lecture seule et 1 endpoint d’écriture.

Gestion des erreurs

Si la connexion n’est pas autorisée, aucun outil ne s’exécute et le client reçoit une erreur JSON-RPC avec le statut HTTP 401 ou 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."
  }
}

Lorsque le compte n’a plus de crédits, la connexion reste ouverte. explore renvoie des résultats, et les autres appels d’outils renvoient un résultat d’erreur sans appeler l’API :

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

Lorsqu’un outil s’exécute et que l’API REST renvoie une réponse autre que 2xx, conservez les métadonnées MCP et l’erreur de l’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": []
  }
}

Consultez Gestion des erreurs et Limites de débit pour savoir comment rétablir la situation.