Aller au contenu

Référence des outils

Chaque outil exposé par le serveur MCP de PostNext, avec ses entrées, la structure de retour et un exemple prêt à copier-coller.

URL du serveur MCPhttps://mcp.postnext.io/api
POST https://mcp.postnext.io/api

Authentification

Chaque requête vers https://mcp.postnext.io/api nécessite un en-tête Authorization avec un jeton Bearer. Vous avez deux façons d'en obtenir un.

OAuth (recommandé pour les clients IA)

Les clients IA exécutent Dynamic Client Registration à la première connexion, puis guident l'utilisateur via un écran de consentement OAuth. La page /mcp/connect le fait automatiquement. Votre client reçoit un jeton d'accès de 30 jours.

Clé API

Pour les scripts et la CI, générez une clé API personnelle dans l'app PostNext via Compte → Clés API. La clé commence par apikey_ et est présentée comme un jeton Bearer ordinaire.

Endpoint

Tous les appels d'outils passent par un seul endpoint JSON-RPC 2.0, en HTTPS POST.

POST https://mcp.postnext.io/api

Outils

list_scheduled_posts

Listez vos publications programmées (en file d'attente pour publication mais pas encore envoyées).

Arguments

limitnumber ·optionnel · default 20
Nombre maximal de résultats à retourner (1-100, défaut 20).
fromstring (ISO 8601) ·optionnel
Horodatage ISO ; retourne uniquement les publications programmées à partir de cette date.

Valeur renvoyée

Un objet avec posts: [{id, platform, content, scheduledAt, status}]. Jusqu'à limit résultats.

Exemple

curl -X POST https://mcp.postnext.io/api \
  -H "Authorization: Bearer apikey_xxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","id":1,
       "params":{"name":"list_scheduled_posts",
                 "arguments":{"limit":5}}}'

list_drafts

Listez vos brouillons (pas encore programmés).

Arguments

limitnumber ·optionnel · default 20
Nombre maximal de résultats à retourner (1-100, défaut 20).

Valeur renvoyée

Un objet avec drafts: [{id, platform, content, updatedAt}]. Jusqu'à limit résultats.

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":2,
 "params":{"name":"list_drafts","arguments":{"limit":10}}}

list_connected_accounts

Listez les comptes sociaux connectés à votre équipe.

Arguments

Aucun argument.

Valeur renvoyée

Un objet avec accounts: [{platform, handle, providerId, connected, lastSyncAt}].

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":3,
 "params":{"name":"list_connected_accounts","arguments":{}}}

get_account_healthOffre payante

Obtenez un résumé de santé sur toutes les plateformes connectées.

Arguments

platformenum ·optionnel
Plateforme sociale : twitter, instagram, linkedin, threads, ou tiktok.
windowDays7 | 30 | 90 ·optionnel · default 30
Période analysée, en jours : 7, 30 ou 90 (30 par défaut).

Valeur renvoyée

Un objet avec windowDays, postsScheduled, postsPublished, postsFailed, une ventilation byPlatform et topErrors[].

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":4,
 "params":{"name":"get_account_health",
           "arguments":{"windowDays":30}}}

create_post_draft

Créez un nouveau brouillon. Les brouillons ne sont pas publiés automatiquement.

Arguments

platformenum ·requis
Plateforme sociale : twitter, instagram, linkedin, threads, ou tiktok.
contentstring ·requis
Corps de la publication (1-2200 caractères).
channelNamestring ·optionnel
Quel compte connecté, quand la plateforme en a plusieurs.
providerIdstring ·optionnel
Le providerId du compte, issu de list_connected_accounts. Il ne change pas quand l'identifiant change : passez-le avec channelName ou à sa place.
mediaUrlsarray<string> ·optionnel
Jusqu'à 10 URL d'images ou de vidéos.
clientRequestIdstring ·optionnel
Clé d'idempotence optionnelle. La même clé dans les 5 minutes renvoie le résultat mis en cache.

Valeur renvoyée

Un objet avec le nouveau brouillon : {id, platform, content, status: "DRAFT", createdAt}.

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":5,
 "params":{"name":"create_post_draft",
           "arguments":{"platform":"twitter",
                        "content":"Hello from MCP"}}}

update_post_draft Offre payante

Mettez à jour un brouillon existant. Au moins l'un des champs content ou mediaUrls doit être fourni.

Arguments

