Fix an MCP server that cannot start or solve a task

Run the supplied launcher in a terminal on the machine that runs your MCP host. For a controlled reproduction, use Node.js 22 and its bundled npx; check that you're not picking up an older, separately installed launcher.

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.

A process that stays open without printing anything hasn't necessarily stalled. This is a local stdio server: it waits for MCP JSON-RPC messages on stdin. Use your MCP host to initialize the connection and list tools; running the executable alone doesn't perform that handshake.

If it exits, read the launch error first. An executable-not-found error points to installation or PATH; a package download error happens before task solving. Neither is evidence of a bad API key, proxy or site profile.

Register solvethree as a local stdio server, not a remote HTTP endpoint. The host should run npx with the arguments shown in the launcher example. There is no hosted MCP endpoint.

The host cannot find npx.

Compare the host's PATH with your terminal's PATH. A desktop application may not inherit your shell setup.

Try this: Make the directory containing npx available to the host, or configure the absolute path to the same executable that worked locally.

The host runs a different Node.js or npx version.

Check which executables the host resolves, not just which versions your terminal uses.

Try this: Point the host at the tested installation. Restart the host after changing its environment.

Initialization reports malformed JSON or unexpected output.

Look for shell banners, wrapper messages or debug prints written to stdout.

Try this: Keep stdout reserved for MCP JSON-RPC. Send diagnostic output to stderr, where the host can collect it without treating it as protocol traffic.

The host stops waiting during startup.

Inspect the startup log and distinguish a slow launch from a process that has already exited.

Try this: For Codex-style configuration, use the documented startup_timeout_sec value of 60. A longer wait won't repair a missing executable or an explicit launch error.

The host says a solvethree tool is not registered.

Confirm that the server initialized and inspect the tools returned by discovery.

Try this: Correct the server registration or reconnect and discover tools again. A missing tool is not an API authentication error or a failed solve.

The server exposes solvethree_capabilities, solvethree_create_recaptcha, solvethree_create_kasada, solvethree_create_tmpt and solvethree_get_task. If discovery succeeds but the host can't call one of these names, resolve that mismatch before sending task requests.

1. 1.

   Check the environment of the host process

   Provide SOLVETHREE_API_KEY and SOLVETHREE_PROXY through the host environment. A variable exported in a separate terminal doesn't establish that the host can read it. In Codex-style configuration, env_vars must include both names; that pass-through list doesn't supply their values. Check presence without printing the key or proxy credentials.

2. 2.

   Check the proxy where the tool actually reads it

   solvethree_create_recaptcha reads its single proxy from SOLVETHREE_PROXY. Don't try to fix a missing environment value by adding a proxy argument to that tool. The proxy URL should use HTTP or HTTPS and have no path, query or fragment.

3. 3.

   Check the reCAPTCHA site profile

   The workspace identified by the API key needs an active profile for the requested site and reCAPTCHA type. Check the capture action too: one generic hostname profile doesn't necessarily resolve every action. Supplying site and action in a task does not create a profile. Use the console's Site profiles page or the profile setup guide to resolve this.

4. 4.

   Check the tool's inputs

   For solvethree_create_recaptcha, supply site as a hostname, action and requestId. recaptchaType is optional and defaults to enterprise-v3. Don't substitute a page URL for site or add the API's other task types to this tool.

Capability discovery doesn't test authentication or proxy access. An authentication or request-validation error after a successful capabilities call belongs to the solving request, not the launcher. Handle non-success HTTP responses before treating a response as a successful task payload.

A host timeout isn't a task status. Codex-style configuration uses tool_timeout_sec of 100, but losing the response still doesn't prove task creation failed. Each create tool requires requestId and creates at most one task.

If you received a task ID, retrieve that task. Otherwise, repeat the same create request with the same requestId to recover the existing task. Don't generate a new requestId just because the call timed out. Reusing an ID with changed task inputs conflicts.

When a task is ready, submit its solution with the returned browser identity and the successful proxy. If the website then rejects the request, investigate that submission rather than MCP startup. Keep solution data private: the MCP host receives it.