Solução de problemas do MCP

Comece pelo code estável do erro, se o cliente o exibir. Erros de autenticação MCP podem chegar em uma resposta JSON-RPC com HTTP 200, e uma falha de ferramenta pode ter isError: true. O status HTTP sozinho não comprova que a operação funcionou.

Começar com um diagnóstico seguro

Usando o servidor da conta, peça:

Para minha conexão “Inventory example”, verifique o que o Sheet Best pode fazer com a planilha.

O cliente deve resolver o ID da conexão com sheetbest_list_connections e depois chamar sheetbest_get_permissions. A verificação de permissões não altera a planilha nem consome sua cota mensal de requisições.

Se a verificação funcionar, você também pode testar o acesso aos dados:

Liste as primeiras 10 linhas.

Essa leitura não altera dados, mas conta como uma requisição de API bem-sucedida. Se alguma verificação falhar, procure o erro ou sintoma correspondente abaixo.

O cliente não consegue conectar

Causas prováveis

• A URL do servidor está incompleta ou aponta para o ambiente errado.
• O cliente não enviou o token como credencial de portador.
• O cliente não aceita servidores MCP remotos Streamable HTTP.
• A origem de um cliente de navegador não foi aprovada.

Verificar

1. Copie novamente o Account endpoint de AI assistants · MCP.
2. Confirme se o campo do token começa com sbmcp_; não cole o token na URL.
3. Confirme se o cliente aceita um servidor MCP remoto e autenticação de portador.
4. Verifique se o cliente informa missing_token, invalid_token ou um erro de origem.

Recuperar

Reconecte usando o endpoint copiado e o token guardado. Substitua o token se não conseguir verificar seu valor. Para um erro de origem, entre em contato com o suporte e informe o nome, a versão e a origem do cliente.

O token é rejeitado

Código	Causa provável	Recuperação
missing_token	O endpoint da conta não recebeu um token de portador.	Adicione seu token MCP nas configurações de autenticação do cliente.
invalid_token	O token foi digitado incorretamente ou não está mais ativo.	Copie o token guardado novamente ou substitua-o nas configurações da conta.
revoked_token	A credencial foi revogada ou substituída.	Gere um novo token e atualize este cliente.
mcp_disabled	MCP support está desativado na conta.	Ative o MCP. O token mantido volta a funcionar, a menos que também tenha sido revogado.

Se vários clientes pararam juntos, verifique se alguém substituiu o único token ativo.

Um endpoint de conexão retorna 404

O Sheet Best usa 404 quando uma conexão não existe, está arquivada, tem MCP desativado ou não pertence ao usuário do token. Isso impede que um usuário descubra a conexão de outro.

Verificar

• Execute sheetbest_list_connections no endpoint da conta.
• Compare o directMcpUrl retornado com a URL do servidor no cliente.
• Verifique mcpEnabled e se a conexão está arquivada.

Recuperar

Use a URL retornada. Restaure uma conexão arquivada, se apropriado. Se uma conexão informar mcpEnabled: false, ative MCP access (Acesso ao MCP) na página da conexão no Sheet Best.

Uma ferramenta esperada está ausente

Causas prováveis

• O método necessário está desativado em Advanced Settings → Methods (Configurações avançadas → Métodos).
• Seu plano não inclui o recurso necessário.
• O cliente armazenou uma lista antiga de ferramentas em cache.

Verificar e recuperar

1. No endpoint da conta, confirme se a chamada inclui connection_id. Em um endpoint direto, confirme se a URL contém /connections/<connection_id>.
2. Revise os requisitos das ferramentas.
3. Ative o método necessário na conexão se a operação deve ser permitida.
4. Reconecte ou atualize o servidor MCP.

sheetbest_get_info também exige um plano com acesso a consultas avançadas. Agregações, tabelas dinâmicas, recursos e streaming não estão disponíveis no servidor MCP atual.

O acesso do Google ou as verificações da planilha falham