postIdstring ·requis
Identifiant de publication PostNext issu d'un appel de liste.
contentstring ·optionnel
Corps de la publication (1-2200 caractères).
mediaUrlsarray<string> ·optionnel
Jusqu'à 10 URL d'images ou de vidéos.
clientRequestIdstring ·optionnel
Clé d'idempotence optionnelle. La même clé dans les 5 minutes renvoie le résultat mis en cache.

Valeur renvoyée

Un objet avec le brouillon mis à jour : {id, platform, content, mediaUrls, status, updatedAt}.

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":6,
 "params":{"name":"update_post_draft",
           "arguments":{"postId":"",
                        "content":"Updated copy"}}}

connect_channel

Générez une URL à usage unique que l'utilisateur peut ouvrir pour autoriser une nouvelle connexion de plateforme.

Arguments

platformenum ·requis
Plateforme sociale : twitter, instagram, linkedin, threads, ou tiktok.

Valeur renvoyée

Un objet avec authUrl (lien à usage unique que l'utilisateur ouvre pour autoriser), expiresAt et platform.

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":7,
 "params":{"name":"connect_channel",
           "arguments":{"platform":"linkedin"}}}

schedule_post

Place un brouillon (statut DRAFT) dans la file de publication à un horodatage futur. Idempotent avec une marge de ±60 s ; refuse une nouvelle programmation à une autre heure sans annulation explicite préalable. Compte dans les publications mensuelles de l'offre (offre gratuite : 10, partagées avec l'app) ; une publication ne compte qu'une fois, donc la reprogrammer après une annulation ou une publication échouée ne compte pas à nouveau.

Arguments

postIdstring ·requis
Identifiant de publication PostNext issu d'un appel de liste.
scheduledAtstring (ISO 8601) ·requis
Horodatage ISO 8601 ; il ne doit pas dater de plus de 5 minutes.

Valeur renvoyée

Un objet avec postId, scheduledAt (ISO), status: SCHEDULED.

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":8,
 "params":{"name":"schedule_post",
           "arguments":{"postId":"",
                        "scheduledAt":"2026-05-10T09:00:00Z"}}}

cancel_scheduled_post

Annule une publication planifiée et la retire de la file. Le brouillon sous-jacent est conservé.

Arguments

postIdstring ·requis
Identifiant de publication PostNext issu d'un appel de liste.

Valeur renvoyée

Un objet avec postId et status: CANCELLED.

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":9,
 "params":{"name":"cancel_scheduled_post",
           "arguments":{"postId":""}}}

delete_draft

Supprime définitivement un brouillon. Refuse les publications non DRAFT (utilisez cancel_scheduled_post pour SCHEDULED).

Arguments

postIdstring ·requis
Identifiant de publication PostNext issu d'un appel de liste.

Valeur renvoyée

Un objet avec postId et deleted: true.

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":10,
 "params":{"name":"delete_draft",
           "arguments":{"postId":""}}}

get_post

Renvoie le PostGroup complet pour un postId avec le contenu par plateforme + statut + timestamps.

Arguments

postIdstring ·requis
Identifiant de publication PostNext issu d'un appel de liste.

Valeur renvoyée

Un objet avec postId, status, scheduledAt, createdAt, updatedAt et providers (carte plateforme → contenu).

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":11,
 "params":{"name":"get_post",
           "arguments":{"postId":""}}}

search_posts

Recherche de sous-chaîne (insensible à la casse) dans le contenu des publications de l'équipe active. Filtres : status, platform, limit (1-100, défaut 20).

Arguments

querystring ·requis
Sous-chaîne à rechercher (3-200 caractères ; les métacaractères regex sont échappés).
statusenum ·optionnel
Optionnel : DRAFT | SCHEDULED | PUBLISHED | FAILED | CANCELLED.
platformenum ·optionnel
Plateforme sociale : twitter, instagram, linkedin, threads, ou tiktok.
limitnumber ·optionnel · default 20
Nombre maximal de résultats à retourner (1-100, défaut 20).

Valeur renvoyée

Un objet avec posts: [{postId, status, platforms, snippet, scheduledAt, updatedAt}]. Le snippet contient le contexte correspondant avec des points de suspension de chaque côté.

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":12,
 "params":{"name":"search_posts",
           "arguments":{"query":"launch","limit":10}}}

list_teams

Renvoie les équipes dont l'utilisateur authentifié est propriétaire ou admin, l'équipe active étant marquée.

Arguments

Aucun argument.

Valeur renvoyée

Un objet avec currentTeamId et teams: [{teamId, teamName, isCurrent}].

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":13,
 "params":{"name":"list_teams","arguments":{}}}

set_current_team

