Solución de problemas de MCP

Empieza por el code estable del error, si tu cliente lo muestra. Los errores de autenticación MCP pueden llegar en una respuesta JSON-RPC con HTTP 200, y un fallo de herramienta puede tener isError: true. El estado HTTP por sí solo no demuestra que la operación haya funcionado.

Empezar con un diagnóstico seguro

Usando el servidor de cuenta, pide:

Para mi conexión «Inventory example», comprueba qué puede hacer Sheet Best con la hoja.

El cliente debe resolver el ID de conexión con sheetbest_list_connections y después llamar a sheetbest_get_permissions. La comprobación de permisos no modifica la hoja ni consume tu cuota mensual de solicitudes.

Si la comprobación funciona, también puedes probar el acceso a los datos:

Lista las primeras 10 filas.

Esta lectura no modifica datos, pero cuenta como una solicitud correcta de API. Si cualquiera de las comprobaciones falla, busca el error o síntoma correspondiente a continuación.

El cliente no puede conectar

Causas probables

• La URL del servidor está incompleta o apunta al entorno equivocado.
• El cliente no envió el token como credencial de portador.
• El cliente no admite servidores MCP remotos Streamable HTTP.
• El origen de un cliente de navegador no está aprobado.

Comprobar

1. Vuelve a copiar el Account endpoint de AI assistants · MCP.
2. Confirma que el campo del token empieza por sbmcp_; no pegues el token en la URL.
3. Confirma que tu cliente admita un servidor MCP remoto y autenticación de portador.
4. Comprueba si el cliente muestra missing_token, invalid_token o un error de origen.

Recuperar

Reconecta usando el endpoint copiado y el token guardado. Sustituye el token si no puedes verificar su valor. Para un error de origen, contacta con soporte e indica el nombre, la versión y el origen del cliente.

El token se rechaza

Código	Causa probable	Recuperación
missing_token	El endpoint de cuenta no recibió un token de portador.	Añade tu token MCP en la configuración de autenticación del cliente.
invalid_token	El token está mal escrito o ya no está activo.	Copia de nuevo el token guardado o sustitúyelo en la configuración de la cuenta.
revoked_token	Las credenciales se revocaron o sustituyeron.	Genera un token nuevo y actualiza este cliente.
mcp_disabled	MCP support está desactivado en la cuenta.	Activa MCP. El token conservado vuelve a funcionar salvo que también se haya revocado.

Si varios clientes dejaron de funcionar a la vez, comprueba si alguien sustituyó el único token activo.

Un endpoint de conexión devuelve 404

Sheet Best usa 404 cuando una conexión no existe, está archivada, tiene MCP desactivado o no pertenece al usuario del token. Esto impide que un usuario descubra la conexión de otro.

Comprobar

• Ejecuta sheetbest_list_connections en el endpoint de cuenta.
• Compara el directMcpUrl devuelto con la URL del servidor en tu cliente.
• Comprueba mcpEnabled y si la conexión está archivada.

Recuperar

Usa la URL devuelta. Restaura una conexión archivada si corresponde. Si una conexión indica mcpEnabled: false, activa MCP access (Acceso a MCP) en su página de Sheet Best.

Falta una herramienta esperada

Causas probables

• El método requerido está desactivado en Advanced Settings → Methods (Configuración avanzada → Métodos).
• Tu plan no incluye la función requerida.
• El cliente guardó una lista de herramientas antigua en caché.

Comprobar y recuperar

1. En el endpoint de cuenta, confirma que la llamada incluya connection_id. En un endpoint directo, confirma que la URL contenga /connections/<connection_id>.
2. Revisa los requisitos de las herramientas.
3. Activa el método requerido en la conexión si la operación debe estar permitida.
4. Reconecta o actualiza el servidor MCP.

sheetbest_get_info también requiere un plan con acceso a consultas avanzadas. Las agregaciones, tablas dinámicas, recursos y streaming no están disponibles en el servidor MCP actual.

Fallan el acceso de Google o las comprobaciones de la hoja

