Documentation API & MCP
Ce que le serveur MCP de Pushrank expose et comment l'appeler manuellement via l'API.
Outils exposés
Le serveur MCP de Pushrank expose 49 outils. Toutes les réponses sont limitées aux projets de votre organisation ; les 26 actions d'écriture sont signalées ci-dessous. Seuls les paramètres listés sont acceptés : un paramètre non déclaré est refusé avec une erreur nommant la clé, jamais ignoré silencieusement.
whoamiAffiche l'utilisateur authentifié, ses organisations accessibles, les scopes accordés, les soldes de crédits et les liens Pushrank utiles.
Paramètres : Aucun. Lecture seule, sans scope supplémentaire.
list_projectsListe les projets Pushrank accessibles à l'utilisateur authentifié.
Paramètres : limit (1–50, défaut 25).
get_project_overviewAperçu compact d'un projet : trafic, résumé du digest et compteurs de statut.
Paramètres : projectId.
get_seo_forecastPrévisionnel SEO d'un projet, en lecture seule : l'estimation Pushrank (curseur à sa position par défaut) avec sa courbe, M6, M12, cumul, coût, seuil, couverture, repère consultant, hypothèses et provenance, ou la raison de son indisponibilité. Même niveau de détail que l'écran selon le compte. Hypothèse, pas une garantie.
Paramètres : projectId.
list_seo_opportunitiesRécupère automatiquement la liste complète des actions SEO correspondant à votre demande, actives par défaut, et guide l'assistant pour les présenter en tableau. Le périmètre et les états sont ceux de l'écran Actions ; la réponse explique aussi les actions masquées par cet écran.
Paramètres : projectId ; optionnels : status (active par défaut | todo | in_progress | done | verified | still_present | ignored | all), type, severity, priority, source, query, pageUrl, priorityMin. pagination=all par défaut ; pagination=page permet une lecture technique par page avec page (défaut 1) et pageSize (défaut 10, maximum 25).
update_seo_opportunity_statusÉcriture · mcp:actions:writeMet à jour le statut d'une ou de plusieurs opportunités SEO (jusqu'à 50 par appel) et rend un résultat par opportunité : appliqué, déjà dans ce statut ou refusé avec sa raison. Nécessite le scope mcp:actions:write.
Paramètres : projectId, status ; opportunityId pour une opportunité, ou opportunityIds (1 à 50) pour un lot.
get_gsc_digestRenvoie le dernier digest GSC complété et le statut de la dernière tentative ; ne génère pas de nouveau digest.
Paramètres : projectId ; kind (dashboard_digest | weekly_gsc | monthly_gsc, défaut dashboard_digest).
get_gsc_snapshotLit uniquement les snapshots Google Search Console conservés ; n'appelle jamais GSC en direct.
Paramètres : projectId, dimension (date | page | query | query_page | page_date) ; optionnels : period, compareTo (même durée), pageUrl, offset, limit (max 50).
list_articlesListe les articles avec scores, état qualité et métadonnées de publication, sans le contenu complet.
Paramètres : projectId ; optionnels : status, search, limit (max 25).
get_articleRenvoie un article complet : contenu, méta, rapports qualité, logs de publication, mots-clés liés, opportunités et runs d'agent.
Paramètres : projectId, articleId.
get_article_generation_readinessVérifie quota, complétude du brief, cannibalisation et avertissements SERP avant génération, sans rien créer.
Paramètres : projectId, keyword, intent, articleType ; optionnels : niche, languageCode.
generate_articleÉcriture · mcp:articles:generateLance le workflow normal de génération d'article avec quotas et protections. Nécessite le scope mcp:articles:generate.
Paramètres : projectId, keyword, intent, idempotencyKey (UUID) ; optionnels : articleType, niche, languageCode, brief, opportunityId, acknowledgeWarnings.
get_workflow_statusLit l'avancement d'une génération ou d'une publication CMS.
Paramètres : projectId et exactement un de requestId ou articleId ; optionnel : publicationJobId.
get_article_publication_readinessVérifie l'article, le verdict qualité, la connexion CMS, les capacités et la provenance avant publication.
Paramètres : projectId, articleId.
publish_article_to_cmsÉcriture · mcp:articles:publishPublie ou met à jour réellement l'article dans le CMS connecté. Nécessite le scope mcp:articles:publish.
Paramètres : projectId, articleId, idempotencyKey (UUID), confirmed=true ; optionnel : acknowledgeQualityOverride.
list_content_planAffiche le plan éditorial courant et l'état de chaque sujet prévu.
Paramètres : projectId.
generate_article_from_plan_itemÉcriture · mcp:articles:generateLance la génération normale depuis un sujet du plan après confirmation. Nécessite mcp:articles:generate.
Paramètres : projectId, itemId, confirmed=true ; optionnel : acknowledgeWarnings.
edit_articleÉcriture · mcp:articles:writePrévisualise puis applique une modification d'article avec contrôle de version. L'application nécessite mcp:articles:write.
Paramètres : projectId, articleId, mode, expectedUpdatedAt, changes (title, slug, content, metaDescription, faqData, ctaData, robotsConfig{index, follow, noSnippet, noArchive}, featuredImageAlt) ; confirmed=true pour appliquer. Un ctaData avec html "" ou blocks [] reste sans CTA, même avec une URL ; un CTA sans URL valide n'est pas affiché.
get_article_performanceLit les performances GSC conservées de la page publiée, sans appel Google en direct.
Paramètres : projectId, articleId.
add_keywordsÉcriture · mcp:keywords:writePrévisualise puis ajoute jusqu'à 100 mots-clés à la stratégie. Les nouveaux mots-clés sont enrichis (volume, difficulté, SERP, intention) comme un ajout depuis le tableau de bord, sans coût en crédits, avec un abonnement actif. Un mot-clé retiré auparavant est remis. L'application nécessite mcp:keywords:write.
Paramètres : projectId, mode, terms[], locale, intent ; confirmed=true et idempotencyKey pour appliquer.
update_keywordÉcriture · mcp:keywords:writePrévisualise puis remplace l'intention, le statut ou le score de priorité d'un mot-clé. L'application nécessite mcp:keywords:write.
Paramètres : projectId, mode, keywordId, changes (intent, status, priorityScore) ; confirmed=true et idempotencyKey pour appliquer.
set_keyword_statusesÉcriture · mcp:keywords:writePrévisualise puis applique un même statut à 100 mots-clés au plus. L'application nécessite mcp:keywords:write.
Paramètres : projectId, mode, keywordIds[], status ; confirmed=true et idempotencyKey pour appliquer.
get_page_reanalysis_readinessVérifie l'URL, la page, les doublons et les crédits avant une relance d'analyse.
Paramètres : projectId, pageUrl.
reanalyze_pageÉcriture · mcp:analysis:runRelance l'analyse SEO normale d'une page avec débit de crédits et idempotence. Nécessite mcp:analysis:run.
Paramètres : projectId, pageUrl, idempotencyKey, confirmed=true.
get_editorial_contextLit le contexte éditorial structuré sans exposer les documents internes du RAG.
Paramètres : projectId.
edit_editorial_contextÉcriture · mcp:editorial:writePrévisualise puis applique un contexte éditorial structuré avec contrôle de version. L'application nécessite mcp:editorial:write.
Paramètres : projectId, mode, expectedUpdatedAt, changes (brandName, primaryOffer, audience, benefits, positioning, tone, proofs[]{claim, sourceUrl, excerpt}) ; confirmed=true pour appliquer.
get_business_profileLit le profil d'activité complet : chaque fait avec son statut, sa provenance et sa décision, l'état de complétude, les champs du socle manquants et le mode historique.
Paramètres : projectId.
declare_business_factÉcriture · mcp:editorial:writePrévisualise puis déclare un fait du profil d'activité (offre, audience, marché, objectif, règle, contrainte, saisonnalité ou terme). Une adresse déjà remplie voit sa valeur remplacée. L'application nécessite mcp:editorial:write.
Paramètres : projectId, mode, expectedRevision, idempotencyKey, address, value ; confirmed=true pour appliquer.
replace_business_factÉcriture · mcp:editorial:writePrévisualise puis remplace la valeur d'un fait du profil d'activité. L'application nécessite mcp:editorial:write.
Paramètres : projectId, mode, expectedRevision, idempotencyKey, factId, value ; confirmed=true pour appliquer.
confirm_business_factÉcriture · mcp:editorial:writePrévisualise puis confirme un fait proposé du profil d'activité. L'application nécessite mcp:editorial:write.
Paramètres : projectId, mode, expectedRevision, idempotencyKey, factId ; confirmed=true pour appliquer.
reject_business_factÉcriture · mcp:editorial:writePrévisualise puis rejette un fait proposé ou confirmé ; il reste rétablissable. L'application nécessite mcp:editorial:write.
Paramètres : projectId, mode, expectedRevision, idempotencyKey, factId, reason ; confirmed=true pour appliquer.
withdraw_business_factÉcriture · mcp:editorial:writePrévisualise puis supprime définitivement un fait du profil ; il ne peut pas être rétabli. L'application nécessite mcp:editorial:write.
Paramètres : projectId, mode, expectedRevision, idempotencyKey, factId, reason ; confirmed=true pour appliquer.
restore_business_factÉcriture · mcp:editorial:writePrévisualise puis remet un fait rejeté à l'état proposé. L'application nécessite mcp:editorial:write.
Paramètres : projectId, mode, expectedRevision, idempotencyKey, factId ; confirmed=true pour appliquer.
reorder_business_offersÉcriture · mcp:editorial:writePrévisualise puis remplace l'ordre des offres. L'application nécessite mcp:editorial:write.
Paramètres : projectId, mode, expectedRevision, idempotencyKey, offerIds[] ; confirmed=true pour appliquer.
adopt_business_profileÉcriture · mcp:editorial:writeEn mode historique seulement : prévisualise puis confirme le profil repris de l'existant, en rejetant les faits erronés et en déclarant les champs du socle manquants dans le même changement. Irréversible. L'application nécessite mcp:editorial:write.
Paramètres : projectId, mode, expectedRevision, idempotencyKey, rejectFactIds[], missingFacts[]{address, value} ; confirmed=true pour appliquer.
retry_project_contextÉcriture · mcp:editorial:writeRelance la reconstruction du contexte projet quand elle a échoué (projectContext.retry = available dans get_article_generation_readiness), comme le bouton des réglages. Prévisualise l'état puis relance ; un appel rejoué rend la relance déjà en file ; après un nouvel échec, chaque application est une nouvelle relance. L'application nécessite mcp:editorial:write.
Paramètres : projectId, mode ; confirmed=true pour appliquer.
get_cms_configLit le type de CMS, l'état de connexion, la date du dernier test et les réglages non secrets. Les secrets ne sont jamais renvoyés, seulement leur présence.
Paramètres : projectId.
configure_cmsÉcriture · mcp:integrations:writePrévisualise puis enregistre et teste les réglages non secrets d'une connexion WordPress, Webflow, Wix, Framer (si activé) ou webhook personnalisé existante. Les identifiants se saisissent uniquement dans le tableau de bord PushRank et restent inchangés. Shopify reste dans le tableau de bord. L'application nécessite mcp:integrations:write et le rôle propriétaire.
Paramètres : projectId, mode, cmsType ; selon le type : wpUrl, wpUsername | webflowCollectionId | wixSiteId, wixMemberId | framerProjectId, framerCollectionId, framerFieldMapping (Framer, si activé) | webhookUrl ; confirmed=true et idempotencyKey pour appliquer.
get_publishing_scheduleLit la planification des articles réglée dans la carte des Sujets : interrupteur, jours, heure, fuseau et « Publier sans relecture », le prochain article prévu et ce que le quota d'articles permet d'ici son renouvellement.
Paramètres : projectId.
update_publishing_scheduleÉcriture · mcp:articles:generate, mcp:articles:publishPrévisualise puis applique un changement de la planification des articles, avec les mêmes règles que la carte des Sujets. L'application nécessite mcp:articles:generate pour l'interrupteur, les jours, l'heure ou le fuseau, et mcp:articles:publish pour « Publier sans relecture ».
Paramètres : projectId, mode ; optionnels : enabled, publishDays (0 à 7 jours parmi mon…sun), publishHour (0–23), timezone (Europe/Paris, Europe/London, America/New_York, America/Los_Angeles, Asia/Tokyo), autoPublish ; confirmed=true et idempotencyKey pour appliquer.
update_article_statusÉcriture · mcp:actions:writeRépercute le statut de publication persistant d'un article et journalise la provenance MCP. Nécessite le scope mcp:actions:write.
Paramètres : projectId, articleId, status (draft | published) ; optionnels : cmsUrl (HTTPS uniquement), publishedAt (ISO 8601, uniquement avec published ; défaut maintenant). La programmation n'est pas prise en charge car cet outil ne reçoit pas de date de programmation.
schedule_article_publicationÉcriture · mcp:actions:writePlanifie la publication future d'un article avec le contrôle qualité et la protection de concurrence existants. Nécessite le scope mcp:actions:write.
Paramètres : projectId, articleId, scheduledAt (date ISO 8601 future avec offset explicite).
cancel_article_publication_scheduleÉcriture · mcp:actions:writeAnnule une planification de publication encore en attente. Refuse si le worker de publication l'a déjà prise en charge. Nécessite le scope mcp:actions:write.
Paramètres : projectId, articleId.
list_keywordsListe les mots-clés enrichis avec métriques, statut, priorité, couverture article et intention canonique.
Paramètres : projectId ; optionnels : intent, source, status, search, limit (max 25), offset (pagination via pagination.nextOffset).
get_keyword_metricsRenvoie les métriques déjà stockées pour jusqu'à 20 termes ; n'appelle jamais de fournisseur et ne déclenche aucun rafraîchissement.
Paramètres : projectId, terms (1–20) ; optionnels : locale (défaut fr), locationCode (défaut 2250).
get_onboarding_checklistAffiche les cinq étapes de prise en main d'un projet, ce qui reste à faire, le lien du tableau de bord de chaque étape et l'état du backlink offert. Les clients compatibles MCP Apps l'affichent en checklist interactive.
Paramètres : projectId.
claim_welcome_giftÉcriture · mcp:backlinks:writePrévisualise puis réclame le backlink offert une fois les cinq étapes faites : une page du site du projet et son ancre. Propriétaire uniquement, avec un essai ou une offre active ; un par organisation. Pendant l'essai, le backlink est seulement réservé : il est commandé à la fin de l'essai, avec le premier mois payé. L'application nécessite mcp:backlinks:write.
Paramètres : projectId, mode, targetUrl, anchorText ; confirmed=true pour appliquer.
get_ai_visibilityLit la Visibilité IA d'un projet : prompts suivis, score, résultats par prompt et par moteur IA (cité, mentionné, rang, extrait), périodes de relevé et, en option, la comparaison avec les concurrents. Ne renvoie jamais le texte intégral des réponses et ne déclenche aucune mesure.
Paramètres : projectId ; optionnels : collectionId, prompt, provider, offset, limit (1–25, défaut 15), includeCompetitors.
manage_ai_visibility_promptsÉcriture · mcp:ai-visibility:writePrévisualise puis applique l'ajout, le retrait ou la reformulation de prompts suivis. Un prompt reformulé repart sans historique. Ne déclenche aucune mesure : les nouveaux prompts sont mesurés au prochain relevé. L'application nécessite mcp:ai-visibility:write.
Paramètres : projectId, mode, operation (add avec prompts, remove avec prompts, ou rename avec from et to) ; confirmed=true pour appliquer.
Connexion OAuth
Les clients MCP comme Claude ou ChatGPT se connectent par OAuth : donnez-leur le point d'accès, ils découvrent le reste dans les métadonnées ci-dessous.
https://ai.pushrank.io/.well-known/oauth-protected-resource/mcphttps://app.pushrank.io/.well-known/oauth-authorization-server- Découverte — un appel non authentifié au point d'accès renvoie 401 avec un en-tête WWW-Authenticate qui pointe vers les métadonnées de la ressource, lesquelles nomment le serveur d'autorisation et les scopes pris en charge.
- Enregistrement — le client s'enregistre par enregistrement dynamique (registration_endpoint), en client public, sans secret.
- Autorisation — flux authorization code avec PKCE (S256) et le paramètre resource égal au point d'accès MCP ; l'utilisateur se connecte à Pushrank et accepte les scopes demandés.
- Jetons — le token_endpoint renvoie un jeton d'accès valable 1 h, et un jeton de rafraîchissement de 30 jours quand offline_access est demandé. Envoyez le jeton d'accès en Authorization: Bearer.
Usage API manuel
Pour un script ou un client sans OAuth, appelez le endpoint JSON-RPC 2.0 avec un token bearer créé depuis l'onglet « API / manuel ».
https://ai.pushrank.io/mcpEn-têtes requis
- Authorization: Bearer <token> — obligatoire sur chaque requête.
- Content-Type: application/json.
- Accept: application/json, text/event-stream.
- mcp-session-id — renvoyé dans les en-têtes de la réponse à initialize, à répéter sur tous les appels suivants.
- mcp-protocol-version: 2025-06-18 sur les appels qui suivent initialize.
Séquence d'appel
1. initialize — ouvre une session. Lisez l'en-tête mcp-session-id de la réponse (option -i de curl).
curl -i -X POST "https://ai.pushrank.io/mcp" \
-H "Authorization: Bearer pushrank_mcp_xxxxxxxx" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"pushrank-manual-client","version":"1.0"}}}'2. tools/list — liste les outils disponibles et leurs schémas d'entrée.
curl -X POST "https://ai.pushrank.io/mcp" \
-H "Authorization: Bearer pushrank_mcp_xxxxxxxx" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "mcp-session-id: <session-id>" \
-H "mcp-protocol-version: 2025-06-18" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'3. tools/call — exécute un outil avec ses arguments.
curl -X POST "https://ai.pushrank.io/mcp" \
-H "Authorization: Bearer pushrank_mcp_xxxxxxxx" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "mcp-session-id: <session-id>" \
-H "mcp-protocol-version: 2025-06-18" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_projects","arguments":{"limit":10}}}'Scopes, limitations et révocation
Les tokens MCP sont dédiés et indépendants de votre session.
Token manuel
Un token manuel porte par défaut les scopes mcp:projects:read et mcp:actions:read. Il n'expire pas et reste révocable à tout moment.
Actions d'écriture
Les mises à jour d'état et de planification exigent mcp:actions:write. Les générations utilisent mcp:articles:generate, la publication mcp:articles:publish, l'édition d'article mcp:articles:write, les mots-clés mcp:keywords:write, la relance d'analyse mcp:analysis:run le contexte éditorial mcp:editorial:write, la connexion CMS mcp:integrations:write, la réclamation du backlink offert mcp:backlinks:write et les prompts suivis de la Visibilité IA mcp:ai-visibility:write. La planification des articles utilise mcp:articles:generate, et « Publier sans relecture » mcp:articles:publish. Ces scopes dédiés sont accordés via OAuth, ou cochés sur une clé manuelle, à sa création comme après. Un token sans le scope requis reçoit insufficientScope.
Durées OAuth
Pour les clients OAuth (Claude, ChatGPT…), l'access token dure 1 h et le refresh token 30 jours.
Révocation
Révoquez un token manuel depuis l'onglet « API / manuel ». La révocation est immédiate et n'affecte pas votre session ; les accès OAuth se révoquent depuis le client connecté.
Périmètre organisation
Le serveur limite toutes les réponses aux projets des organisations dont vous êtes membre.