Código	O que verificar	Recuperação
sheet_access_denied	Compartilhamento da planilha e conta do Google usada pelo Sheet Best	Conceda acesso de Leitor para ler ou de Editor para gravar.
sheet_access_check_failed	Problema temporário de autorização ou acesso do Google	Verifique o acesso e execute a ferramenta de permissões novamente.
upstream_sheet_not_found	A planilha de origem foi excluída, movida ou não está mais acessível	Restaure a planilha ou crie uma conexão com a URL correta.
upstream_permission_denied	O Google negou a operação solicitada	Conceda à conta autorizada a permissão necessária na planilha.
invalid_sheet_url	A URL não é uma URL nativa do Google Sheets	Use uma URL que comece com https://docs.google.com/spreadsheets/d/.

Execute sheetbest_get_permissions. google.isEditable deve ser true para gravar. Para planilhas privadas, consulte planilhas privadas.

A planilha não tem cabeçalhos válidos

malformed_sheet_content geralmente indica que a primeira linha não contém nomes de coluna válidos.

1. Abra a aba afetada.
2. Coloque um cabeçalho não vazio e utilizável na primeira linha de cada coluna necessária.
3. Remova células de cabeçalho mescladas ou malformadas.
4. Execute sheetbest_get_permissions novamente.

Consulte preparar sua planilha.

Um plano ou a cota bloqueia a operação

Código	Significado	Recuperação
quota_exceeded	A conta não tem requisições restantes.	Aguarde a renovação ou faça upgrade do plano.
trial_expired	O período de teste não permite mais a operação.	Ative um plano pago.
plan_required	A operação exige um recurso ausente no plano atual.	Use um plano compatível ou escolha outra ferramenta.
method_not_allowed	A conexão não permite o método lógico da ferramenta.	Ative esse método nas configurações da conexão, se apropriado.

Chame sheetbest_get_limits para consultar limit, remaining e plan sem consumir cota. sheetbest_get_permissions mostra as ações permitidas e efetivas.

A ferramenta informa argumentos inválidos

invalid_arguments significa que a chamada não corresponde ao esquema anunciado da ferramenta. Exemplos comuns:

• limit é menor que 1 ou maior que 1000;
• offset é negativo;
• um valor de consulta não começa com um operador aceito;
• uma atualização ou exclusão fornece tanto index quanto columns, ou nenhum deles;
• os dados de linha estão vazios ou usam nomes de argumentos inesperados.

Peça ao cliente para atualizar a lista de ferramentas e tente novamente com as entradas documentadas.

A saída é grande demais

output_too_large significa que o resultado ultrapassou o limite de tamanho da resposta MCP.

Reduza limit, use um filtro columns ou query mais específico ou aumente offset para obter a próxima página. Uma resposta que falha por excesso de tamanho não registra uma requisição de API bem-sucedida.

Os dados parecem desatualizados após uma gravação

Ao trabalhar com a primeira aba, omitir tab e enviar explicitamente seu nome usam caminhos de cache temporários diferentes.

Recuperar

• Use a mesma forma de tab para leituras e gravações relacionadas.
• Se já misturou as duas formas, tente novamente após o intervalo de cache da conexão.

Isso não afeta gravações em outra aba com nome.

Substituir um token interrompeu outro cliente

O Sheet Best permite um token MCP ativo por usuário. Replace token (Substituir token) invalida imediatamente o token anterior para todos os clientes configurados.

Atualize todos os clientes confiáveis com o novo token. Se não tiver mais o valor completo, substitua-o novamente e guarde o novo token antes de fechar o diálogo.

Uma operação falha sem um código específico

Para operation_failed, tente novamente uma vez. Depois:

1. Execute sheetbest_get_permissions.
2. Verifique os métodos permitidos da conexão e o acesso do Google.
3. Confirme se a planilha ainda tem cabeçalhos válidos.
4. Anote o nome do cliente, o nome da conexão, a ferramenta, o horário e o código do erro.

Não inclua seu token, chave de API, URL de planilha privada nem conteúdo das linhas ao entrar em contato com o suporte do Sheet Best.

Para erros REST fora do MCP, use o guia geral de solução de problemas e a referência de códigos de erro.

Próximo passo

Volte ao guia rápido do MCP depois de corrigir a conexão ou as credenciais.