El servidor MCP de GSC Wizard es un recurso remoto de Model Context Protocol, protegido con OAuth, que expone a Claude los datos de Google Search Console, Bing Webmaster, GA4 y Merchant Center. Esta página es la referencia técnica: el transporte, la cadena de autenticación, el conjunto de herramientas, el contrato de respuesta, cómo se enrutan las lecturas y cuáles son los límites.
Si prefieres la configuración paso a paso, usa la guía de conexión con Claude. Para la visión general del producto con todos los clientes, consulta el MCP de Google Search Console.
https://mcp.gscwizard.com/mcp
Streamable HTTP
OAuth 2.1 (DCR + PKCE) or Bearer key
128 · 96 read / 32 write
El servidor habla MCP sobre Streamable HTTP. No existe un endpoint de reserva solo con SSE; los clientes que todavía asumen el par HTTP+SSE, ya obsoleto, deben apuntar a la ruta única /mcp, que negocia el streaming en cada petición.
| Ruta | Autenticación | Finalidad |
|---|---|---|
POST /mcp | Obligatoria | JSON-RPC sobre Streamable HTTP |
/v1/* | Obligatoria | Superficie REST para clientes que no usan MCP |
GET /health | Pública | Devuelve { ok, sessions } |
GET /, /docs | Pública | Catálogo de herramientas renderizado |
/.well-known/oauth-protected-resource | Pública | Metadatos del recurso según RFC 9728 |
La continuidad de la sesión se apoya en la cabecera de respuesta Mcp-Session-Id, que el cliente devuelve en las peticiones siguientes. Cada sesión queda fijada en el servidor al user_id que la abrió. Si se vuelve a presentar un id de sesión con otra credencial, se rechaza en lugar de reasignarlo en silencio, de modo que un id de sesión filtrado no basta por sí solo para leer una cuenta.
MCP stdio, MCP Streamable HTTP y la API REST en /v1 se ejecutan por el mismo pipeline runTool(). La autorización, la validación de argumentos, la comprobación de permisos por propiedad, el control de suscripción, el limitador de tasa y el registro de auditoría se aplican en ese único punto, así que no pueden divergir entre transportes. Una herramienta añadida al registro es accesible, y se rige exactamente igual, en las tres.
Dos mecanismos, elegidos según lo que admita el cliente. La interfaz de Conectores de Claude usa OAuth 2.1; los clientes con archivo de configuración y los clientes sin interfaz presentan una clave de API estática.
El servidor MCP es el servidor de recursos; la app en tool.gscwizard.com es el servidor de autorización. Claude recorre la cadena de forma automática:
Un GET sin autenticar sobre el recurso indica el servidor de autorización y los scopes.
Claude consulta /.well-known/oauth-authorization-server en el emisor para localizar los endpoints.
Claude se registra por sí mismo y recibe su propio client ID. Por eso los campos de client ID y secret se dejan en blanco al añadir el conector: rellenarlos se adelanta al registro y rompe el flujo.
Una concesión authorization_code con desafío S256, renovable. El inicio de sesión y el consentimiento de Google ocurren en el servidor de autorización, nunca en Claude.
Metadatos del recurso
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"]
}Metadatos del servidor de autorización
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"
]
}Dos requisitos antes de emitir un token. El endpoint de autorización exige una suscripción activa y al menos una propiedad de Search Console conectada. Una cuenta que no cumple ninguno de los dos se redirige para completarlos primero, en lugar de recibir un token que rechazaría cada llamada posterior a una herramienta.
Las claves llevan el prefijo gscw_live_, se crean en Cuenta → Claves de API y se presentan como Authorization: Bearer. Solo se almacena un hash SHA-256, de modo que el texto en claro se muestra una única vez al crearla y no se puede recuperar después; rotarla significa emitir una clave nueva y revocar la anterior.
Cada clave lleva un scope fijado en su creación. Una clave con scope de lectura no puede invocar una herramienta de mutación: la comprobación se ejecuta en el pipeline antes del handler, así que el modo de solo lectura es una propiedad estructural de la credencial y no una instrucción de la que se pueda convencer al modelo para que prescinda.
Cuatro superficies de Claude, tres mecanismos de conexión distintos.
Ajustes → Conectores → Añadir conector personalizado. Introduce la URL y deja vacíos los dos campos de OAuth.
URL: https://mcp.gscwizard.com/mcp
OAuth Client ID: (leave blank)
OAuth Secret: (leave blank)Un solo comando registra el servidor remoto con una cabecera de clave. Compruébalo con /mcp dentro de una sesión.
claude mcp add --transport http gsc-wizard \
https://mcp.gscwizard.com/mcp \
--header "Authorization: Bearer gscw_live_..."El archivo de configuración de escritorio lanza solo servidores stdio locales, así que una entrada "type": "http" no supera la validación. Conecta el servidor remoto a través de mcp-remote (requiere Node.js) si necesitas una clave estática en lugar de OAuth.
{
"mcpServers": {
"gsc-wizard": {
"command": "npx",
"args": [
"-y", "mcp-remote",
"https://mcp.gscwizard.com/mcp",
"--header", "Authorization: Bearer gscw_live_..."
]
}
}
}Decláralo como servidor MCP HTTP en las opciones del agente; el SDK se encarga del handshake JSON-RPC.
mcpServers: {
"gsc-wizard": {
type: "http",
url: "https://mcp.gscwizard.com/mcp",
headers: { Authorization: `Bearer ${process.env.GSCW_API_KEY}` }
}
}Usa una clave con scope de lectura para cualquier ejecución desatendida. Si el agente solo necesita un puñado de herramientas, restringe también la lista de herramientas permitidas en el cliente: una superficie menor es más barata por turno y reduce lo que podría alcanzar una inyección de prompt en el contenido de una página descargada.
128 herramientas registradas: 96 de lectura y 32 de mutación, todas disponibles para cualquier cuenta. Cada herramienta anuncia anotaciones MCP (readOnlyHint, destructiveHint, openWorldHint, title), de modo que un cliente puede mostrarlas o filtrarlas sin fijar nombres en el código.
| Grupo | Herramientas representativas | Scope |
|---|---|---|
| Analítica de búsqueda | query_search_analytics, query_top_queries, query_top_pages, query_countries, query_devices | lectura |
| Análisis | find_decaying_content, analyze_cannibalization, get_ranking_changes, score_opportunities, analyze_ctr_curve | lectura |
| Detección | detect_anomalies, detect_change_points, forecast_traffic, get_decay_overview | lectura |
| Indexación | inspect_url, bulk_inspect_urls, get_indexing_tracker, list_sitemaps | lectura |
| Otras fuentes | Bing Webmaster, GA4, Yandex, Merchant Center, Core Web Vitals | lectura |
| Mutaciones | submit_sitemap, submit_indexnow_urls, create_topic_cluster, create_annotation, add_site | escritura |
El análisis se ejecuta en el servidor. El decaimiento, la canibalización, el modelado de la curva de CTR, la detección de puntos de cambio y la puntuación de oportunidades se calculan en el servidor y se devuelven como resultados. El modelo recibe conclusiones y las filas que las respaldan, no un volcado en bruto sobre el que razonar estadísticamente, lo cual es más barato por turno y no está expuesto a errores aritméticos.
El catálogo completo de cada herramienta, con sus esquemas de argumentos y ejemplos de payload, está publicado en mcp.gscwizard.com y se contrasta con el registro mediante tests de cobertura, así que no puede quedarse atrás en silencio respecto a las herramientas realmente registradas.
El riesgo no son los límites de filas, sino los límites no declarados. Un modelo al que se le entregan exactamente limit filas no puede distinguir una respuesta completa de una recortada, y afirmará con seguridad que "tu sitio tiene 100 consultas". Por eso las herramientas con límite de filas piden una fila de sondeo de más, devuelven como máximo limit y adjuntan un bloque que indica la ventana, si hay más resultados y la siguiente llamada exacta.
"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 devuelve por defecto 100 filas en lugar de las 1000 originales: con 1000, una sola llamada devolvía unos 58k tokens, más contexto que toda la lista de herramientas. Las herramientas de análisis con ranking aplican el límite dentro del núcleo de analítica compartido y no incluyen bloque de paginación.
Ninguna herramienta exige que quien llama conozca la fecha de hoy. Si se omite la ventana, se toman por defecto los últimos 28 días consolidados, teniendo en cuenta el retraso de unos tres días de los informes de Search Console, y la base de comparación es por defecto el periodo anterior de la misma duración. El analizador de fechas también convierte los valores null, "null" y "", que los clientes LLM suelen emitir, en "usar el valor por defecto" en lugar de fallar en la validación, lo que elimina toda una clase de bucles de reintento.
| Campo | Significado |
|---|---|
dataSource | clickhouse o api: qué vía sirvió esta lectura |
settledThrough | Última fecha con datos completos |
dataMaturity | Primera fecha incompleta, zona horaria de referencia, sondeo utilizado |
note | Aviso de frescura en texto para que el modelo lo transmita |
Existen para poder atribuir una respuesta. Cuando Claude dice que el tráfico cayó la semana pasada, settledThrough es lo que distingue un descenso real del retraso de los informes, que es la falsa alarma más habitual en el análisis automatizado de Search Console.
La mayoría de las lecturas no llegan a la API de Search Console. Los datos históricos de rendimiento se ingieren en un almacén de datos ClickHouse y las lecturas elegibles se sirven desde ahí: más historial que la ventana de 16 meses de la API y sin el muestreo de la API en propiedades de alta cardinalidad.
Ocho herramientas de analítica de búsqueda (query_search_analytics, query_top_queries, query_top_pages, query_countries, query_devices, get_site_summary, get_query_performance, get_page_performance) y once herramientas de análisis.
Peticiones que necesitan searchAppearance, el tipo googleNews, tres o más dimensiones distintas o paginación. También cualquier propiedad cuyo backfill no haya terminado.
El enrutamiento es automático y se decide en cada petición; quien llama no elige. Las lecturas del almacén de datos usan un rol de solo lectura y una política de filas ligada a la cuenta, de modo que el límite entre inquilinos lo impone la base de datos y no solo el generador de consultas. El servidor nunca escribe en el almacén de datos en una ruta de lectura.
Consecuencia práctica para Claude: el almacén de datos va unos dos días por detrás del tiempo real, mientras que la API en vivo va unos tres, y las respuestas servidas desde el almacén lo indican en note. Si pides "la semana pasada", obtienes semanas completas, no un tramo parcial presentado como una caída.
| Superficie | Por minuto | Por hora |
|---|---|---|
| MCP | 60 | 1000 |
REST /v1 | 180 | 2000 |
Se cuenta por usuario y por superficie. Una llamada limitada indica qué ventana se ha superado y cuántos segundos hay que esperar, de modo que un agente puede espaciar las peticiones con precisión en lugar de adivinar. Las inspecciones de URLs tienen una cuota diaria aparte de Google, que se consulta con get_inspection_quota.
| Condición | Comportamiento |
|---|---|
| Una clave de lectura llama a una herramienta de escritura | Se rechaza antes de que se ejecute el handler |
| Propiedad no conectada o sin permiso concedido | La comprobación de permisos rechaza e indica el motivo |
| Integración no configurada | Devuelve notConfigured: true con un motivo en lugar de un error |
| Id de sesión reutilizado con otras credenciales | Se rechaza, no se reasigna |
| OAuth de Google recién hecho, propiedad aún sin propagar | Google devuelve 403 durante un breve periodo; vuelve a intentarlo poco después de conectar |
La convención notConfigured es importante para los agentes: una conexión de GA4 o Merchant Center sin configurar es un estado que hay que comunicar, no una excepción que reintentar, y distinguir ambos casos evita que un bucle agote su límite de tasa por una condición que ningún reintento puede arreglar.
Las credenciales de Google nunca llegan a Claude. Los tokens de Search Console se guardan en el servidor, cifrados en reposo, y los renueva el servidor. Claude tiene un token o una clave limitados a GSC Wizard, no a Google.
El scope es estructural. Una credencial con scope de lectura no puede llegar a un handler de mutación. Esto se aplica en el pipeline compartido, así que funciona igual en MCP y en REST.
Las claves se almacenan con hash. Solo SHA-256; el texto en claro se muestra una vez. La revocación es inmediata.
Cada llamada queda registrada en la auditoría, tenga éxito o falle: las lecturas sin argumentos, las escrituras con ellos. Las acciones de un agente se pueden reconstruir a posteriori.
El acceso a las propiedades se concede por permiso. Claude solo ve las propiedades conectadas a la cuenta, y las propiedades compartidas llevan sus propios permisos, incluidos los de solo lectura, que no pueden gastar el presupuesto de rastreo del propietario.
Para un agente desatendido, la configuración recomendada es una clave con scope de lectura más una lista de permitidas en el cliente con las herramientas concretas que necesita la tarea. Esa combinación acota el alcance de una inyección de prompt que llegue a través de cualquier contenido que el agente descargue.
Lo más habitual es que se haya rellenado el client ID o el secret. El servidor usa registro dinámico de clientes, así que ambos campos deben quedar en blanco. Elimina el conector, vuelve a añadirlo solo con la URL y deja que Claude se registre por sí mismo.
Comprueba los dos requisitos que aplica el endpoint de autorización: una suscripción activa y al menos una propiedad de Search Console conectada a la cuenta. Un token emitido para una cuenta sin ninguna propiedad conectada no tiene nada que pueda leer.
El archivo de configuración solo lanza procesos stdio locales, así que "type": "http" no es una entrada válida. Usa la interfaz de Conectores o conecta a través de npx -y mcp-remote, como se muestra arriba.
Google necesita un breve margen para propagar una autorización de Search Console recién concedida. Un 403 en los primeros minutos tras conectar suele deberse a la propagación y no a un error de permisos; vuelve a intentarlo antes de repetir el flujo de OAuth.
Revisa dataSource y settledThrough en la respuesta. Una lectura servida desde el almacén de datos y una vista de la interfaz con el mismo rango nominal pueden terminar en fechas distintas, y la propia interfaz aplica muestreo a los informes de consultas de alta cardinalidad, algo que el almacén no hace.
Normalmente es un bucle de reintentos contra una respuesta notConfigured, que ningún reintento puede resolver, o una iteración página por página cuando una herramienta de análisis respondería en una sola llamada. Prefiere las herramientas de análisis del servidor a descargar filas y razonar sobre ellas.
Streamable HTTP en https://mcp.gscwizard.com/mcp. La continuidad de la sesión la lleva la cabecera de respuesta Mcp-Session-Id, y cada sesión queda fijada en el servidor al usuario que la abrió, de modo que un id de sesión reutilizado con otras credenciales se rechaza. Existe un punto de entrada stdio para compilaciones locales y una superficie REST en /v1 que sirve HTTP+JSON plano a través del mismo pipeline.
El servidor MCP es el servidor de recursos de OAuth 2.1 y publica metadatos de recurso protegido según RFC 9728 que designan a tool.gscwizard.com como servidor de autorización. Claude lee entonces los metadatos RFC 8414 de ese emisor, se registra mediante el registro dinámico de clientes de RFC 7591 y ejecuta un flujo authorization_code con PKCE S256. Por eso los campos de client ID y secret se dejan en blanco.
mcp:read y mcp:write. Los bearer tokens solo se aceptan en la cabecera Authorization. Las claves de API llevan la distinción equivalente como un scope fijado en su creación: una clave de lectura no puede invocar una herramienta de mutación, así que la barrera es estructural y no una instrucción del prompt.
128 herramientas registradas: 96 de lectura y 32 de mutación, todas disponibles para cualquier cuenta. Las tres superficies se ejecutan por un único pipeline runTool(), así que la autorización, la validación, la comprobación de permisos y el registro de auditoría no pueden divergir entre ellas.
El archivo de configuración de Claude Desktop solo lanza servidores stdio locales, así que una entrada HTTP remota no supera la validación. Usa la interfaz de Conectores, que habla Streamable HTTP sobre OAuth de forma nativa, o conecta el servidor remoto a través de npx mcp-remote, que requiere Node.js y permite presentar en su lugar una clave de API estática gscw_live_.
La superficie MCP permite 60 llamadas por minuto y 1000 por hora por usuario. La superficie REST en /v1 permite 180 por minuto y 2000 por hora. Los límites se cuentan por usuario y por superficie, y una llamada limitada devuelve el número de segundos que hay que esperar antes de reintentar.
No en la mayoría de las lecturas. Ocho herramientas de analítica de búsqueda y once de análisis se enrutan automáticamente a un almacén de datos ClickHouse que guarda el historial de Search Console de la cuenta, lo que ofrece más historial y evita el muestreo de la API. Cada respuesta incluye un campo dataSource con el valor clickhouse o api, además de settledThrough y una nota de frescura cuando se sirve desde el almacén. Las peticiones que necesitan searchAppearance, el tipo googleNews, tres o más dimensiones distintas o paginación siempre recurren a la API en vivo.
Las herramientas con límite de filas piden una única fila de sondeo de más y devuelven un bloque de paginación que indica la ventana, si existen más filas y la siguiente llamada exacta. El fallo que se quiere eliminar de raíz es el truncado silencioso: un modelo al que se le entregan exactamente limit filas no puede distinguir una respuesta completa de una recortada. query_search_analytics devuelve 100 filas por defecto porque con 1000 una sola llamada devolvía unos 58k tokens, más contexto que toda la lista de herramientas.
La guía de configuración paso a paso para Claude web, de escritorio y Claude Code.
La visión general del producto: qué hace el servidor con cada cliente MCP.
La superficie de GA4 del mismo servidor: sesiones, eventos clave, ecommerce y tráfico de LLM.
La superficie de Yandex del mismo servidor: índice de calidad del sitio, consultas e historial de indexación.
La superficie de shopping del mismo servidor: fichas gratuitas, problemas de producto, precios y una auditoría del feed.
Cursor, VS Code, Windsurf, Gemini, Grok y ChatGPT, además de Claude.
Los mismos datos en la app de Gemini, Antigravity CLI, Gemini Enterprise o la API de Gemini.
Un agente desatendido de ejemplo, construido sobre este servidor y un MCP de rastreador.
Cómo se comparan los servidores con datos propios de la fuente con las plataformas de terceros.
Un endpoint, OAuth o una clave con scope y 128 herramientas sobre las propiedades que ya tienes.
Flujos de trabajo prácticos con GSC y GA4, novedades del producto y experimentos SEO. Sin spam, date de baja cuando quieras.