Skip to main content

​
Collegare un assistente

SORANK ospita già il server MCP remoto all’indirizzo https://app.sorank.com/mcp. Non devi creare un endpoint MCP né avviare un server locale.
  1. In un assistente compatibile con MCP remoto su Streamable HTTP e OAuth authorization code con PKCE S256, apri le impostazioni MCP o dei connettori.
  2. Aggiungi un server remoto con URL https://app.sorank.com/mcp. Seleziona OAuth o autenticazione automatica. Il sito web, /api/public/v1 e localhost non sono indirizzi MCP.
  3. Premi Connetti o Autorizza. Il client scopre la configurazione OAuth, si registra se necessario e apre l’accesso SORANK. Controlla scope e siti richiesti prima di approvarli.
  4. Torna all’assistente, aggiorna gli strumenti e chiama list_profiles. Vedrai solo i siti autorizzati. Poi usa get_capabilities e, con quotas:read, get_quotas.
Se il client richiede JSON, inserisci questo indirizzo nel campo URL remota e scegli OAuth. I nomi dei campi dipendono dal client; questo server ospitato non richiede un comando locale npx.

​
Alternativa con chiave personale

Se il client supporta un header Authorization personalizzato per MCP remoto, crea una chiave su https://app.sorank.com/settings/api con siti e scope necessari. Configura Authorization: Bearer <chiave-completa> nell’archivio sicuro del client, mai nel prompt. La chiave completa è mostrata una sola volta. OAuth è preferibile per client interattivi.

​
Configurare OAuth

I metadati della risorsa MCP si trovano su https://app.sorank.com/.well-known/oauth-protected-resource/mcp e quelli del server di autorizzazione su https://app.sorank.com/.well-known/oauth-authorization-server. I client compatibili li scoprono automaticamente. Chi sviluppa client usa gli endpoint OAuth annunciati, PKCE S256 e la risorsa esatta https://app.sorank.com/mcp.

​
Verificare l’idoneità

Puoi collegare un assistente dopo aver completato l’onboarding in Sorank e se almeno un sito ha un abbonamento valido. Altrimenti, la schermata di consenso spiega cosa manca, rimanda all’onboarding o a Impostazioni → Fatturazione, e Consenti accesso resta non disponibile. Completa quel passaggio, poi riavvia la connessione dall’assistente. Si possono selezionare solo siti idonei, e list_profiles restituisce solo siti idonei. Se in seguito un sito perde l’abbonamento, i suoi strumenti restituiscono subscription_required, anche in una sessione già aperta.

​
Scegliere strumenti e permessi

Chiedi al client di elencare gli strumenti dopo la connessione. Il server mostra solo gli strumenti consentiti dalla tua autorizzazione e la verifica di nuovo a ogni chiamata. Uno strumento nascosto non può essere invocato direttamente.
  • Siti e quote: list_profiles, get_capabilities, get_quotas.
  • Visualizzare i prodotti: list_products.
  • Visualizzare le analisi: get_gsc_performance, list_gsc_queries, list_gsc_pages, get_gsc_countries_devices, get_ai_traffic_timeline, list_ai_traffic_pages.
  • Visualizza visibilità IA: get_geo_stats, get_geo_mentions_evolution, get_geo_citations_timeline, list_geo_citing_sources, get_geo_cited_competitors.
  • Visualizzare le impostazioni: get_settings. Modificare le impostazioni: update_site_settings, replace_business_brief, replace_competitors, update_article_settings, update_visual_settings, connect_youtube_channel, set_youtube_channel_enabled, disconnect_youtube_channel.
  • Contenuti: create_calendar, generate_articles, publish_article, get_operation e gli altri strumenti per articoli e calendario.

​
Seguire un flusso sicuro

Inizia con list_profiles, get_capabilities e get_quotas. Crea un calendario o genera articoli dopo aver controllato la quota. Ogni modifica richiede un UUID idempotency_key nell’input. Conserva l’ID dell’operazione e consulta get_operation fino al termine. Un comando accettato può fallire in seguito; verifica risultato o errore. Leggi l’articolo prima di modificarlo o pubblicarlo.

​
Effetti e revoca

La creazione di un calendario può programmare generazioni e pubblicazioni successive. generate_articles usa la quota di articoli dell’account; la sua ricevuta è succeeded appena il lotto viene accettato, e segui ogni articolo accettato con get_article. publish_article può inviare contenuti a un CMS, in base alle sue funzionalità e alla destinazione scelta. Gli strumenti delle impostazioni modificano le stesse impostazioni dell’app e restituiscono un elenco effects con le attività avviate in background, come una rigenerazione delle domande GEO o una sincronizzazione YouTube. L’URL del sito non può essere modificato. Lo stesso piano, gli stessi permessi e la stessa quota valgono nell’app e in REST. Revocare la connessione o perdere l’accesso al sito blocca le chiamate e le letture delle operazioni successive.

​
Gestire gli errori degli strumenti

Una chiamata non riuscita restituisce un errore dello strumento con gli stessi code, message, request_id, retryable e details dell’API REST, ad esempio onboarding_required, subscription_required, missing_scope, not_found, gsc_not_connected o business_brief_revision_conflict. Riprova solo se retryable è true.

​
Verificare la compatibilità

Questa V1 supporta il trasporto Streamable HTTP e il flusso OAuth testati, con registrazione dinamica limitata. Non supporta client che richiedono solo metadati CIMD. Verifica le capacità del client prima di collegarlo. Il testo restituito dagli articoli è contenuto utente, non un’istruzione affidabile.

​
Se la connessione non riesce

  • Aprire /mcp nel browser non testa MCP. Inserisci l’URL in un client MCP e scegli Streamable HTTP.
  • Se non compare l’accesso, verifica OAuth discovery, authorization code con PKCE S256 e registrazione dinamica. Una chiave personale funziona se il client accetta un header Authorization.
  • Se mancano siti o strumenti, controlla siti e scope approvati. list_profiles richiede profiles:read; get_quotas richiede quotas:read.
  • Se una connessione smette di funzionare, verifica revoca e accesso ai siti in Impostazioni → Accesso API, poi collegala di nuovo.
  • Se la schermata di consenso non consente di autorizzare, completa l’onboarding o aggiorna l’abbonamento come indicato, poi ricollegati dall’assistente.