Soluciona problemas de un servidor MCP que no puede iniciarse o resolver una tarea

Ejecuta el lanzador proporcionado en una terminal de la máquina donde se ejecuta tu host MCP. Para reproducir el problema de forma controlada, usa Node.js 22 y su npx incluido; comprueba que no se esté usando un lanzador más antiguo instalado por separado.

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.

Un proceso que permanece abierto sin imprimir nada no se ha bloqueado necesariamente. Este es un servidor stdio local: espera mensajes MCP JSON-RPC en stdin. Usa tu host MCP para inicializar la conexión y enumerar las herramientas; ejecutar el programa por sí solo no realiza ese intercambio inicial.

Si termina, lee primero el error de inicio. Un error de ejecutable no encontrado apunta a la instalación o a PATH; un error de descarga del paquete ocurre antes de la resolución de tareas. Ninguno demuestra que la clave de API, el proxy o el perfil de sitio sean incorrectos.

Registra solvethree como servidor stdio local, no como endpoint HTTP remoto. El host debe ejecutar npx con los argumentos que se muestran en el ejemplo del lanzador. No hay ningún endpoint MCP alojado.

El host no encuentra npx.

Compara el PATH del host con el PATH de tu terminal. Una aplicación de escritorio puede no heredar la configuración de tu shell.

Prueba esto: Haz que el directorio que contiene npx esté disponible para el host, o configura la ruta absoluta al mismo ejecutable que funcionó localmente.

El host ejecuta una versión diferente de Node.js o npx.

Comprueba qué ejecutables encuentra el host, no solo qué versiones usa tu terminal.

Prueba esto: Configura el host para usar la instalación probada. Reinicia el host después de cambiar su entorno.

La inicialización informa de JSON mal formado o de una salida inesperada.

Busca mensajes de bienvenida del shell, mensajes de scripts envoltorio o impresiones de depuración escritos en stdout.

Prueba esto: Reserva stdout para MCP JSON-RPC. Envía la salida de diagnóstico a stderr, donde el host puede recogerla sin tratarla como tráfico del protocolo.

El host deja de esperar durante el inicio.

Examina el registro de inicio y distingue entre un inicio lento y un proceso que ya ha terminado.

Prueba esto: Para una configuración de estilo Codex, usa el valor documentado de startup_timeout_sec de 60. Esperar más no solucionará la ausencia de un ejecutable ni un error de inicio explícito.

El host indica que una herramienta de solvethree no está registrada.

Confirma que el servidor se haya inicializado y examina las herramientas devueltas por el descubrimiento.

Prueba esto: Corrige el registro del servidor o vuelve a conectarte y a descubrir las herramientas. La ausencia de una herramienta no es un error de autenticación de la API ni una resolución fallida.

El servidor ofrece solvethree_capabilities, solvethree_create_recaptcha, solvethree_create_kasada, solvethree_create_tmpt y solvethree_get_task. Si el descubrimiento funciona, pero el host no puede invocar uno de estos nombres, resuelve esa discrepancia antes de enviar solicitudes de tareas.

1. 1.

   Comprueba el entorno del proceso del host

   Proporciona SOLVETHREE_API_KEY y SOLVETHREE_PROXY a través del entorno del host. Exportar una variable en otro terminal no garantiza que el host pueda leerla. En una configuración de estilo Codex, env_vars debe incluir ambos nombres; esa lista de variables que se transmiten no proporciona sus valores. Comprueba que estén presentes sin imprimir la clave ni las credenciales del proxy.

2. 2.

   Comprueba el proxy donde realmente lo lee la herramienta

   solvethree_create_recaptcha lee su único proxy de SOLVETHREE_PROXY. No intentes corregir la ausencia de un valor de entorno añadiendo un argumento proxy a esa herramienta. La URL del proxy debe usar HTTP o HTTPS y no tener ruta, consulta ni fragmento.

3. 3.

   Comprueba el perfil del sitio de reCAPTCHA

   El espacio de trabajo identificado por la clave de API necesita un perfil activo para el sitio y el tipo de reCAPTCHA solicitados. Comprueba también la acción de captura: un perfil genérico de nombre de host no resuelve necesariamente todas las acciones. Proporcionar site y action en una tarea no crea un perfil. Usa la página Perfiles de sitio de la consola o la guía de configuración de perfiles para resolverlo.

4. 4.

   Comprueba los parámetros de entrada de la herramienta

   Para solvethree_create_recaptcha, proporciona site como nombre de host, action y requestId. recaptchaType es opcional y su valor predeterminado es enterprise-v3. No sustituyas site por la URL de una página ni añadas a esta herramienta otros tipos de tarea de la API.

El descubrimiento de capacidades no comprueba la autenticación ni el acceso al proxy. Un error de autenticación o de validación de la solicitud tras una llamada correcta de capacidades corresponde a la solicitud de resolución, no al lanzador. Gestiona las respuestas HTTP que no indiquen éxito antes de tratar una respuesta como datos de una tarea correcta.

Un tiempo de espera agotado en el host no es un estado de tarea. La configuración de estilo Codex usa tool_timeout_sec con un valor de 100, pero perder la respuesta tampoco demuestra que la creación de la tarea haya fallado. Cada herramienta de creación requiere requestId y crea como máximo una tarea.

Si recibiste un ID de tarea, recupera esa tarea. De lo contrario, repite la misma solicitud de creación con el mismo requestId para recuperar la tarea existente. No generes un requestId nuevo solo porque se haya agotado el tiempo de espera de la llamada. Reutilizar un ID con parámetros de entrada distintos genera un conflicto.

Cuando una tarea esté lista, envía su solución con la identidad del navegador devuelta y el proxy que funcionó. Si el sitio web rechaza después la solicitud, investiga ese envío en lugar del inicio de MCP. Mantén privados los datos de la solución: el host MCP los recibe.