Código	Qué comprobar	Recuperación
sheet_access_denied	Uso compartido de la hoja y cuenta de Google usada por Sheet Best	Concede acceso de Lector para leer o de Editor para escribir.
sheet_access_check_failed	Problema temporal de autorización o acceso de Google	Comprueba el acceso y vuelve a ejecutar la herramienta de permisos.
upstream_sheet_not_found	La hoja de origen se eliminó, movió o ya no es accesible	Restaura la hoja o crea una conexión con la URL correcta.
upstream_permission_denied	Google denegó la operación solicitada	Concede a la cuenta autorizada el permiso necesario sobre la hoja.
invalid_sheet_url	La URL no es una URL nativa de Google Sheets	Usa una URL que empiece por https://docs.google.com/spreadsheets/d/.

Ejecuta sheetbest_get_permissions. google.isEditable debe ser true para escribir. Para hojas privadas, consulta hojas privadas.

La hoja no tiene cabeceras válidas

malformed_sheet_content suele indicar que la primera fila no contiene nombres de columna válidos.

1. Abre la pestaña afectada.
2. Pon una cabecera no vacía y utilizable en la primera fila de cada columna que necesites.
3. Elimina las celdas de cabecera combinadas o mal formadas.
4. Ejecuta sheetbest_get_permissions de nuevo.

Consulta preparar tu hoja.

Un plan o la cuota bloquea la operación

Código	Significado	Recuperación
quota_exceeded	La cuenta no tiene solicitudes restantes.	Espera a la renovación o amplía el plan.
trial_expired	El periodo de prueba ya no permite la operación.	Activa un plan de pago.
plan_required	La operación necesita una función que no incluye el plan actual.	Usa un plan compatible o elige otra herramienta.
method_not_allowed	La conexión no permite el método lógico de la herramienta.	Activa ese método en la configuración de la conexión si corresponde.

Llama a sheetbest_get_limits para consultar limit, remaining y plan sin consumir cuota. sheetbest_get_permissions muestra las acciones permitidas y efectivas.

La herramienta indica argumentos no válidos

invalid_arguments significa que la llamada no coincide con el esquema anunciado de la herramienta. Ejemplos habituales:

• limit es inferior a 1 o superior a 1000;
• offset es negativo;
• un valor de consulta no empieza por un operador admitido;
• una actualización o eliminación proporciona tanto index como columns, o ninguno;
• los datos de fila están vacíos o usan nombres de argumentos inesperados.

Pide al cliente que actualice la lista de herramientas y vuelve a intentarlo con las entradas documentadas.

La salida es demasiado grande

output_too_large significa que el resultado superó el límite de tamaño de respuesta MCP.

Reduce limit, usa un filtro columns o query más específico, o aumenta offset para obtener la siguiente página. Una respuesta fallida por exceso de tamaño no registra una solicitud correcta de API.

Los datos parecen desactualizados después de escribir

Al trabajar con la primera pestaña, omitir tab y enviar explícitamente su nombre usan rutas de caché temporales diferentes.

Recuperar

• Usa la misma forma de tab para lecturas y escrituras relacionadas.
• Si ya mezclaste las dos formas, vuelve a intentarlo después del intervalo de caché de la conexión.

Esto no afecta a las escrituras en otra pestaña con nombre.

Sustituir un token interrumpió otro cliente

Sheet Best permite un token MCP activo por usuario. Replace token (Sustituir token) invalida inmediatamente el anterior para todos los clientes configurados.

Actualiza todos los clientes de confianza con el nuevo token. Si ya no tienes el valor sin ocultar, sustitúyelo de nuevo y guarda el nuevo token antes de cerrar el diálogo.

Una operación falla sin un código específico

Para operation_failed, vuelve a intentarlo una vez. Después:

1. Ejecuta sheetbest_get_permissions.
2. Comprueba los métodos permitidos de la conexión y el acceso de Google.
3. Confirma que la hoja siga teniendo cabeceras válidas.
4. Anota el nombre del cliente, el de la conexión, la herramienta, la hora y el código de error.

No incluyas tu token, clave de API, URL de hoja privada ni contenido de filas al contactar con soporte de Sheet Best.

Para errores REST que no sean de MCP, consulta la guía general de solución de problemas y la referencia de códigos de error.

Próximo paso

Vuelve a la guía rápida de MCP después de corregir la conexión o las credenciales.