Change l'équipe active pour ce jeton Bearer. L'utilisateur doit en être membre. Le choix est enregistré sur le document du jeton OAuth ; il s'applique aussitôt aux outils suivants de la même conversation.

Arguments

teamIdstring ·requis
teamId cible depuis list_teams. L'appartenance est revalidée côté serveur.

Valeur renvoyée

Un objet avec teamId, teamName, persisted (true si OAuth, false si clé API) et un champ note facultatif.

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":14,
 "params":{"name":"set_current_team",
           "arguments":{"teamId":"team_xxxxx"}}}

get_plan_limits

Lit le niveau d'abonnement actuel de l'utilisateur et les quotas par palier (canaux, stockage, crédits IA, publication). Disponible dans toutes les offres. Utile avant un outil qui modifie des données, pour savoir si l'appel sera bloqué.

Arguments

Aucun argument.

Valeur renvoyée

Un objet avec tier, tierDisplayName, isPaid, isTrial, limits (channels/storage/aiCalls chacun sous la forme {limit, current, exceeded} ; posts sous la forme {limit, allowed, current}, où current est le nombre de ce mois, ou null s'il n'a pas pu être lu) et creditsAvailable ({total, subscriptionRemaining, purchasedBalance} ou null).

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":15,
 "params":{"name":"get_plan_limits","arguments":{}}}

get_post_metrics

Récupère les métriques d'engagement d'une publication sur chaque plateforme où elle a été envoyée. Twitter renvoie j'aime, retweets, réponses et impressions ; Instagram renvoie j'aime et commentaires. LinkedIn, Threads et TikTok ne renvoient que le statut de publication et l'URL (la collecte de l'engagement viendra dans une version ultérieure). Un total normalisé additionne les métriques des plateformes qui en ont fourni.

Arguments

postId Identifiant de publication PostNext issu d'un appel de liste.

Valeur renvoyée

Un objet avec postId, status, providers: [{platform, publishedPostId, publishedUrl, publishedAt, status, metrics}] et totals: {likes, comments, shares, impressions}. metrics est un objet de compteurs numériques par plateforme, ou null lorsque la plateforme ne collecte pas encore l'engagement.

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":16,
 "params":{"name":"get_post_metrics",
           "arguments":{"postId":""}}}

get_publish_status

Diagnostique une publication planifiée : état de la file, succès/erreur par plateforme, temps de traitement et jobId du worker. Renvoie isScheduled=false pour les publications qui existent en brouillon mais n'ont pas été placées dans la file, avec un hint qui renvoie à schedule_post.

Arguments

postId Identifiant de publication PostNext issu d'un appel de liste.

Valeur renvoyée

Un objet avec postId, isScheduled, status, scheduledAt, publishedAt, platforms, processingTimeMs, jobId, topLevelError et results: [{platform, success, publishedPostId, publishedAt, error}]. Inclut hint quand isScheduled est false.

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":17,
 "params":{"name":"get_publish_status",
           "arguments":{"postId":""}}}

update_brand_profile Offre payante

Met à jour le profil de marque actif de l'utilisateur. Champs autorisés : bio, brandVoice, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize. Tout autre champ est ignoré sans avertissement. Le profil « actif » est d'abord le profil par défaut de l'équipe, puis le premier profil actif de l'utilisateur.

Arguments

brandVoice Tableau de descripteurs de ton de marque (p. ex. ["professionnel", "concis"]).

Other patchable fields: bio, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize.

Valeur renvoyée

Un objet avec profileId, name, updated: [noms des champs modifiés] et les valeurs actuelles de bio, brandVoice, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize après la modification.

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":18,
 "params":{"name":"update_brand_profile",
           "arguments":{"brandVoice":["professional","concise"]}}}

get_best_time_to_post Offre payante

Recommande les N meilleurs créneaux (jour de la semaine, heure) pour la prochaine publication sur une plateforme, d'après les 90 derniers jours. Twitter et Instagram sont classés par engagement par publication ; LinkedIn, Threads et TikTok uniquement par fréquence de publication. Heures dans le fuseau IANA fourni (UTC par défaut). Offre payante requise.

Arguments

platform Plateforme sociale : twitter, instagram, linkedin, threads, ou tiktok.

timezone Nom de fuseau horaire IANA (p. ex. Europe/Paris, America/New_York). UTC par défaut.

topN Nombre de recommandations de créneaux à renvoyer (1-24, 5 par défaut).

Valeur renvoyée

