Solução de problemas do MCP
Diagnostique problemas na descoberta de ferramentas, na autenticação, no acesso à organização e nos argumentos, além de resultados incertos, antes de tentar novamente.
Use o sintoma para definir a próxima verificação: se uma ferramenta não aparecer, inspecione a conexão; se uma chamada for rejeitada, verifique o erro de argumento ou de permissão. Guarde o nome da ferramenta, as entradas sem dados sigilosos, a resposta e o recurso relevante ou a revisão da fonte. Essas evidências ajudam a retomar o trabalho pretendido sem repetir uma operação de gravação cujo resultado é desconhecido.
As ferramentas esperadas não aparecem #
Compare o endpoint configurado com a lista de ferramentas retornada pelo cliente. /mcp e /main disponibilizam as mesmas ferramentas autenticadas; /account redireciona para /main após a autenticação.
Procure members_listMemberships e engines_list e siga os exemplos de leitura inicial. Consulte a resposta atual de tools/list para obter os nomes e esquemas exatos. A existência de um endpoint de API não significa que o MCP o disponibilize.
Se apenas algumas ferramentas estiverem ocultas, verifique a lista de permissões e as aprovações do cliente e habilite apenas o necessário para a tarefa. Se uma ferramenta que deveria estar disponível não aparecer, guarde os dados do servidor e da versão, além da saída de descoberta sem dados sigilosos, para relatar o problema.
GET retorna 405 #
Configure Streamable HTTP em /mcp. Após a autenticação, uma requisição GET a /mcp ou /main retorna 405 com Allow: POST; o cliente envia mensagens MCP via POST. Se o token estiver ausente ou for inválido, o retorno será 401 antes do encaminhamento. Já uma requisição autenticada a /account retorna 308 para /main. Essas respostas GET não verificam se uma conexão MCP válida via POST funciona. Depois de selecionar o transporte correto, inspecione o erro de conexão do cliente.
A autenticação ou a organização está incorreta #
Para 401, verifique se a conexão concluiu o OAuth com o usuário correto do Lingo.dev. O servidor hospedado exige um token de portador válido de um usuário; uma chave de API pessoal ou de serviço não é aceita em x-api-key nem como valor do token de portador. Deixe o cliente renovar a autorização ou reconecte pelo gerenciamento de contas do cliente. Não inclua tokens nos diagnósticos.
Chame members_listMemberships, escolha a organização desejada em data e informe o ID dela no campo de organização da próxima ferramenta. Para engines_list, esse campo é orgId. Escolher outra organização da mesma lista não exige uma nova autorização OAuth. Reconecte se a conta conectada não for a correta; apenas reiniciar pode reutilizar a sessão salva.
Se o vínculo com a organização aparecer em ssoRequired, entre no Lingo.dev pelo provedor de identidade dessa organização e reconecte. Se data e ssoRequired estiverem vazios, conclua a configuração da organização em https://lingo.dev/orgs/start e consulte os vínculos novamente. Uma organização indisponível pode não existir, estar fora dos vínculos do usuário ou exigir SSO; nem toda resposta desse tipo indica uma credencial expirada.
Se uma ferramenta recusar a operação por falta de permissão ou de direito de acesso, verifique os requisitos da operação em vez de repetir a autenticação. O acesso à organização e a permissão para realizar uma gravação específica são verificações distintas. Explique qual autorização está faltando, sem escolher silenciosamente uma função ou credencial com permissões mais amplas.
Uma ferramenta informa que a configuração da organização está incompleta #
A organização foi criada recentemente, e quem a criou ainda não terminou a configuração no aplicativo web: integrações, colegas de equipe e o primeiro engine. As ferramentas no nível da organização podem ficar bloqueadas até a conclusão da configuração; tentar novamente ou refazer a autorização não conclui essas etapas. members_listMemberships continua disponível. Abra o link da mensagem, https://lingo.dev/orgs/<orgId>, com a conta de quem criou a organização, conclua as etapas indicadas e repita a chamada. Consulte Concluir a configuração de uma nova organização.
A ferramenta rejeita os argumentos #
Compare a entrada com o esquema exato retornado pela conexão. Os argumentos atuais das ferramentas são campos no nível principal, com valores aninhados apenas onde o esquema os declara. Não adicione estruturas de encapsulamento inventadas, como body, params ou query. Informe explicitamente o campo de organização quando exigido; ele não é preenchido automaticamente a partir do token de portador. O campo opcional intent descreve a tarefa. Consulte Capacidades para ver as operações de conta disponíveis.
Verifique o que cada ID identifica. members_remove.id é o ID do vínculo com a organização obtido em members_list; members_setRole.userId identifica o usuário desse vínculo. Um ID de engine de localização não pode substituir um ID de registro de solicitação. Copie exatamente os cursores opacos ou os pares de carimbo de data/hora e ID com precisão total, em vez de reconstruí-los a partir das datas exibidas.
Respeite as distinções do esquema entre valores omitidos e nulos, números e strings, arrays e valores individuais. Verifique o esquema da ferramenta conectada antes de aplicar uma solução alternativa a um erro de argumento.
Uma gravação na conta ou um trabalho tem resultado incerto #
Consulte o recurso relevante ou o estado do trabalho antes de tentar novamente. Um erro de rede pode ocorrer depois que o servidor aceitou a criação de uma chave, um convite, uma decisão de revisão, uma sugestão ou um trabalho. Confirme se a alteração pretendida existe, em vez de enviá-la novamente de forma automática.
Para um trabalho de provisionamento que você enviou, consulte provisioningJobs_get com o ID salvo do trabalho antes de decidir se deve tentar novamente. Para outras operações, inspecione o recurso salvo e o contrato de conclusão da ferramenta conectada. Consulte a referência da CLI ou da API para fluxos de trabalho de tradução.
Faltam documentação ou evidências #
Pesquise com localization_search e passe o path de um resultado para docs_fetch para ler a página completa. Se o caminho não funcionar, pesquise novamente pela tarefa e use um resultado atual. A base de conhecimento usa um caminho de armazenamento separado do site baseado em arquivos, por isso uma página do site pode estar ausente ou desatualizada nesse índice. Consulte a referência atual no site antes de concluir que a funcionalidade está indisponível.
Ao relatar uma lacuna ainda não resolvida no MCP, inclua a tarefa que tentou realizar, o nome exato da ferramenta, a versão do servidor e a resposta sem dados sigilosos. A confirmação de recebimento do relato não garante uma data de correção.
Em uma consulta sobre qualidade, identifique o que está faltando: evidências da fonte, uma avaliação concluída, um critério aplicável ou uma resposta conclusiva. Cada caso exige próximos passos diferentes. Medir explica como relatar as evidências disponíveis sem considerar aprovados os casos sem resposta.