Un client IA peut parler de données sociales sans savoir quel endpoint appeler. C’est un problème d’acheminement, pas un second catalogue. SocQ MCP expose les mêmes API de données publiques que REST : une seule adresse hébergée, trois périmètres d’outils et le même modèle de tâches asynchrones.
Ce guide montre comment connecter Codex, Claude, Cursor et VS Code, choisir un périmètre, lancer une collecte et continuer d’interroger la même tâche. Les détails de configuration se trouvent sur la page MCP. Copiez-y la configuration générée plutôt que d’inventer des champs.

Réponse rapide : connectez-vous à l’endpoint Streamable HTTP hébergé
https://api.socq.ai/mcp. La découverte fonctionne sans clé. La collecte exige une clé API SocQ. Le mode compact enchaînesocq_search_endpoints→socq_describe_endpoint→socq_execute, puis poursuit la tâche renvoyée. Ne considérez pas cet appel execute comme un export synchrone de toutes les lignes.
API officielles des plateformes ou MCP public ?
Les produits officiels d’Instagram, de X, de YouTube et des services comparables restent la bonne porte d’entrée lorsqu’un utilisateur autorise la publication, la messagerie, la publicité ou l’accès à des statistiques privées. MCP n’ajoute aucune de ces autorisations.
SocQ MCP est une porte d’entrée pour les données publiques. Un agent ne peut appeler que des fonctionnalités déjà présentes dans le catalogue d’API. Il ne peut pas publier, ne peut pas lire de comptes privés et ne peut pas inventer un endpoint absent du registre. REST, MCP et la CLI exécutent les mêmes tâches. L’Agent Skill aide un agent à choisir des endpoints et à estimer les crédits ; ce n’est pas un second service de données. Si le produit parle déjà HTTP, gardez REST. Si l’opérateur travaille dans un terminal ou une tâche CI, utilisez la CLI. Si l’opérateur est un agent d’IDE, utilisez MCP.
Choisir un périmètre d’outils plutôt que deviner un endpoint
Un client MCP ne voit que les outils exposés par la connexion en cours. Choisissez le périmètre sur /mcp, puis copiez l’adresse correspondante.
| Périmètre | Adresse | Surface visible | Idéal pour |
|---|---|---|---|
| Compact | /mcp | Outils de découverte, d’exécution, de tâche, de fichier et de compte | Exploration susceptible de couvrir plusieurs plateformes |
| Plateformes | /mcp?platforms=youtube,tiktok | Outils de collecte typés pour cinq plateformes au plus, plus les outils de tâche, de fichier et de compte | Agents qui restent sur un ensemble connu de plateformes |
| Outils précis | /mcp?tools=youtube_comments,x_search | Jusqu’à trente outils typés, plus les outils de tâche, de fichier et de compte | Workflows stables avec une liste d’outils maîtrisée |
platforms et tools s’excluent mutuellement. Après avoir modifié un filtre, reconnectez le client pour qu’il actualise tools/list. Une connexion compacte qui ne se reconnecte jamais continuera de servir l’ancienne liste d’outils.
Vous choisissez toujours une fonctionnalité concrète du catalogue à l’intérieur de ce périmètre. Le mode compact interroge le registre. Les modes plateformes et outils précis appellent un outil typé dont le schéma d’entrée correspond au corps REST de cette ressource.
Une bonne règle par défaut :
- Commencez en mode compact lorsque la question peut passer des commentaires YouTube à la recherche X, puis à une requête Shop.
- Passez en mode plateformes lorsque l’agent ne travaille que sur deux ou trois réseaux.
- Passez en mode outils précis lorsqu’une évaluation de production doit voir une liste d’outils figée.
Ne gardez pas une connexion à cinq plateformes pour demander ensuite au modèle d’« essayer aussi Amazon ». Reconnectez-vous avec Amazon dans le filtre, ou revenez au mode compact.
Connecter un client et garder la clé hors de Git
Faites la configuration en trois étapes, au même niveau que la page MCP :
- Choisissez compact, plateformes ou outils précis.
- Choisissez Codex, Claude, Cursor ou VS Code.
- Copiez la configuration générée et reconnectez-vous.
Fichiers et transports par client :
| Client | Fichier de configuration | Mode de connexion |
|---|---|---|
| Codex | ~/.codex/config.toml | HTTP distant vers l’URL Streamable HTTP hébergée |
| Claude | claude_desktop_config.json | Pont stdio @socq/mcp, Node.js 20+ |
| Cursor | .cursor/mcp.json | Pont stdio @socq/mcp |
| VS Code | mcp.json | Pont stdio, avec la clé saisie via une invite |
La découverte des plateformes, des endpoints et des schémas ne demande pas de clé. La collecte, le compte, les résultats de tâche et les fichiers en demandent une. Stockez SOCQ_API_KEY dans l’environnement ou dans la saisie protégée du client. Ne commitez pas la clé.
Voici l’esquisse d’une configuration Streamable HTTP générique. Préférez le fichier que la page MCP génère pour votre client ; n’ajoutez aucun champ non documenté.
{
"mcpServers": {
"socq": {
"url": "https://api.socq.ai/mcp",
"headers": {
"Authorization": "Bearer ${SOCQ_API_KEY}"
}
}
}
}
Codex communique directement avec cette URL hébergée. Claude, Cursor et VS Code l’atteignent généralement via le pont @socq/mcp publié. Après l’enregistrement, redémarrez ou reconnectez le serveur SocQ dans le client.
REST et MCP partagent une même fonctionnalité
Chaque collecte possède un chemin REST, un ID d’endpoint et un nom d’outil typé. Le mode compact place les champs métier dans input. Les outils typés exposent ce schéma directement.
POST /v1/tiktok/profiles
= endpoint id tiktok-profiles
= typed tool tiktok_profiles
La facturation, les limites et l’enveloppe de la tâche ne changent pas lorsque vous changez de porte d’entrée. Les outils de découverte ne créent pas de tâches de collecte. Si REST rejette une liste de noms d’utilisateur, MCP la rejettera aussi.
Lancer une collecte, puis interroger la même tâche
Le mode compact enchaîne trois outils, puis la poursuite de la tâche :
natural-language request
→ socq_search_endpoints
→ socq_describe_endpoint
→ socq_execute(endpoint, input)
→ task_id
→ socq_get_task
→ results.items
socq_execute valide l’entrée métier et crée une collecte asynchrone. Il peut attendre brièvement, puis renvoie l’état courant. Si la tâche est encore queued ou running, continuez avec le même task_id. Un délai d’expiration côté client n’annule pas la collecte.
Lorsque la tâche réussit, lisez results.items. Tant que has_more vaut true, transmettez next_cursor tel quel. Ne soumettez pas à nouveau le même profil Instagram ou le même nom d’utilisateur TikTok simplement parce que la première page était courte.
Les modes plateformes et outils précis sautent la recherche lorsque l’outil typé est déjà dans le contexte. Le contrat de la tâche ne change pas : créer une fois, conserver l’ID, interroger, paginer.
Exemple d’intention en mode compact, et non une capture de conversation :
Collect the public TikTok profile for @tiktok.
Describe the tiktok/profiles input first.
Execute, wait for the task, then return username, name, visible metrics, and collected_at.
L’agent doit revenir avec un ID de tâche et des éléments normalisés, pas avec l’affirmation que « le profil est arrivé dans un seul résultat d’outil synchrone ».
Conservez la même ligne opérationnelle que pour REST :
- L’ID d’endpoint choisi ou le nom de l’outil typé.
- L’entrée métier canonique.
- L’ID de tâche.
- Le premier état observé et l’état final.
- Le dernier
next_cursorconsommé.
Si le processus de l’agent s’arrête, reprenez cette tâche. Ne laissez pas une boucle de nouvelles tentatives ouvrir cinq tâches identiques sur des profils TikTok.
L’hygiène des entrées reste de votre ressort
MCP n’assouplit pas la validation REST.
- L’
inputdu mode compact doit correspondre au schéma d’endpoint renvoyé parsocq_describe_endpoint. - Les outils typés exposent les mêmes champs obligatoires que
POST /v1/{platform}/{resource}. - Retirez
@ou conservez-le de façon cohérente. Convertissez les URL de profil en noms d’utilisateur dans le prompt ou dans une étape préalable. - N’envoyez pas d’URL de vidéo dans un champ de nom d’utilisateur, ni de nom d’utilisateur dans un champ d’URL de statut.
- Gardez
results_limitcomme plafond. Le catalogue ne promet pas l’exhaustivité. - Si le périmètre omet la plateforme, reconnectez-vous avec un filtre de plateformes ou d’outils qui l’inclut. Ne demandez pas au modèle d’« appeler TikTok quand même ».
Consignez l’ID d’endpoint choisi, les entrées et l’ID de tâche dans votre propre journal. Les agents oublient ; votre table de tâches ne doit pas oublier.
Lire les champs normalisés, pas la prose du chat
Les éléments réussis utilisent la même enveloppe que REST : id, platform, resource, type, url, author, metrics, created_at, collected_at et extra lorsqu’il est présent.
Demandez à l’agent de conserver les valeurs nulles. Un nombre d’abonnés masqué n’est pas égal à zéro. Une transcription absente ne signifie pas « aucune parole ». Les URL de médias sont des références vers la source.
Si vous avez besoin de fichiers, récupérez-les avec l’outil de fichiers de cette tâche. Si vous avez besoin d’une autre page, conservez le curseur. Si vous avez besoin d’une autre ressource, décrivez et exécutez cette ressource ; ne remodelez pas la première réponse en un faux second schéma.
Vérifications minimales avant de faire confiance à une ligne résumée par l’agent :
platformetresourcecorrespondent à l’outil qui a été exécuté.- Au moins un champ parmi
idouurlexiste. - Les métriques sont des nombres ou null, jamais des zéros forcés.
collected_atest présent et n’est pas recopié danscreated_at.- La réponse rédigée peut être rattachée à
results.items, et non à la mémoire du modèle.
Demandez à l’agent de citer les champs, pas de « nettoyer » les valeurs manquantes.
Cadence d’actualisation pour les agents
Les connexions MCP et les tâches de collecte n’ont pas la même horloge.
| Objet | Bonne habitude | Raison |
|---|---|---|
| Périmètre d’outils | Se reconnecter après chaque changement de filtre | Les clients mettent tools/list en cache |
| Découverte | Relancer socq_search_endpoints quand la question change | Le catalogue est vivant ; le résultat précédent peut désigner la mauvaise ressource |
| Tâche de collecte | Interroger le même ID | Soumettre à nouveau duplique le travail |
| Entités de type profil | Chaque semaine ou chaque mois | Les champs d’identité évoluent lentement |
| Publications, commentaires, publicités, produits | De toutes les heures à tous les jours tant que l’activité dure | Les métriques et les annonces publiques évoluent plus vite |
| Serveurs de production à outils précis | Ne changer les outils que lors d’une version planifiée | Une liste d’outils modifiée par surprise casse les évaluations |
N’actualisez pas une tâche terminée pour la « rendre synchrone ». Lancez une nouvelle tâche seulement si les entrées ou la fenêtre de temps ont réellement changé.
Modes de défaillance courants
L’agent indique que la plateforme est absente
La connexion actuelle peut ignorer le mode compact, être limitée à d’autres plateformes ou conserver une ancienne tools/list. Ouvrez /mcp, définissez le périmètre, copiez la configuration, reconnectez-vous.
La collecte est rejetée sans profil exploitable
La découverte n’exige pas de clé. L’exécution, si. Vérifiez SOCQ_API_KEY dans l’environnement ou dans la saisie de VS Code.
Le premier appel d’outil s’est « terminé » sans aucune ligne
La tâche est asynchrone. Lisez son état. Poursuivez avec socq_get_task avant de conclure à un échec ou de soumettre à nouveau.
L’agent invente un outil de publication ou de données privées
Cette fonctionnalité n’existe pas dans le catalogue. Arrêtez-vous. Utilisez un produit OAuth officiel pour les écritures et les statistiques privées.
La pagination s’est arrêtée trop tôt
has_more et next_cursor font partie du résultat, ils ne sont pas facultatifs. Parcourez le curseur jusqu’au bout ou notez que vous vous êtes arrêté volontairement.
Le changement de filtre n’a rien produit
platforms et tools ne peuvent pas être combinés. Reconnectez-vous après le changement.
Usage responsable
Ne collectez que les données publiques nécessaires à un objectif légitime. Ne demandez pas à un agent de contourner des comptes privés, des connexions ou des contrôles d’accès. Gardez les clés hors des prompts que vous collez dans des tickets. Examinez les conditions des plateformes et vos propres règles de conservation.
Ne demandez pas à l’agent de :
- Publier, répondre ou envoyer un DM.
- Ouvrir une vue privée ou connectée.
- Traiter
socq_executecomme un jeu de données terminé. - Combiner
platformsettoolsdans une même URL. - Coder en dur une clé API active dans un fichier de configuration commité.
SocQ MCP est une connexion technique. Elle n’accorde aucun droit supplémentaire sur les contenus et ne transforme pas un scraping non officiel en intégration officielle.
Appliquez la même règle de minimisation des données que dans un worker REST : collectez les champs publics dont le ticket a besoin, puis arrêtez-vous. Un agent disposant d’un accès compact à tout le catalogue continuera volontiers à découvrir des endpoints que vous n’avez pas demandés. Les périmètres restreints existent pour cette raison.
FAQ
SocQ MCP est-il une seconde API sociale ?
Non. C’est une autre porte d’entrée vers le même catalogue que celui utilisé par REST et la CLI.
Puis-je l’utiliser sans clé API ?
Vous pouvez découvrir les plateformes, les endpoints et les schémas. La collecte, le compte, les résultats de tâche et les fichiers demandent une clé.
Pourquoi le mode compact ne liste-t-il pas chaque API comme un outil distinct ?
Le mode compact recherche et décrit un endpoint au moment voulu, ce qui garde l’ensemble des schémas hors du contexte du modèle.
Execute renvoie-t-il toutes les lignes immédiatement ?
Non. Il renvoie une tâche. Poursuivez cette tâche et parcourez results.items page par page.
L’agent peut-il publier sur X ou lire un compte Instagram privé ?
Non. Il ne peut appeler que les fonctionnalités publiques du catalogue.
Quand ajouter le Skill ?
Lorsque l’agent doit choisir des endpoints et estimer les crédits sur une tâche en plusieurs étapes. MCP continue d’exécuter. Les détails sont sur /skill.
Où copier la vraie configuration du client ?
Depuis /mcp : choisissez le périmètre, choisissez le client, copiez, reconnectez-vous.
MULTIPLATEFORME API
Tester le workflow avec une URL publique Multiplateforme
Envoyez des entrées publiques et recevez des enregistrements normalisés, avec un contexte de source traçable.
Découvrir les API Multiplateforme