Un objet avec platform, timezone, sampleWindowDays, sampleSize, metricsAvailable et recommendations: [{dayOfWeek (1-7, Lun=1), dayLabel, hour (0-23), score, basedOn: {posts, avgEngagement}}]. Inclut hint pour les cas cold-start ou métriques indisponibles.

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":19,
 "params":{"name":"get_best_time_to_post",
           "arguments":{"platform":"twitter","timezone":"Europe/Berlin","topN":5}}}

get_channel_analytics

Performance agrégée d'un canal connecté, ou de tous à la fois. Renvoie impressions, portée, likes, commentaires et taux d'engagement sur la période, l'écart avec la période précédente de même durée, et la série des abonnés. Sans platform, le total de toute l'équipe. Pour une publication seule, get_post_metrics ; pour planifier, get_best_time_to_post.

Arguments

platform Plateforme sociale : twitter, instagram, linkedin, threads, ou tiktok.

channelName Quel compte connecté, quand la plateforme en a plusieurs.

providerId Le providerId du compte, issu de list_connected_accounts. Il ne change pas quand l'identifiant change : passez-le avec channelName ou à sa place.

period Période à analyser : 7d, 30d, 90d ou all (30d par défaut).

Valeur renvoyée

Un objet avec scope, period, totals, vsPrevious, coverage, dataThrough et followers, qui porte trackingSince, current, change et la série.

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":34,
 "params":{"name":"get_channel_analytics",
           "arguments":{"platform":"linkedin","period":"30d"}}}

search_tools

Recherche le catalogue d'outils MCP par texte libre, catégorie ou intention. Renvoie catégories, requiresScope, descriptions d'une ligne et les tags de cas d'usage qui correspondent. Disponible dans toutes les offres (surface de découverte).

Arguments

Tous facultatifs. Appelez-le sans argument pour lister tous les outils disponibles.

query Recherche libre dans les noms, descriptions et tags d'usage des outils.

category Filtre sur une catégorie : posts, accounts, analytics, brand, teams, discovery, other.

Valeur renvoyée

Un objet avec totalTools, matchCount, categories: [string[]] et tools: [{name, category, requiresScope, description, useCases, matchedOn: [name|category|description|use_case]}]. Inclut hint quand pas de correspondance ou pas de filtre.

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":20,
 "params":{"name":"search_tools",
           "arguments":{"query":"why did my post fail"}}}

get_plan

Formule et dates de facturation : palier, date de renouvellement, fin de la période d'essai et résiliation prévue en fin de période. Pour les quotas et la consommation, appelez plutôt get_plan_limits.

Arguments

Aucun argument.

Valeur renvoyée

Un objet avec tier, tierDisplayName, isPaid, isTrial, gated, subscriptionStatus, renewsAt, trialEndsAt, cancelAtPeriodEnd et currency.

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":21,
 "params":{"name":"get_plan",
           "arguments":{}}}

upload_asset

Envoi d'une image ou d'une vidéo dans la médiathèque directement en base64. Fiable uniquement pour de très petits fichiers, environ 8 Ko ou moins : au-delà, le contenu est tronqué sans avertissement dans les arguments de l'outil et le fichier enregistré est corrompu. Pour tout le reste, utilisez request_asset_upload.

Arguments

filename Nom du fichier avec son extension, jusqu'à 255 caractères.

contentType Type MIME du fichier, parmi la liste autorisée d'images et de vidéos.

base64 Les octets du fichier, encodés en base64. Gardez-le très petit et lisez d'abord l'avertissement ci-dessus.

Valeur renvoyée

Un objet avec assetId, url, sizeBytes et mimeType. Transmettez url à create_post_draft dans mediaUrls.

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":22,
 "params":{"name":"upload_asset",
           "arguments":{"filename":"logo.png","contentType":"image/png","base64":"iVBORw0KGgo..."}}}

request_asset_upload

La méthode d'envoi recommandée, pour les images et les vidéos de toute taille. Deux étapes : appelez cet outil pour obtenir une URL présignée et une commande curl prête à l'emploi, puis envoyez le fichier en PUT vers cette URL. La réponse au PUT contient l'URL finale du média.

Arguments

filename Nom du fichier avec son extension, jusqu'à 255 caractères.

contentType Type MIME du fichier, parmi la liste autorisée d'images et de vidéos.

sizeBytes Taille exacte du fichier en octets, utilisée pour signer l'envoi.

Valeur renvoyée

Un objet avec uploadId, uploadUrl, uploadToken, expiresInSeconds et instructions contenant la commande PUT exacte.

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":23,
 "params":{"name":"request_asset_upload",
           "arguments":{"filename":"clip.mp4","contentType":"video/mp4","sizeBytes":4194304}}}

