> ## Documentation Index > Fetch the complete documentation index at: https://sorank.com/llms.txt > Use this file to discover all available pages before exploring further. # Collegare un assistente con MCP > Configurare OAuth per il server MCP SORANK e usare gli strumenti pubblici. ## 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 ` 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.