Collegare un assistente
SORANK ospita già il server MCP remoto all’indirizzohttps://app.sorank.com/mcp. Non devi creare un endpoint MCP né avviare un server locale.
- In un assistente compatibile con MCP remoto su Streamable HTTP e OAuth authorization code con PKCE S256, apri le impostazioni MCP o dei connettori.
- Aggiungi un server remoto con URL
https://app.sorank.com/mcp. Seleziona OAuth o autenticazione automatica. Il sito web,/api/public/v1elocalhostnon sono indirizzi MCP. - 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.
- Torna all’assistente, aggiorna gli strumenti e chiama
list_profiles. Vedrai solo i siti autorizzati. Poi usaget_capabilitiese, conquotas:read,get_quotas.
npx.
Leggere la schermata di consenso
La schermata di consenso indica quale applicazione richiede l’accesso e dove viene inviata l’autorizzazione.- Verificata: l’autorizzazione viene inviata all’indirizzo ufficiale di un assistente noto, come Claude o ChatGPT. SORANK mostra allora il nome di quell’assistente.
- Su questo computer: l’applicazione è in esecuzione sul tuo computer, come un assistente desktop o uno strumento di sviluppo. Consenti l’accesso solo se hai avviato tu la connessione.
- Non verificata: qualsiasi altro indirizzo. Il nome dell’applicazione è scelto da chi l’ha registrata: controlla l’indirizzo prima di consentire l’accesso.
Alternativa con chiave personale
Se il client supporta un headerAuthorization 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 suhttps://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, elist_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. - Ricerca e genera parole chiave:
research_keywords,get_keyword_metrics,generate_keywords. Segui una ricerca completa di parole chiave conget_keyword_run. - Visualizza miglioramenti:
get_audit,list_audit_pages,estimate_audit_fixes,list_audit_fixes. Avvia analisi e correggi articoli:start_audit,recheck_audit_page,fix_audit_page,apply_audit_fix,restore_audit_fix,fix_audit_bulk. - Aggiorna prodotti:
refresh_product_catalog. Visualizza articoli:get_article_index_status. - Visualizza visibilità IA:
list_geo_prompts. Modifica prompt di visibilità IA:create_geo_prompts,update_geo_prompt,delete_geo_prompts. - Visualizza backlink:
get_backlinks,list_backlink_quests. Gestisci backlink e missioni:update_backlink_settings,claim_backlink_quest. - Visualizza fatture:
list_invoices. - Contenuti:
create_calendar,generate_articles,publish_article,get_operatione gli altri strumenti per articoli e calendario.
Seguire un flusso sicuro
Inizia conlist_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.
Su un sito Framer, get_publication restituisce anche site_deploy. Framer mostra una modifica solo dopo una pubblicazione del sito, che Sorank avvia circa un minuto dopo ogni modifica: pending indica che public_url non mostra ancora l’ultima modifica, e live che è online. Finché lo stato è pending, last_error_code indica l’errore dell’ultimo deploy non riuscito, ad esempio cms_token_expired quando la chiave API di Framer va sostituita.
Quando una pubblicazione non riesce, get_publication restituisce status failed con last_error.code publication_failed. Se Sorank ha registrato la causa, last_error.reason la indica, ad esempio site_unreachable: Sorank non è riuscito a connettersi al sito, quindi verifica che sia online e che il suo hosting o il suo firewall non blocchino Sorank. Possono aggiungersi nuove cause: gestisci una causa sconosciuta come un errore generico.
Su un negozio PrestaShop collegato con una chiave Webservice, senza il modulo Sorank, update_published_article non può cambiare l’indirizzo di una pagina pubblicata. Se hai modificato lo slug dell’articolo, l’operazione termina in failed con publication_change_failed. Ripristina lo slug pubblicato oppure installa il modulo Sorank sul negozio.
Spendere crediti IA e correggere articoli
La ricerca di parole chiave, le ricerche complete di parole chiave e le correzioni degli articoli usano i crediti IA del sito, allo stesso prezzo dell’app.get_quotas restituisce il saldo e il prezzo attuale di ogni azione. Chiama estimate_audit_fixes prima di correggere una pagina o tutto il sito: restituisce il costo e non addebita nulla. Se il saldo non basta, lo strumento restituisce insufficient_credits con details.required e details.balance. Una ricerca di parole chiave non riuscita viene rimborsata.
fix_audit_page prepara le correzioni scelte, o una riscrittura completa. apply_audit_fix scrive poi una correzione nell’articolo sul tuo CMS, e restore_audit_fix ripristina la versione precedente; entrambi richiedono anche Pubblica articoli. fix_audit_bulk corregge tutto il sito e applica da solo ogni correzione; richiede anche Genera articoli e Pubblica articoli. start_audit usa la quota di analisi del sito, e viene eseguita una sola analisi alla volta.
Gestire gli errori degli strumenti
Una chiamata non riuscita restituisce un errore dello strumento con gli stessicode, 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
/mcpnel 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_profilesrichiedeprofiles:read;get_quotasrichiedequotas: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.