import_chat_file

ChatGPT uniquement. Enregistre dans votre médiathèque les images et vidéos jointes à la conversation, prêtes pour create_post_draft. ChatGPT transmet chaque fichier sous forme de lien temporaire ; PostNext le télécharge une fois en HTTPS et vérifie sur le fichier lui-même qu'il s'agit d'une image ou d'une vidéo. Jusqu'à 10 fichiers par appel, 50 Mo chacun, comptés dans le stockage de votre offre (10 Mo au total avec l'offre gratuite).

Arguments

files Rempli par ChatGPT à partir des fichiers joints à la conversation : download_url et file_id, et éventuellement mime_type et file_name. Jusqu'à 10. Les autres clients envoient leurs fichiers avec request_asset_upload.

Valeur renvoyée

Un objet avec files (assetId, url, sizeBytes, mimeType et fileName pour chaque fichier enregistré) et failed (fileName et reason pour chaque fichier qui n'a pas pu être enregistré). Si aucun fichier n'a pu être enregistré, l'appel renvoie à la place l'erreur du premier.

Exemple

{"jsonrpc":"2.0","method":"tools/call","id":35,
 "params":{"name":"import_chat_file",
           "arguments":{"files":[{"download_url":"https://files.oaiusercontent.com/...","file_id":"file_abc123"}]}}}

Ressources MCP

Les ressources sont du contexte en lecture seule que le client peut récupérer via la méthode MCP resources/read. Claude les charge au début de chaque conversation pour avoir le contexte compte/équipe/marque sans qu'il faille le réexpliquer à chaque fois.

postnext://account/summary

E-mail et identifiant du compte (pour que Claude confirme avec quel compte il travaille), offre, crédits IA utilisés / limite, nombre de brouillons, nombre de publications programmées, nombre de canaux connectés. Chaque nombre est plafonné à 100 pour un chargement rapide.

postnext://channels/connected

Même structure que le résultat de list_connected_accounts ; exposé en tant que ressource pour que Claude le charge une fois au début de la conversation (sans aller-retour d'appel d'outil).

postnext://brand-profiles/active

Le profil de marque actif de l'utilisateur (par défaut de l'équipe, avec repli sur le premier profil propre). Renvoie uniquement les champs pertinents pour le LLM : bio, expertiseAreas, personalityTraits, brandVoice, mainThemes, audienceSize, preferredHashtags.

postnext://teams/current

Métadonnées de l'équipe actuelle (teamId, teamName) plus totalTeamsAvailable. À combiner avec list_teams + set_current_team pour changer.

Workflows nommés

Raccourcis slash qui orchestrent plusieurs outils. Choisissez-en un et laissez votre assistant IA dérouler une tâche en plusieurs étapes, avec confirmation avant toute modification.

/weekly-plan

Lit le profil de marque, les canaux connectés et la file, puis propose 5-10 brouillons répartis du lundi au vendredi.

/draft-thread

Rédige un fil de 5-10 publications pour Twitter ou Threads à partir d'un sujet ou d'une URL que vous fournissez, dans le ton de votre marque.

/audit-queue

Parcourt les 7 prochains jours de publications planifiées et signale doublons, surcharge de plateforme et créneaux vides.

/channel-sweep

Compare les canaux connectés à la liste des plateformes prises en charge et suggère lesquels connecter ou rafraîchir.

Endpoints de découverte et OAuth

Métadonnées conformes aux standards pour qu'un client MCP puisse s'auto-configurer.

  • GET /.well-known/oauth-protected-resource/api — RFC 9728
  • GET /.well-known/oauth-authorization-server — RFC 8414
  • GET /oauth/.well-known/openid-configuration — OIDC
  • POST /oauth/reg — Dynamic Client Registration (RFC 7591)
  • GET /oauth/auth — Authorize (PKCE-S256 required)
  • POST /oauth/token — Token exchange

Open source

Des recettes prêtes à copier et une référence pour développeurs se trouvent dans notre dépôt de documentation public. Licence MIT ; les pull requests sont les bienvenues. github.com/postnextio/postnext-mcp

MCP réseaux sociaux pour Claude, ChatGPT et tout agent IA

Le serveur MCP de PostNext pour les réseaux sociaux permet à Claude, ChatGPT et tout agent IA de planifier, rédiger et programmer vos publications. Les brouillons restent dans votre calendrier jusqu'à ce que vous les programmiez.