Add solvethree MCP to Codex

1. 1.

   Make Node.js 22 and npx available

   They must be available to the process running Codex. Installing them in a separate environment that Codex can’t access won’t let it start the server.

2. 2.

   Set the host environment variables

   Set SOLVETHREE_API_KEY to your workspace API key and SOLVETHREE_PROXY to the proxy URL. Start Codex with those variables available. For the IDE integration, make sure the IDE process inherits them too. Keep the API key out of prompts and source control.

3. 3.

   Activate the reCAPTCHA site profile

   In Site profiles, add the HTTPS page URL, select the reCAPTCHA type, and supply the capture action. Wait until the profile is active. Configure the hostname, capture action, and type you need; a task’s site and action don’t create a profile. See site profile setup if this is your first target.

Codex CLI and IDE share ~/.codex/config.toml. You can also use a trusted project’s .codex/config.toml. Add this server entry:

[mcp_servers.solvethree]
command = "npx"
args = ["--yes", "--package=https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz", "solvethree-mcp"]
env_vars = ["SOLVETHREE_API_KEY", "SOLVETHREE_PROXY"]
startup_timeout_sec = 60
tool_timeout_sec = 100

The entry runs the official SDK’s solvethree-mcp executable through npx. env_vars forwards existing host variables; it doesn’t assign their values. There’s no hosted MCP endpoint to enter and no OAuth login for this local server.

startup_timeout_sec allows 60 seconds for server startup. tool_timeout_sec allows 100 seconds for a tool call. Neither setting means the target website has accepted a solution.

Run codex mcp list, or open /mcp in the Codex TUI, to inspect the configured server. If it can’t start, check that Codex can find npx and has inherited both environment variables.

1. 1.

   Inspect capabilities

   Have Codex call solvethree_capabilities before choosing the solve tool. For reCAPTCHA, use solvethree_create_recaptcha.

2. 2.

   Provide the reCAPTCHA inputs

   Supply site as the hostname, action, and a requestId. The tool also accepts optional recaptchaType and waitMs; the default type is enterprise-v3. It reads its single proxy from SOLVETHREE_PROXY, so don’t treat it as a per-call proxy setting. Don’t add type or url fields to the reCAPTCHA request.

3. 3.

   Keep the task ID and check its status

   Each create call makes at most one task. Retrieve that task with solvethree_get_task using its returned ID. Continue checking while its status is pending or solving. Only ready contains a usable solution. If it becomes failed, stop polling and inspect errorCode and error before deciding what to change.

The MCP server doesn’t drive a browser, inspect its current session, or fill forms. Your application must take the ready reCAPTCHA result and submit solution.token to the intended target.

Use the returned userAgent and secChUa browser identity with the same proxy used for the solve. If your browser or HTTP client uses a different proxy or unrelated browser identity, fix that before submission. Adding the MCP server doesn’t configure those settings for you.

Codex receives private solution data through the tool response, so keep it out of shared reports and logs. A ready task means a solution was generated; check the target’s response separately to determine whether it accepted the application request.