---
title: "Transfert MCP pour agents"
description: "Instructions pour transférer en toute sécurité l'accès Twexapi MCP aux agents IA et aux workflows en aval."
---

Utilisez cette page lorsque vous donnez l'accès Twexapi MCP à un agent de codage IA, un agent de recherche, un agent de workflow ou un assistant interne.

En bref : connectez le serveur MCP API, donnez une clé API à l'agent, demandez-lui d'appeler `explore` avant `twexapi_request`, et exigez une sortie de transfert durable au lieu de résumés uniquement dans le chat.

## Liste de contrôle de transfert

1. **Connecter le serveur MCP API**

    Ajoutez `https://api.twexapi.io/mcp` à votre client MCP avec `x-api-key` ou `Authorization: Bearer <token>`.

2. **Connecter le serveur Docs MCP**

    Ajoutez `https://docs.twexapi.io/mcp` lorsque l'agent doit rechercher la documentation Twexapi avant de choisir les routes API.

3. **Découvrir avant d'appeler**

    Demandez à l'agent d'appeler `explore` d'abord, avec une requête ou une catégorie correspondant à la tâche.

4. **Exiger des chemins relatifs**

    Demandez à l'agent d'appeler `twexapi_request` uniquement avec les chemins relatifs renvoyés par `explore`.

5. **Conserver les champs de transfert**

    Exigez les ID, curseurs, ID de tâche, noms de routes, statut et champs de crédits dans la sortie finale.

6. **Gérer les écritures avec prudence**

    Exigez une confirmation utilisateur explicite avant tout endpoint où `read_only` est `false`.

## Liste de contrôle des routes agent

### Lire la documentation d'abord

Utilisez Docs MCP à `https://docs.twexapi.io/mcp` pour la documentation publique, les paramètres API, les instructions de configuration, les codes d'erreur, les conseils SDK et les exemples.

### Découvrir la route API

Utilisez API MCP `explore` pour trouver l'endpoint exact, la méthode, le schéma de requête, la catégorie et le drapeau de sécurité.

### Exécuter l'appel API

Utilisez API MCP `twexapi_request` avec la méthode et le chemin relatif exacts renvoyés par `explore`. Transmettez uniquement les champs `query` et `body` documentés.

### Persister en dehors du chat

Utilisez REST, les SDK, une file d'attente ou un outil de workflow lorsqu'un backend doit gérer les retries, le stockage de curseurs, les téléchargements de fichiers, les tâches planifiées ou l'orchestration par lots.

### Transférer les résultats

Stockez le chemin d'endpoint, les paramètres de requête, les ID renvoyés, `has_more`, `next_cursor`, les ID de tâche, les ID d'action d'écriture, les crédits facturés et toute route d'export ou de polling avant de terminer l'exécution de l'agent.

## Instruction d'agent à copier-coller

Collez ceci dans les instructions système, les instructions de projet ou l'invite de tâche de votre agent :

```txt
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 `twexapi_request` with the exact method and a relative path from the returned catalog entry.

Rules:
- Never call absolute URLs through `twexapi_request`.
- 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 any catalog entry with `read_only: false` as a production action.
- Ask for explicit user confirmation before posting, replying, liking, retweeting, following, blocking, bookmarking, deleting, sending DMs, or making any other write call.
- 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.
- For downstream workflows, return compact JSON with route_used, request, rows or ids, has_more, next_cursor, and next_step.
```

## Workflows courants

### Rechercher des sujets tendances

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

Route recommandée :

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

Champs de transfert : `country`, `topic`, `content`, `tweet_id`, `author_username`, `created_at`, métriques d'engagement, `has_more`, `next_cursor`.

### Rechercher des tweets

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

Route recommandée :

1. `explore(query="advanced search tweets")`
2. `twexapi_request` pour `/twitter/advanced_search/page`
3. Utilisez `/twitter/advanced_search/page` si le catalogue renvoie un flux de pagination

Champs de transfert : requête d'origine, mode de tri, `tweet_id`, texte, métadonnées auteur, heure de création, URL directe, `has_more`, `next_cursor`.

### Exporter des abonnés

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

Route recommandée :

1. `explore(category="followers")`
2. `twexapi_request` pour `/twitter/followers/{screen_name}/{count}` ou un endpoint page/tâche renvoyé par `explore`

Champs de transfert : compte source, `user_id`, `username`, nom, bio, nombre d'abonnés, statut vérifié, ID de tâche, `has_more`, `next_cursor`.

### Scraper des réponses

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

Route recommandée :

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

Champs de transfert : ID du tweet source, ID de réponse, nom d'utilisateur auteur, texte, métriques, index de page, `has_more`, `next_cursor`.

### Récupérer des articles X

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

Route recommandée :

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

Champs de transfert : ID d'article, titre, auteur, corps Markdown, liens extraits, URL source, résumé généré.

### Exécuter une action d'écriture

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

Route recommandée :

1. `explore(query="create tweet", include_writes=true)`
2. Présentez le corps d'écriture exact à l'utilisateur
3. Attendez une confirmation explicite
4. `twexapi_request` pour l'endpoint d'écriture renvoyé

Champs de transfert : texte de confirmation, méthode, chemin, corps de requête, `tweet_id`, `write_action_id`, statut, crédits facturés, cible de réponse, URL média.

## Contrat de sortie de transfert

Pour les workflows durables, demandez à l'agent de renvoyer du JSON 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
}
```

Utilisez `rows` pour les enregistrements destinés à un CRM, une feuille de calcul, une base de données ou une file d'attente. Utilisez `ids` lorsque le worker suivant n'a besoin que d'identifiants durables.

## Modèle de sécurité

Twexapi MCP a trois garde-fous importants :

| Garde-fou | Comportement |
| --- | --- |
| Auth par clé API | MCP utilise la même validation de clé API, vérifications de crédits et contrôles de compte que l'API REST. |
| Chemins sur liste blanche | `twexapi_request` rejette les endpoints hors du catalogue MCP. |
| Drapeaux d'écriture | Les actions à effet de bord sont marquées `read_only: false` pour que les agents puissent demander une confirmation. |

## Gestion des erreurs

Lorsque l'authentification MCP échoue, l'outil ne s'exécute pas. Conservez l'erreur JSON-RPC :

```json
{
  "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, demandez à l'agent de conserver le résultat de l'outil :

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

Interprétations utiles :

| Statut | Signification |
| --- | --- |
| `401` | L'authentification MCP a échoué avant l'exécution de l'outil ; vérifiez `x-api-key` ou l'auth Bearer. |
| `403` | La clé API est indisponible, les crédits sont épuisés ou l'action n'est pas autorisée. |
| `429` | Limite de débit dépassée. Réessayez après la fenêtre de limite. |
| `5xx` | Défaillance côté service ou problème de récupération X/Twitter en amont. |

## Conseils de production

- Utilisez une clé API à portée limitée lorsque l'agent n'a besoin que d'un workflow spécifique.
- Préférez les workflows en lecture seule pour les agents autonomes.
- Journalisez les invites, corps de requête, noms de routes et réponses MCP pour les workflows d'écriture.
- Exigez une approbation humaine avant les appels `read_only: false`.
- Gardez cookies, auth tokens, clés API et texte DM privé hors des messages finaux visibles par l'utilisateur.
- Stockez curseurs et ID de tâche en dehors du chat lorsqu'un autre worker doit continuer la tâche.
- Utilisez REST direct ou les SDK générés pour les tâches de production planifiées qui ont besoin de retries, de mise en file d'attente et de stockage durable.