MCP ligado mas não funciona? Diagnostica cada etapa no Mono
Distingue falhas de transporte, autorização, descoberta, modelo e chamada de ferramentas no Mono e confirma uma operação sem alterações.
Um servidor MCP guardado não quer dizer que a ferramenta funciona. O endereço pode estar certo e o início de sessão ainda não ter terminado. O início de sessão pode funcionar e as ferramentas do servidor não carregarem. E uma ferramenta pode carregar e mesmo assim receber um pedido errado. Encontra o primeiro passo que falha antes de mudares qualquer definição.
Este guia trata da resolução de problemas no Mono da Reunified, que ainda não está disponível (adere à lista de espera). Para uma primeira ligação, usa o guia de configuração MCP. Aqui o objetivo é transformar um vago «não funciona» numa observação clara que possas repetir, sem repetires por engano uma escrita.
1. Regista o sintoma e interrompe repetições incertas
Anota o nome do servidor, o transporte, o dispositivo, a versão da app, o que estavas a tentar fazer e o erro exato, sem segredos. Indica se a mesma configuração funcionava antes e o que mudou desde então. «A lista de ferramentas fica vazia depois de iniciar sessão» é mais útil do que «o MCP está avariado».
Se o último pedido podia criar, enviar ou atualizar alguma coisa, verifica o destino antes de tentares de novo. Uma resposta perdida não quer dizer que a ação não aconteceu. Para testar, passa a um pedido pequeno só de leitura, como listar um item num projeto de teste que consigas verificar.
Guarda em privado uma cópia das últimas definições que funcionavam. Não coles tokens, códigos de autorização nem resultados privados de ferramentas num pedido de apoio público.
2. Verifica o transporte antes da conta
Uma ligação HTTP no Mono precisa do endereço de um servidor MCP, não de uma página inicial normal nem do endereço da API de um modelo. Compara o URL completo, incluindo o caminho, com a documentação atual de quem publica o servidor. Uma página que abre no navegador só mostra que essa página está acessível, não que o MCP funciona lá.
Com Entrada/saída padrão (stdio), verifica o comando e os argumentos no dispositivo que os tem de iniciar. Voltar a iniciar sessão não resolve um comando em falta nem um dispositivo que não o consegue executar. Telemóveis e computadores são diferentes, por isso não esperes que um comando de computador corra num telemóvel.
Um endereço com localhost aponta para o dispositivo que faz o pedido. Testa a partir do dispositivo real, por um caminho suportado e com sessão iniciada. Não enfraqueças os controlos de acesso de um servidor que funciona só para um teste passar.
3. Separa configurações guardadas de autorização concluída
Verifica que método de autenticação escolheste. Um Token Bearer precisa do token certo do serviço no respetivo campo. O OAuth precisa da conta certa, dos requisitos do servidor e de um regresso completo ao Mono; fechar o navegador antes do tempo não é um início de sessão bem-sucedido.
O Mono pode guardar um servidor antes de o início de sessão terminar, por isso um servidor guardado não prova que o início de sessão funcionou. Mesmo depois de um início de sessão bem-sucedido, o carregamento das ferramentas pode falhar durante algum tempo. Nem uma entrada guardada nem uma mensagem «Conectado a» provam que uma ferramenta concreta está pronta.
Se mudares o URL ou o transporte do servidor, o Mono trata-o como uma ligação nova, por isso podes ter de voltar a iniciar sessão. Corrige um erro real de endereço, mas não mudes vezes sem conta um URL que funciona como se fosse uma reposição geral. Segue as definições de cliente e de redirecionamento documentadas por quem publica o servidor em vez de adivinhares valores.
4. Verifica capacidades e modelo selecionado
A arquitetura MCP distingue ferramentas, recursos e prompts. Um servidor pode oferecer só alguns, por isso um servidor que só oferece recursos não dá ao assistente nenhuma ferramenta para chamar.
Numa competência MCP instalada, abre a secção Configuração para ver as ferramentas que o Mono encontrou. Se estiver vazia, verifica o início de sessão e se o servidor lista as suas ferramentas; não assumas que todas as ações do serviço estão disponíveis. Guardar um servidor não é uma verificação completa do seu estado.
Verifica também o modelo usado na conversa. Nem todos os modelos conseguem chamar ferramentas, incluindo alguns que ligas tu mesmo. Um modelo que responde bem em texto pode ser, ainda assim, a razão pela qual uma ferramenta ligada nunca é usada. O guia de endpoints personalizados explica isto.
5. Testa uma operação conhecida
Usa um pedido inofensivo e compara o resultado com o serviço original:
Lê o título do elemento de demonstração existente que eu identificar.
Não cries, edites, envies nem elimines nada.
Se o acesso falhar, indica a falha em vez de adivinhar o título.| O que vês | Próxima verificação |
|---|---|
| Não liga ao endereço | Endereço, transporte, rede do dispositivo e se o servidor está ativo |
| O início de sessão não termina | Conta, método de autenticação e requisitos OAuth de quem publica o servidor |
| Não aparecem ferramentas | O que o servidor oferece, se as ferramentas carregaram e se o modelo suporta ferramentas |
| Uma ferramenta falha | Dados necessários, permissões do serviço e erro devolvido |
| A leitura funciona, a escrita é bloqueada | O acesso que querias dar e a permissão da ferramenta; não abras tudo |
O erro próprio de uma ferramenta é diferente de um resultado vazio mas bem-sucedido. Guarda juntos o estado devolvido e o texto relevante, sem segredos.
6. Confirma a correção e guarda um registo
Muda uma coisa de cada vez, repete o mesmo teste só de leitura e anota o resultado. Se mais tarde precisares de uma escrita, verifica o destino exato e confirma o resultado no serviço antes de nova tentativa.
Guarda uma nota curta com o passo que falha, as versões, a alteração feita e o último teste bem-sucedido. Remover uma ligação no Mono e revogar o acesso no fornecedor são passos separados. Para decisões de permissões durante a utilização, lê o guia de permissões de ferramentas; aprovar pedidos vezes sem conta não resolve uma ligação.
