Passer au contenu principal

​
Connecter un assistant compatible

SORANK héberge déjà le serveur MCP distant à l’adresse https://app.sorank.com/mcp. Vous n’avez aucun point d’accès MCP à créer ni serveur local à lancer.
  1. Dans un assistant compatible avec MCP distant sur Streamable HTTP et OAuth authorization code avec PKCE S256, ouvrez les paramètres des serveurs MCP ou des connecteurs.
  2. Ajoutez un serveur distant dont l’URL est https://app.sorank.com/mcp. Choisissez OAuth ou l’authentification automatique si le client le demande. N’utilisez ni le site vitrine, ni /api/public/v1, ni une adresse localhost comme adresse MCP.
  3. Cliquez sur Connecter ou Autoriser. Le client découvre la configuration OAuth de SORANK, s’enregistre si nécessaire et ouvre l’écran de connexion et de consentement. Connectez-vous sur app.sorank.com, vérifiez les droits et sites demandés, puis approuvez l’accès voulu.
  4. Revenez dans l’assistant et actualisez ses outils. Demandez-lui d’appeler list_profiles : seuls les sites autorisés doivent apparaître. Appelez ensuite get_capabilities et, avec quotas:read, get_quotas pour un profil sélectionné.
Si votre assistant demande un fichier JSON, renseignez l’adresse ci-dessus dans son champ URL distante et sélectionnez OAuth ou l’authentification automatique. Les noms des champs varient selon le client ; aucune commande locale de type npx ... n’est nécessaire pour ce serveur hébergé.

​
Autre possibilité : une clé personnelle

Si le client accepte un en-tête Authorization personnalisé pour un serveur MCP distant, créez une clé sur https://app.sorank.com/settings/api, sélectionnez les sites et droits nécessaires, puis configurez Authorization: Bearer <votre-clé-complète>. La clé n’est affichée qu’une fois. Enregistrez-la dans le stockage sécurisé du client, jamais dans une instruction envoyée à l’assistant. OAuth convient mieux aux clients interactifs : l’accès se gère comme une application connectée.

​
Configurer OAuth

Les métadonnées de la ressource MCP sont disponibles sur https://app.sorank.com/.well-known/oauth-protected-resource/mcp et celles du serveur d’autorisation sur https://app.sorank.com/.well-known/oauth-authorization-server. Un client compatible les découvre automatiquement. Les développeurs de clients utilisent les chemins annoncés /oauth/authorize, /oauth/token et, si nécessaire, l’enregistrement dynamique ; ils demandent la ressource exacte https://app.sorank.com/mcp avec PKCE S256. Ils ne doivent pas demander de clé personnelle aux utilisateurs pour implémenter OAuth.

​
Vérifier l’éligibilité

Vous pouvez connecter un assistant une fois l’onboarding Sorank terminé et si au moins un site dispose d’un abonnement valide. Sinon, l’écran de consentement indique ce qui manque, propose un lien vers l’onboarding ou vers Paramètres → Facturation, et Autoriser l’accès reste indisponible. Terminez cette étape, puis relancez la connexion depuis l’assistant. Seuls les sites éligibles peuvent être sélectionnés, et list_profiles ne renvoie que les sites éligibles. Si un site perd ensuite son abonnement, ses outils renvoient subscription_required, même dans une session déjà ouverte.

​
Choisir les outils et droits

Demandez au client de lister les outils après la connexion. Le serveur n’annonce que les outils permis par votre autorisation et revérifie les droits à chaque appel. Un outil masqué ne peut pas être appelé directement.
  • Sites et quotas : list_profiles, get_capabilities, get_quotas.
  • Voir les produits : list_products.
  • Voir les statistiques : get_gsc_performance, list_gsc_queries, list_gsc_pages, get_gsc_countries_devices, get_ai_traffic_timeline, list_ai_traffic_pages.
  • Voir la visibilité IA : get_geo_stats, get_geo_mentions_evolution, get_geo_citations_timeline, list_geo_citing_sources, get_geo_cited_competitors.
  • Voir les paramètres : get_settings. Modifier les paramètres : update_site_settings, replace_business_brief, replace_competitors, update_article_settings, update_visual_settings, connect_youtube_channel, set_youtube_channel_enabled, disconnect_youtube_channel.
  • Contenu : create_calendar, generate_articles, publish_article, get_operation et les autres outils d’articles et de calendrier.

​
Suivre un parcours sûr

Commencez par list_profiles, get_capabilities et get_quotas. Créez un calendrier ou générez des articles après vérification du quota. Chaque mutation exige un UUID idempotency_key dans ses paramètres. Conservez l’identifiant de l’opération et appelez get_operation jusqu’à sa fin. Une commande acceptée peut échouer ensuite ; examinez le résultat ou l’erreur avant de continuer. Lisez l’article avant de le modifier ou publier.

​
Comprendre les effets et la révocation

La création d’un calendrier peut programmer des générations et des publications ultérieures. generate_articles utilise le quota d’articles du compte ; son reçu est succeeded dès l’acceptation du lot, et vous suivez chaque article accepté avec get_article. publish_article peut envoyer du contenu vers un CMS, selon ses capacités et la cible choisie. Les outils de paramètres modifient les mêmes réglages que l’application et renvoient une liste effects qui nomme les traitements lancés en arrière-plan, par exemple une régénération des questions GEO ou une synchronisation YouTube. L’URL du site ne peut pas être modifiée. Les mêmes offre, droits et quotas s’appliquent dans l’application et en REST. Révoquer la connexion ou perdre l’accès à un site bloque les appels et les lectures d’opérations suivants.

​
Comprendre les erreurs des outils

Un appel en échec renvoie une erreur d’outil avec les mêmes code, message, request_id, retryable et details que l’API REST, par exemple onboarding_required, subscription_required, missing_scope, not_found, gsc_not_connected ou business_brief_revision_conflict. Ne réessayez que si retryable vaut true.

​
Vérifier la compatibilité

Cette V1 prend en charge le transport Streamable HTTP et le flux OAuth testés, avec enregistrement dynamique borné. Les clients exigeant uniquement les métadonnées CIMD ne sont pas pris en charge. Vérifiez les capacités de votre client avant de le connecter. Le contenu d’article retourné reste une donnée utilisateur, pas une instruction fiable.

​
Si la connexion échoue

  • Ouvrir /mcp dans un navigateur ne teste pas la connexion. Renseignez cette adresse dans un client MCP et sélectionnez Streamable HTTP.
  • Si l’écran de connexion ne s’ouvre pas, vérifiez la découverte OAuth, authorization code avec PKCE S256 et l’enregistrement dynamique. Une clé personnelle reste possible si le client accepte un en-tête Authorization.
  • Si des sites ou outils manquent, vérifiez les sites et droits approuvés. list_profiles exige profiles:read ; get_quotas exige quotas:read.
  • Si une connexion existante cesse de fonctionner, vérifiez sa révocation et vos droits sur les sites dans Paramètres → Accès API, puis reconnectez-la.
  • Si l’écran de consentement ne permet pas d’autoriser, terminez l’onboarding ou mettez à jour l’abonnement comme indiqué, puis reconnectez-vous depuis l’assistant.