Early Access

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.

whoami

Affiche 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_projects

Liste les projets Pushrank accessibles à l'utilisateur authentifié.

Paramètres : limit (1–50, défaut 25).

get_project_overview

Aperçu compact d'un projet : trafic, résumé du digest et compteurs de statut.

Paramètres : projectId.

get_seo_forecast

Pré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_opportunities

Ré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:write

Met à 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_digest

Renvoie 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_snapshot

Lit 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_articles

Liste 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_article

Renvoie 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_readiness

Vé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:generate

Lance 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_status

Lit 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_readiness

Vé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:publish

Publie 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_plan

Affiche le plan éditorial courant et l'état de chaque sujet prévu.

Paramètres : projectId.

generate_article_from_plan_itemÉcriture · mcp:articles:generate

Lance 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:write

Pré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_performance

Lit les performances GSC conservées de la page publiée, sans appel Google en direct.

Paramètres : projectId, articleId.

add_keywordsÉcriture · mcp:keywords:write

Pré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:write

Pré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:write

Pré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_readiness

Vé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:run

Relance 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_context

Lit le contexte éditorial structuré sans exposer les documents internes du RAG.

Paramètres : projectId.

edit_editorial_contextÉcriture · mcp:editorial:write

Pré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_profile

Lit 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:write

Pré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:write

Pré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:write

Pré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:write

Pré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:write

Pré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:write

Pré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:write

Pré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:write

En 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:write

Relance 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_config

Lit 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:write

Pré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_schedule

Lit 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:publish

Pré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:write

Ré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:write

Planifie 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:write

Annule 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_keywords

Liste 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_metrics

Renvoie 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_checklist

Affiche 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:write

Pré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_visibility

Lit 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:write

Pré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.

Métadonnées de la ressourcehttps://ai.pushrank.io/.well-known/oauth-protected-resource/mcp
Serveur d'autorisationhttps://app.pushrank.io/.well-known/oauth-authorization-server
  1. 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.
  2. Enregistrement — le client s'enregistre par enregistrement dynamique (registration_endpoint), en client public, sans secret.
  3. 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.
  4. 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 ».

Endpointhttps://ai.pushrank.io/mcp

En-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).

terminal
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.

terminal
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.

terminal
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}}}'
Le serveur est stateful : sans en-tête mcp-session-id valide, tout appel après initialize renvoie « Session not found » (404).

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.