Vai al contenuto principale

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.

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.
Seleziona tutto seleziona con un clic tutti i siti, o tutti i permessi di un gruppo. I permessi di lettura sono preselezionati; modifiche e azioni restano sempre una tua scelta.

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.
  • Ricerca e genera parole chiave: research_keywords, get_keyword_metrics, generate_keywords. Segui una ricerca completa di parole chiave con get_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_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. 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 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.