Installation and access

Sign in with Google at Setup. The Google action opens a popup directly; after sign-in, the original page continues to Setup with the selected example. Existing email/GitHub users retain existing account access. Teams are outside this flow.

Create an agent key

Choose your agent in Setup and select Connect. Review and send the prefilled setup request in your agent; it imports a private Tools-only key securely. Generic setup connects first and then asks for a task; an example includes the chosen task and asks for its missing inputs.

Install uv, then install or update the SDK:

uv tool install --upgrade --python 3.14 "recurse-sdk>=0.2.8"
recurse tools --help

The SDK requires Python 3.14 or newer. This command selects Python 3.14 for its isolated CLI environment; uv can download it if needed. Keep the Python selector and minimum SDK version so an older system interpreter cannot select an obsolete SDK.

Use SDK 0.2.8 or later. The key-import command is recurse tools login --key-stdin; provide the key through process stdin. For a manual hidden-input import:

python -c 'import getpass, subprocess; subprocess.run(["recurse", "tools", "login", "--key-stdin"], input=getpass.getpass("Recurse access key: "), text=True, check=True)'

Never put a key in command arguments, environment variables, source files, MCP settings or logs. The SDK verifies it and saves it in the operating-system keychain. It renews scoped short-lived access automatically; the raw key is not an API bearer. Stop if a keychain is unavailable rather than saving credentials in plaintext.

Connect and verify

codex mcp add recurse-tools -- recurse tools mcp serve
recurse tools apis search "web search" --limit 3

If the Recurse plugin already provides the bridge, verify that single connection rather than adding another. Read the canonical Tools skill. The root /SKILL.md is a Tools alias. Existing hosted-agent guidance is separately named Recurse Agents; verify that replacement before disabling an older agent-authoring skill named recurse. Do not install both Tools aliases as separate skills.

Successful discovery verifies connection, not paid execution. Agree a task and total spending cap before preparation. Continue with Run private Python.

TEST and production

Production is the default. For TEST, set both origins before import and pass them into the actual MCP process (Codex filters ambient shell variables):

export RECURSE_API_URL=https://api.dev.recurse.run
export RECURSE_TOOLS_URL=https://tools.dev.recurse.run
codex mcp add recurse-tools --env RECURSE_API_URL=https://api.dev.recurse.run --env RECURSE_TOOLS_URL=https://tools.dev.recurse.run -- recurse tools mcp serve

Never send a TEST key to production. Key/cache identities are partitioned by these origins. recurse tools logout revokes the imported Tools key; issued bearers may last up to one hour. Other keys and the separate hosted-agent login remain independent. Browser sign-out does not revoke those connections. The existing hosted-agent path still uses its own account login and agent instructions.