Resolução de problemas com o MCP
Diagnostique problemas de descoberta de ferramentas, autenticação, acesso à organização e argumentos, bem como resultados incertos, antes de tentar novamente.
Parta do sintoma para decidir o que verificar a seguir: se faltar uma ferramenta, verifique a ligação; se uma chamada for rejeitada, analise o erro de argumentos ou de permissões. Guarde o nome da ferramenta, os dados de entrada não confidenciais, a resposta e o recurso ou a revisão da fonte relevante. Estes elementos ajudam a retomar o trabalho pretendido sem repetir uma operação de escrita cujo resultado é desconhecido.
Faltam as ferramentas esperadas #
Compare o ponto de acesso configurado com o inventário devolvido 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 ponto de acesso da 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 ative apenas o que a tarefa exige. Se uma ferramenta que deveria estar disponível não aparecer, guarde os dados do servidor e da versão, bem como os resultados não confidenciais da descoberta, para comunicar o problema.
GET devolve 405 #
Configure Streamable HTTP em /mcp. Após a autenticação, um pedido GET a /mcp ou /main devolve 405 com Allow: POST; o cliente envia mensagens MCP através de POST. Se o token estiver em falta ou for inválido, é devolvido 401 antes do encaminhamento. Por sua vez, um pedido autenticado a /account devolve 308 para /main. Estas respostas GET não permitem verificar se uma ligação MCP válida por POST funciona. Depois de selecionar o transporte correto, analise o erro de ligação do cliente.
A autenticação ou a organização está incorreta #
Para 401, verifique se a ligação concluiu a autenticação OAuth com a conta de utilizador Lingo.dev pretendida. O servidor alojado exige um token bearer de utilizador válido; não aceita uma chave de API pessoal ou de serviço em x-api-key nem como valor bearer. Deixe o cliente renovar a autorização ou volte a estabelecer a ligação através da gestão de contas do cliente. Não inclua tokens nos dados de diagnóstico.
Chame members_listMemberships, escolha a organização pretendida em data e indique o respetivo ID no campo de organização da ferramenta seguinte. Para engines_list, esse campo é orgId. Escolher outra organização da mesma lista não exige uma nova autorização OAuth. Volte a estabelecer a ligação se a pessoa com sessão iniciada não for a correta; reiniciar, por si só, pode reutilizar a sessão guardada.
Se a associação aparecer em ssoRequired, inicie sessão no Lingo.dev através do fornecedor de identidade dessa organização e volte a estabelecer a ligação. Se tanto data como ssoRequired estiverem vazios, conclua a configuração da organização em https://lingo.dev/orgs/start e volte a consultar as associações. Uma organização indisponível pode não existir, não estar entre as organizações de que o utilizador é membro ou exigir SSO; não interprete todas estas respostas como sinal de uma credencial expirada.
Se uma ferramenta recusar uma operação por falta de permissões ou de direitos de utilização, verifique os requisitos da operação em vez de repetir a autenticação. O acesso à organização e a permissão para efetuar uma determinada operação de escrita são verificações distintas. Explique que autorização falta, sem escolher silenciosamente uma função ou credencial com permissões mais abrangentes.
Uma ferramenta indica que a configuração da organização está incompleta #
A organização foi criada recentemente e a pessoa que a criou ainda não concluiu a configuração na aplicação Web: integrações, colegas de equipa e o primeiro motor. As ferramentas ao nível da organização podem ficar bloqueadas até a configuração estar concluída; tentar novamente ou renovar a autorização não conclui esses passos. members_listMemberships continua disponível. Abra a ligação indicada na mensagem, https://lingo.dev/orgs/<orgId>, com a conta de quem criou a organização, conclua os passos indicados e repita a chamada. Consulte Concluir a configuração de uma nova organização.
A ferramenta rejeita argumentos #
Compare os dados de entrada com o esquema exato devolvido pela ligação. Os argumentos atuais das ferramentas são campos de um único nível, com valores aninhados apenas onde o esquema os define. Não acrescente estruturas envolventes inventadas como body, params ou query. Forneça explicitamente o campo de organização quando for obrigatório; este não é preenchido a partir do token bearer. O campo opcional intent descreve a tarefa. Consulte Capacidades para conhecer as operações de conta suportadas.
Verifique o que cada ID identifica. members_remove.id é o ID da associação obtido em members_list; members_setRole.userId identifica o utilizador dessa associação. Um ID de motor de localização não pode substituir um ID de registo de pedidos. Copie exatamente os cursores opacos ou os pares de marca temporal/ID com precisão total, em vez de os reconstruir a partir das datas apresentadas.
Respeite as distinções do esquema entre valores omitidos e nulos, números e cadeias de caracteres, listas e valores individuais. Verifique o esquema da ferramenta ligada antes de aplicar uma solução alternativa a um erro de argumentos.
Uma operação de escrita na conta ou uma tarefa tem um resultado incerto #
Consulte o recurso relevante ou o estado da tarefa antes de tentar novamente. Pode ocorrer um erro de rede depois de o servidor ter aceite a criação de uma chave, um convite, uma decisão de revisão, uma sugestão ou uma tarefa. Confirme se a alteração pretendida existe, em vez de a submeter novamente de forma automática.
Se submeteu uma tarefa de aprovisionamento, consulte provisioningJobs_get com o ID da tarefa guardado antes de decidir se deve tentar novamente. Para outras operações, verifique o recurso guardado e as condições de conclusão da ferramenta ligada. Consulte a referência da CLI ou da API para os fluxos de trabalho de tradução.
Documentação ou elementos de prova em falta #
Pesquise com localization_search e, em seguida, passe o path de um resultado a docs_fetch para ler a página completa. Se o caminho não funcionar, volte a pesquisar a tarefa e use um resultado atual. A base de conhecimento usa um caminho de armazenamento diferente do site baseado em ficheiros, pelo que uma página do site pode estar ausente ou desatualizada nesse índice. Consulte a referência atual do site antes de concluir que a capacidade está indisponível.
Ao comunicar uma lacuna do MCP ainda por resolver, inclua a tarefa que tentou executar, o nome exato da ferramenta, a versão do servidor e a resposta sem dados confidenciais. A confirmação de receção da comunicação não garante uma data de correção.
Numa questão sobre qualidade, identifique o que falta: elementos de prova da fonte, uma avaliação concluída, um critério aplicável ou uma resposta conclusiva. Cada caso exige passos seguintes diferentes. Medição explica como comunicar os elementos de prova disponíveis sem considerar aprovados os casos sem resposta.