Référence des outils MCP

Outils Twexapi MCP pour la découverte d'endpoints, les appels API authentifiés, le transfert de workflow et l'exécution agent sûre.

Le serveur MCP API Twexapi expose 2 outils : explore et twexapi_request. Connectez-vous à https://api.twexapi.io/mcp avec x-api-key ou l’authentification Bearer OAuth 2.1.

Les agents doivent utiliser explore pour inspecter le catalogue API avant d’appeler twexapi_request. Cela garde la sélection d’endpoint explicite, aide l’agent à préserver les schémas de requête et empêche les appels accidentels à des chemins non disponibles via MCP.

Outils

explore

Recherchez le catalogue d’endpoints API. Lecture seule, aucun appel réseau X/Twitter, et aucun crédit d’endpoint consommé. L’appel nécessite toujours l’authentification MCP via une clé API ou un jeton Bearer OAuth.

Utilisez explore pour découvrir les endpoints disponibles, vérifier les paramètres, comparer les catégories et trouver le bon chemin API avant d’exécuter des appels.

Entrée

Forme du catalogue

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;
  };
}

Exemples

Trouver les endpoints de tendances :

{
  "category": "trending"
}

Rechercher par mot-clé :

{
  "query": "advanced search tweets"
}

Inclure les endpoints capables d’écriture :

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

twexapi_request

Exécutez des appels API contre votre compte Twexapi. L’authentification est injectée automatiquement depuis la requête MCP, les agents ne passent donc que la méthode d’endpoint, le chemin relatif et les données query/body optionnelles.

Entrée

Contrat de réponse

twexapi_request renvoie les métadonnées d’exécution MCP plus la réponse REST sous-jacente :

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

Préservez les champs durables de result, y compris les ID, curseurs, ID de tâche, champs de crédits et ID d’action d’écriture. Lorsqu’une page inclut has_more et next_cursor, passez le curseur dans l’endpoint de suivi documenté ou le paramètre de requête renvoyé par explore.

Exemples de workflow

Ces exemples montrent la forme qu’un agent devrait produire. Exécutez explore d’abord en usage réel pour que l’agent puisse confirmer le schéma actuel.

Rechercher des tweets avec lignes de transfert

{
  "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": "1803006263529541838",
      "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
  }
}

Stockez country, topic, content, ID de tweets, noms d’utilisateur des auteurs, champs d’engagement, has_more et next_cursor lorsqu’ils sont présents.

Exporter des abonnés vers un CRM

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

Stockez user_id, username, name, description, followers_count, le compte source et les champs de pagination/tâche. Si l’endpoint renvoie un ID de tâche, stockez-le et interrogez l’endpoint de statut/suivant documenté.

Lire un article X en Markdown

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

Stockez l’ID de l’article, le titre, l’auteur, le corps Markdown, les liens extraits et l’URL source.

Publier un tweet ou une réponse

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

Stockez tweet_id, write_action_id, status, charged_credits, la cible de réponse, les URL média et l’enregistrement de confirmation utilisateur.

Modèles de transfert agent

MCP renvoie du JSON. Pour les files d’agents, CRM, feuilles de calcul, entrepôts et workflows no-code, renvoyez un petit objet durable avec la tâche d’origine, la route utilisée, les lignes ou ID normalisés à stocker, et le curseur ou la tâche suivante à interroger.

Recherche de tweets vers JSON

Appelez POST /twitter/advanced_search/page. Stockez les ID de tweets, le texte, les métadonnées d’auteur, l’heure de création, les liens, has_more, next_cursor et la requête d’origine.

Extraire des réponses

Appelez GET /twitter/tweets/{tweet_id}/replies/{count} pour une page bornée ou GET /twitter/tweets/{tweet_id}/replies/page pour la pagination par curseur. Stockez les ID de réponses, noms d’utilisateur des auteurs, texte, métriques, has_more et next_cursor.

Exporter des abonnés

Appelez GET /twitter/followers/{screen_name}/{count} ou les endpoints page/tâche renvoyés par explore. Stockez les ID utilisateur, noms d’utilisateur, noms, bios, compteurs d’abonnés, compte source, ID de tâche et curseur suivant.

Suivre les actions d’écriture

Pour les endpoints d’écriture, stockez le chemin d’endpoint, le hash du corps ou le texte de confirmation, l’ID de tweet ou d’action d’écriture renvoyé, le statut, les crédits facturés et les références média.

Envoyer des DM

Appelez l’endpoint DM uniquement après confirmation utilisateur. Stockez l’ID de message, l’ID utilisateur destinataire, le compte, les références média et le statut de livraison. Gardez les corps complets de DM hors des sorties MCP partagées.

Catégories d’endpoints

Gestion des erreurs

Lorsque l’authentification MCP échoue, l’outil ne s’exécute pas. Le client reçoit une erreur JSON-RPC :

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

Lorsque twexapi_request s’exécute et que l’API Twexapi sous-jacente renvoie une réponse non-2xx, préservez les métadonnées MCP et l’erreur Twexapi :

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

Consultez Error Handling et Rate Limits pour les modèles de récupération REST et MCP.