Corrija um servidor MCP que não consegue iniciar ou resolver uma tarefa

Execute o inicializador fornecido em um terminal na máquina que executa seu host MCP. Para uma reprodução controlada, use Node.js 22 e o npx incluído nele; verifique se você não está usando um inicializador mais antigo, instalado separadamente.

node --version
npx --yes --package=https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz solvethree-mcp
# The process waits for JSON-RPC on stdin. Silence is not a failed startup.
# Use the MCP host to initialize and list tools. Press Ctrl-C to stop this check.
# Never paste an API key or proxy password into troubleshooting logs.

Um processo que permanece aberto sem exibir nada não está necessariamente travado. Este é um servidor stdio local: ele aguarda mensagens MCP JSON-RPC em stdin. Use seu host MCP para inicializar a conexão e listar as ferramentas; executar apenas o executável não realiza esse handshake.

Se ele encerrar, leia primeiro o erro de inicialização. Um erro de executável não encontrado aponta para a instalação ou o PATH; um erro de download do pacote ocorre antes da resolução de tarefas. Nenhum dos dois indica uma chave de API, um proxy ou um perfil de site inválido.

Registre o solvethree como um servidor stdio local, não como um endpoint HTTP remoto. O host deve executar npx com os argumentos mostrados no exemplo do inicializador. Não há um endpoint MCP hospedado.

O host não encontra npx.

Compare o PATH do host com o PATH do seu terminal. Um aplicativo de desktop pode não herdar a configuração do seu shell.

Experimente: Disponibilize para o host o diretório que contém npx ou configure o caminho absoluto para o mesmo executável que funcionou localmente.

O host executa uma versão diferente de Node.js ou npx.

Verifique quais executáveis o host encontra, não apenas quais versões seu terminal usa.

Experimente: Configure o host para usar a instalação testada. Reinicie o host após alterar seu ambiente.

A inicialização informa JSON malformado ou saída inesperada.

Procure mensagens de abertura do shell, mensagens de wrappers ou impressões de depuração gravadas em stdout.

Experimente: Mantenha stdout reservado para MCP JSON-RPC. Envie a saída de diagnóstico para stderr, onde o host pode coletá-la sem tratá-la como tráfego do protocolo.

O host para de aguardar durante a inicialização.

Inspecione o log de inicialização e diferencie uma inicialização lenta de um processo que já encerrou.

Experimente: Para uma configuração no estilo do Codex, use o valor documentado de 60 para startup_timeout_sec. Uma espera maior não corrige um executável ausente nem um erro explícito de inicialização.

O host informa que uma ferramenta do solvethree não está registrada.

Confirme que o servidor foi inicializado e inspecione as ferramentas retornadas pela descoberta.

Experimente: Corrija o registro do servidor ou reconecte e execute a descoberta de ferramentas novamente. Uma ferramenta ausente não é um erro de autenticação da API nem uma falha de resolução.

O servidor disponibiliza solvethree_capabilities, solvethree_create_recaptcha, solvethree_create_kasada, solvethree_create_tmpt e solvethree_get_task. Se a descoberta funcionar, mas o host não conseguir chamar um desses nomes, resolva essa incompatibilidade antes de enviar solicitações de tarefas.

1. 1.

   Verifique o ambiente do processo do host

   Forneça SOLVETHREE_API_KEY e SOLVETHREE_PROXY pelo ambiente do host. Uma variável exportada em outro terminal não garante que o host consiga lê-la. Em uma configuração no estilo Codex, env_vars deve incluir ambos os nomes; essa lista de repasse não fornece os valores. Verifique a presença das variáveis sem imprimir a chave nem as credenciais do proxy.

2. 2.

   Verifique o proxy onde a ferramenta realmente o lê

   solvethree_create_recaptcha lê seu único proxy de SOLVETHREE_PROXY. Não tente corrigir um valor ausente no ambiente adicionando um argumento proxy a essa ferramenta. A URL do proxy deve usar HTTP ou HTTPS e não ter caminho, consulta nem fragmento.

3. 3.

   Verifique o perfil do site para reCAPTCHA

   O workspace identificado pela chave de API precisa de um perfil ativo para o site e o tipo de reCAPTCHA solicitados. Verifique também a ação de captura: um perfil genérico de hostname não necessariamente resolve todas as ações. Fornecer site e action em uma tarefa não cria um perfil. Use a página Perfis de sites do console ou o guia de configuração de perfis para resolver isso.

4. 4.

   Verifique as entradas da ferramenta

   Para solvethree_create_recaptcha, forneça site como um hostname, action e requestId. recaptchaType é opcional e tem enterprise-v3 como padrão. Não substitua site por uma URL de página nem adicione os outros tipos de tarefa da API a essa ferramenta.

A descoberta de recursos não testa a autenticação nem o acesso ao proxy. Um erro de autenticação ou de validação da requisição após uma chamada de recursos bem-sucedida está relacionado à requisição de resolução, não ao inicializador. Trate as respostas HTTP sem sucesso antes de considerar uma resposta como um payload de tarefa bem-sucedida.

Um tempo limite excedido no host não é um status de tarefa. A configuração no estilo Codex usa tool_timeout_sec de 100, mas a perda da resposta ainda não prova que a criação da tarefa falhou. Cada ferramenta de criação exige requestId e cria no máximo uma tarefa.

Se você recebeu um ID de tarefa, consulte essa tarefa. Caso contrário, repita a mesma requisição de criação com o mesmo requestId para recuperar a tarefa existente. Não gere um novo requestId só porque a chamada excedeu o tempo limite. Reutilizar um ID com entradas de tarefa alteradas gera conflito.

Quando uma tarefa estiver pronta, envie sua solução com a identidade de navegador retornada e o proxy bem-sucedido. Se o site rejeitar a requisição, investigue esse envio em vez da inicialização do MCP. Mantenha os dados da solução privados: o host MCP os recebe.