Il server MCP di GSC Wizard è una risorsa Model Context Protocol remota, protetta da OAuth, che espone a Claude i dati di Google Search Console, Bing Webmaster, GA4 e Merchant Center. Questa pagina è il riferimento tecnico: trasporto, catena di autenticazione, elenco dei tool, contratto di risposta, instradamento delle letture e limiti.
Se preferisci la configurazione passo passo, usa la guida alla connessione di Claude. Per la panoramica del prodotto su tutti i client, vedi il Google Search Console MCP.
https://mcp.gscwizard.com/mcp
Streamable HTTP
OAuth 2.1 (DCR + PKCE) or Bearer key
128 · 96 read / 32 write
Il server parla MCP su Streamable HTTP. Non esiste un endpoint di fallback solo SSE: i client che presuppongono ancora la coppia HTTP+SSE ormai deprecata vanno indirizzati all'unico percorso /mcp, che negozia lo streaming a ogni richiesta.
| Percorso | Autenticazione | Scopo |
|---|---|---|
POST /mcp | Obbligatorio | JSON-RPC su Streamable HTTP |
/v1/* | Obbligatorio | Interfaccia REST per chi non usa MCP |
GET /health | Pubblico | Restituisce { ok, sessions } |
GET /, /docs | Pubblico | Catalogo dei tool in formato leggibile |
/.well-known/oauth-protected-resource | Pubblico | Metadati della risorsa RFC 9728 |
La continuità della sessione passa dall'header di risposta Mcp-Session-Id, che il client rimanda nelle richieste successive. Ogni sessione è vincolata lato server allo user_id che l'ha aperta. Ripresentare un ID di sessione con una credenziale diversa viene rifiutato invece di essere riassegnato in silenzio, quindi un ID di sessione trapelato non basta da solo per leggere un account.
MCP stdio, MCP Streamable HTTP e l'API REST su /v1 passano tutti dalla stessa pipeline runTool(). Autorizzazione, validazione degli argomenti, verifica dei permessi per proprietà, controllo dell'abbonamento, rate limiter e audit trail sono applicati in un unico punto, quindi non possono divergere da un trasporto all'altro. Un tool aggiunto al registro è raggiungibile, e governato allo stesso modo, su tutte e tre.
Due meccanismi, scelti in base alle capacità del client. L'interfaccia Connettori di Claude usa OAuth 2.1; i client basati su file di configurazione e quelli headless presentano una chiave API statica.
Il server MCP è il resource server; l'app su tool.gscwizard.com è l'authorization server. Claude percorre la catena in autonomia:
Un GET non autenticato sulla risorsa indica l'authorization server e gli scope.
Claude recupera /.well-known/oauth-authorization-server dall'emittente per individuare gli endpoint.
Claude si registra da solo e riceve il proprio client ID. Per questo i campi client ID e secret vanno lasciati vuoti quando aggiungi il connettore: compilarli anticipa la registrazione e rompe il flusso.
Un grant authorization_code con challenge S256, rinnovabile. L'accesso con Google e il consenso avvengono sull'authorization server, mai dentro Claude.
Metadati della risorsa
GET https://mcp.gscwizard.com/.well-known/oauth-protected-resource
{
"resource": "https://mcp.gscwizard.com/mcp",
"authorization_servers": ["https://tool.gscwizard.com"],
"scopes_supported": ["mcp:read", "mcp:write"],
"bearer_methods_supported": ["header"]
}Metadati dell'authorization server
GET https://tool.gscwizard.com/.well-known/oauth-authorization-server
{
"issuer": "https://tool.gscwizard.com",
"authorization_endpoint": "https://tool.gscwizard.com/oauth/authorize",
"token_endpoint": "https://tool.gscwizard.com/api/oauth/token",
"registration_endpoint": "https://tool.gscwizard.com/api/oauth/register",
"revocation_endpoint": "https://tool.gscwizard.com/api/oauth/revoke",
"scopes_supported": ["mcp:read", "mcp:write"],
"response_types_supported": ["code"],
"grant_types_supported": ["authorization_code", "refresh_token"],
"code_challenge_methods_supported": ["S256"],
"token_endpoint_auth_methods_supported": [
"none", "client_secret_post", "client_secret_basic"
]
}Due controlli prima dell'emissione di un token. L'endpoint di autorizzazione richiede un abbonamento attivo e almeno una proprietà di Search Console collegata. Un account che non ha né l'uno né l'altra viene mandato a completarli prima, invece di ricevere un token che ogni chiamata successiva a un tool rifiuterebbe.
Le chiavi hanno il prefisso gscw_live_, si creano in Account → Chiavi API e si presentano come Authorization: Bearer. Viene archiviato solo un hash SHA-256, quindi il testo in chiaro compare una sola volta alla creazione e non è più recuperabile; la rotazione significa emettere una nuova chiave e revocare la vecchia.
Ogni chiave ha uno scope fissato alla creazione. Una chiave con scope di sola lettura non può invocare un tool di modifica: il controllo gira nella pipeline prima dell'handler, quindi la sola lettura è una proprietà strutturale della credenziale e non un'istruzione da cui il modello potrebbe essere dissuaso.
Quattro interfacce di Claude, tre meccanismi di collegamento diversi.
Impostazioni → Connettori → Aggiungi connettore personalizzato. Inserisci l'URL e lascia vuoti entrambi i campi OAuth.
URL: https://mcp.gscwizard.com/mcp
OAuth Client ID: (leave blank)
OAuth Secret: (leave blank)Un solo comando registra il server remoto con un header della chiave. Verifica con /mcp dentro una sessione.
claude mcp add --transport http gsc-wizard \
https://mcp.gscwizard.com/mcp \
--header "Authorization: Bearer gscw_live_..."Il file di configurazione desktop avvia solo server stdio locali, quindi una voce "type": "http" non supera la validazione. Collega il server remoto tramite mcp-remote (richiede Node.js) se ti serve una chiave statica invece di OAuth.
{
"mcpServers": {
"gsc-wizard": {
"command": "npx",
"args": [
"-y", "mcp-remote",
"https://mcp.gscwizard.com/mcp",
"--header", "Authorization: Bearer gscw_live_..."
]
}
}
}Dichiaralo come server MCP HTTP nelle opzioni dell'agente; l'SDK gestisce l'handshake JSON-RPC.
mcpServers: {
"gsc-wizard": {
type: "http",
url: "https://mcp.gscwizard.com/mcp",
headers: { Authorization: `Bearer ${process.env.GSCW_API_KEY}` }
}
}Usa una chiave con scope di sola lettura per tutto ciò che gira senza supervisione. Se all'agente servono solo pochi tool, limita anche lato client l'elenco dei tool consentiti: un perimetro più piccolo costa meno a ogni turno e restringe ciò che una prompt injection nel contenuto di una pagina recuperata potrebbe raggiungere.
128 tool registrati: 96 di lettura e 32 di modifica, tutti disponibili per ogni account. Ogni tool dichiara annotazioni MCP (readOnlyHint, destructiveHint, openWorldHint, title), così un client può presentarli o filtrarli senza scrivere i nomi nel codice.
| Gruppo | Tool rappresentativi | Scope |
|---|---|---|
| Analisi della ricerca | query_search_analytics, query_top_queries, query_top_pages, query_countries, query_devices | lettura |
| Analisi | find_decaying_content, analyze_cannibalization, get_ranking_changes, score_opportunities, analyze_ctr_curve | lettura |
| Rilevamento | detect_anomalies, detect_change_points, forecast_traffic, get_decay_overview | lettura |
| Indicizzazione | inspect_url, bulk_inspect_urls, get_indexing_tracker, list_sitemaps | lettura |
| Altre fonti | Bing Webmaster, GA4, Yandex, Merchant Center, Core Web Vitals | lettura |
| Modifiche | submit_sitemap, submit_indexnow_urls, create_topic_cluster, create_annotation, add_site | scrittura |
L'analisi gira lato server. Decay, cannibalizzazione, modellazione della curva del CTR, rilevamento dei change point e punteggio delle opportunità vengono calcolati nel server e restituiti come risultati. Il modello riceve le conclusioni e le righe che le sostengono, non un dump grezzo su cui ragionare statisticamente: costa meno a ogni turno e non soffre di derive aritmetiche.
Il catalogo completo, tool per tool, con schemi degli argomenti ed esempi di payload è pubblicato su mcp.gscwizard.com e viene verificato con test di copertura rispetto al registro, quindi non può restare indietro in silenzio rispetto ai tool effettivamente registrati.
Il rischio non sono i limiti di righe, ma quelli non dichiarati. Un modello che riceve esattamente limit righe non sa distinguere una risposta completa da una tagliata e riferirà con sicurezza "il tuo sito ha 100 query". I tool con limite di righe quindi recuperano una riga di sonda in più, restituiscono al massimo limit righe e allegano un blocco che indica la finestra, se ce ne sono altre e la chiamata esatta successiva.
"pagination": {
"limit": 100,
"offset": 0,
"returned": 100,
"hasMore": true,
"note": "Showing rows 1-100. Call again with offset: 100 for the next page."
}query_search_analytics ha come valore predefinito 100 righe invece delle 1.000 originali: con 1.000 una singola chiamata restituiva circa 58k token, più contesto dell'intero elenco dei tool. I tool di analisi con classifica applicano il limite nel core analitico condiviso e non includono un blocco di paginazione.
Nessun tool richiede che chi chiama conosca la data di oggi. Le finestre omesse usano come valore predefinito gli ultimi 28 giorni consolidati, tenendo conto del ritardo di circa tre giorni nei dati di Search Console, e il periodo di confronto predefinito è quello precedente della stessa lunghezza. Il parser delle date converte inoltre i valori null, "null" e "" che i client LLM emettono spesso in "usa il valore predefinito" invece di far fallire la validazione, il che elimina un'intera classe di loop di tentativi.
| Campo | Significato |
|---|---|
dataSource | clickhouse o api: quale percorso ha servito questa lettura |
settledThrough | Ultima data con dati completi |
dataMaturity | Prima data incompleta, fuso orario di riferimento, sonda usata |
note | Avvertenza sulla freschezza dei dati, in forma testuale, che il modello può riportare |
Esistono per poter attribuire una risposta alla sua fonte. Quando Claude dice che il traffico è calato la settimana scorsa, è settledThrough a distinguere un calo reale dal ritardo dei dati, che è il falso allarme più comune nell'analisi automatizzata di Search Console.
La maggior parte delle letture non tocca l'API di Search Console. I dati storici sul rendimento vengono caricati in un data warehouse ClickHouse e le letture idonee vengono servite da lì: uno storico più lungo della finestra di 16 mesi dell'API e nessun campionamento lato API sulle proprietà ad alta cardinalità.
Otto tool di analisi della ricerca (query_search_analytics, query_top_queries, query_top_pages, query_countries, query_devices, get_site_summary, get_query_performance, get_page_performance) e undici tool di analisi.
Richieste che richiedono searchAppearance, il tipo googleNews, tre o più dimensioni distinte o la paginazione. Vale anche per qualsiasi proprietà il cui backfill non sia stato completato.
L'instradamento è automatico e avviene a ogni richiesta; chi chiama non sceglie. Le letture dal warehouse usano un ruolo di sola lettura e una row policy legata all'account, quindi il confine tra tenant è garantito dal database e non solo dal query builder. Il server non scrive mai nel warehouse su un percorso di lettura.
Conseguenza pratica per Claude: il warehouse è indietro di circa due giorni rispetto al tempo reale, mentre l'API in tempo reale è indietro di circa tre, e le risposte servite dal warehouse lo indicano in note. Chiedi "la settimana scorsa" e ottieni settimane complete, non una coda parziale presentata come un calo.
| Interfaccia | Al minuto | All'ora |
|---|---|---|
| MCP | 60 | 1.000 |
REST /v1 | 180 | 2.000 |
Conteggiati per utente e per interfaccia. Una chiamata limitata indica quale finestra è scattata e quanti secondi attendere, così un agente può rallentare con precisione invece di tirare a indovinare. I controlli URL hanno una quota giornaliera separata da parte di Google, leggibile con get_inspection_quota.
| Condizione | Comportamento |
|---|---|
| Una chiave di lettura chiama un tool di scrittura | Rifiutata prima che l'handler giri |
| Proprietà non collegata o permesso non concesso | Il controllo dei permessi rifiuta indicando il motivo |
| Integrazione non configurata | Restituisce notConfigured: true con un motivo invece di dare errore |
| ID di sessione riutilizzato con altre credenziali | Rifiutato, non riassegnato |
| OAuth Google appena fatto, proprietà non ancora propagata | Google restituisce 403 per un breve periodo; riprova poco dopo il collegamento |
La convenzione notConfigured è importante per gli agenti: una connessione GA4 o Merchant Center non configurata è uno stato da segnalare, non un'eccezione da ritentare, e distinguere le due cose impedisce a un loop di bruciare il proprio rate limit su una condizione che nessun nuovo tentativo può risolvere.
Le credenziali Google non arrivano mai a Claude. I token di Search Console sono conservati lato server, cifrati a riposo, e rinnovati dal server. Claude possiede un token o una chiave valida per GSC Wizard, non per Google.
Lo scope è strutturale. Una credenziale con scope di sola lettura non può raggiungere un handler di modifica. Il controllo è applicato nella pipeline condivisa, quindi vale allo stesso modo su MCP e REST.
Le chiavi sono sottoposte a hash. Solo SHA-256; il testo in chiaro compare una sola volta. La revoca è immediata.
Ogni chiamata viene registrata nell'audit log, riuscita o fallita: le letture senza argomenti, le scritture con gli argomenti. Le azioni di un agente sono ricostruibili a posteriori.
L'accesso alle proprietà dipende dal permesso concesso. Claude vede solo le proprietà collegate all'account e le proprietà condivise hanno i propri permessi, compresi i destinatari in sola lettura che non possono consumare il crawl budget del titolare.
Per un agente senza supervisione la configurazione consigliata è una chiave con scope di sola lettura più una allowlist lato client dei tool specifici di cui il lavoro ha bisogno. Questa combinazione limita il raggio d'azione di una prompt injection che arrivi da qualsiasi contenuto recuperato dall'agente.
Molto spesso è stato compilato un client ID o un secret. Il server usa la registrazione dinamica del client, quindi entrambi i campi devono essere vuoti. Rimuovi il connettore, aggiungilo di nuovo solo con l'URL e lascia che Claude si registri da solo.
Controlla i due requisiti imposti dall'endpoint di autorizzazione: un abbonamento attivo e almeno una proprietà di Search Console collegata all'account. Un token emesso per un account senza proprietà collegate non ha nulla che possa leggere.
Il file di configurazione avvia solo processi stdio locali, quindi "type": "http" non è una voce valida. Usa l'interfaccia Connettori oppure collega tramite npx -y mcp-remote come mostrato sopra.
Google ha bisogno di un breve intervallo per propagare un'autorizzazione di Search Console appena concessa. Un 403 nei primi minuti dopo il collegamento di solito è dovuto alla propagazione e non a un errore di permessi; riprova prima di rifare il flusso OAuth.
Controlla dataSource e settledThrough nella risposta. Una lettura servita dal warehouse e una vista dell'interfaccia sullo stesso intervallo nominale possono finire in date diverse e l'interfaccia stessa campiona i report di query ad alta cardinalità, mentre il warehouse no.
Di solito è un loop di tentativi contro una risposta notConfigured, che nessun nuovo tentativo può risolvere, oppure un'iterazione pagina per pagina dove un solo tool di analisi risponderebbe in una chiamata. Preferisci i tool di analisi lato server al recupero di righe su cui ragionare.
Streamable HTTP su https://mcp.gscwizard.com/mcp. La continuità della sessione passa dall'header di risposta Mcp-Session-Id e ogni sessione è vincolata lato server all'utente che l'ha aperta, quindi un ID di sessione riutilizzato con credenziali diverse viene rifiutato. Esiste un punto di ingresso stdio per le build locali e un'interfaccia REST su /v1 che serve HTTP+JSON semplice attraverso la stessa pipeline.
Il server MCP è il resource server OAuth 2.1 e pubblica i metadati della risorsa protetta RFC 9728 che indicano tool.gscwizard.com come authorization server. Claude poi legge i metadati RFC 8414 di quell'emittente, si registra tramite la registrazione dinamica del client RFC 7591 ed esegue un flusso authorization_code con PKCE S256. Per questo i campi client ID e secret vanno lasciati vuoti.
mcp:read e mcp:write. I bearer token sono accettati solo nell'header Authorization. Le chiavi API hanno la stessa distinzione come scope fissato alla creazione: una chiave di lettura non può invocare un tool di modifica, quindi il blocco è strutturale e non un'istruzione nel prompt.
128 tool registrati: 96 di lettura e 32 di modifica, tutti disponibili per ogni account. Tutte e tre le interfacce passano da un'unica pipeline runTool(), quindi autorizzazione, validazione, verifica dei permessi e audit trail non possono divergere tra loro.
Il file di configurazione di Claude Desktop avvia solo server stdio locali, quindi una voce HTTP remota non supera la validazione. Usa l'interfaccia Connettori, che parla Streamable HTTP su OAuth in modo nativo, oppure collega il server remoto tramite npx mcp-remote, che richiede Node.js e ti permette di presentare invece una chiave API statica gscw_live_.
L'interfaccia MCP consente 60 chiamate al minuto e 1.000 all'ora per utente. L'interfaccia REST su /v1 ne consente 180 al minuto e 2.000 all'ora. I limiti sono conteggiati per utente e per interfaccia e una chiamata limitata restituisce i secondi da attendere prima di riprovare.
Non per la maggior parte delle letture. Otto tool di analisi della ricerca e undici tool di analisi vengono instradati automaticamente a un data warehouse ClickHouse che contiene lo storico di Search Console dell'account, il che dà uno storico più lungo ed evita il campionamento dell'API. Ogni risposta contiene un campo dataSource con valore clickhouse o api, più settledThrough e una nota sulla freschezza quando la lettura è servita dal warehouse. Le richieste che richiedono searchAppearance, il tipo googleNews, tre o più dimensioni distinte o la paginazione ripiegano sempre sull'API in tempo reale.
I tool con limite di righe recuperano una singola riga di sonda in più e restituiscono un blocco di paginazione che indica la finestra, se esistono altre righe e la chiamata esatta successiva. Il troncamento silenzioso è il difetto che si vuole eliminare in partenza: un modello che riceve esattamente limit righe non sa distinguere una risposta completa da una tagliata. query_search_analytics ha come valore predefinito 100 righe perché con 1.000 una singola chiamata restituiva circa 58k token, più contesto dell'intero elenco dei tool.
La guida passo passo alla configurazione per Claude web, desktop e Claude Code.
La panoramica del prodotto: cosa fa il server con ogni client MCP.
La parte GA4 dello stesso server: sessioni, eventi chiave, ecommerce e traffico da LLM.
La parte Yandex dello stesso server: indice di qualità del sito, query e storico di indicizzazione.
La parte shopping dello stesso server: schede senza costi, problemi dei prodotti, prezzi e audit del feed.
Cursor, VS Code, Windsurf, Gemini, Grok e ChatGPT, oltre a Claude.
Gli stessi dati nell'app Gemini, in Antigravity CLI, in Gemini Enterprise o nella Gemini API.
Un esempio concreto di agente autonomo costruito su questo server più un MCP di crawler.
Come si confrontano i server con dati di prima parte con le piattaforme di terze parti.
Un solo endpoint, OAuth o una chiave con scope limitato, e 128 tool sulle proprietà che già possiedi.
Workflow pratici per GSC e GA4, aggiornamenti del prodotto ed esperimenti SEO. Niente spam, puoi annullare l'iscrizione quando vuoi.