Let your coding agent set up Uclusion

Bootstrap a temporary Uclusion MCP, approve one browser authorization, and let your coding agent create and connect a workspace without seeing secrets.

Uclusion can be set up from an existing Claude Code, Cursor, or Codex conversation. Your agent proposes the small amount of configuration it can infer, a temporary local MCP creates the workspace, and the normal Uclusion MCP replaces it when setup finishes.

The browser is used only for Uclusion authentication and approval. Passwords, OAuth results, the Uclusion secret, and setup proof never need to be pasted into chat or a shell command.

Before you start

You need Python 3 and one supported coding client. Ask the agent to show and confirm all of these values before it changes client configuration:

  • a short workspace name;
  • Claude Code, Cursor, or Codex;
  • a global install or an install for the current project;
  • token usage notes for Claude Code or Codex, off unless requested (Cursor does not support them); and
  • work claims, off unless requested.

Advanced choices can be changed later.

The selected global or project scope must not already contain a Uclusion MCP registration. The bootstrap stops instead of replacing an existing setup. Use the normal MCP instructions to inspect or update an existing connection.

Only one agent-led setup can be active on a machine for the selected Uclusion environment. Finish or abandon that attempt before starting another one; the shared account credential is intentionally machine-wide.

If that environment already has a valid credential for a different Uclusion account, setup stops without replacing it. A malformed existing credential also stops setup so the original file can be inspected or recovered deliberately.

Bootstrap the setup MCP

After confirming the client and scope, the agent runs the public installer. A global Codex example is:

curl -fsSL https://production.uclusion.com/scripts/install.sh | bash -s -- setup --clients codex

For the current project, append --project. Substitute claude or cursor for another client. The command contains no workspace ID, account identity, authorization code, or secret.

The bootstrap installs a temporary Uclusion server exposing only create_workspace and complete_setup. Restart the coding client or reconnect its Uclusion MCP server so those tools become available. Codex setup starts in ordinary Codex; uclusion codex is used after a workspace exists.

Authorize and create the workspace

The agent calls create_workspace with the values you confirmed. The tool opens a Uclusion URL when possible and always returns that same public URL for headless or remote environments.

At Uclusion:

  1. Sign in or create an account with Google, GitHub, or email.
  2. Review the exact workspace name, coding client, install scope, and setup defaults.
  3. Choose Approve or Deny.

The URL contains only an opaque setup ID. The proof that can complete setup stays in the running local setup MCP’s memory. Authorization expires after 15 minutes.

After approval, the agent calls complete_setup. Pending approval returns a safe retryable status. Completion creates the workspace once, stores the existing Uclusion secret through the normal local credentials contract, writes the workspace configuration, and replaces the temporary server with the normal Uclusion MCP. Neither tool returns a secret to the agent.

The completion result announces the created workspace and links to it at the environment-correct Uclusion URL. Fully exit the setup client and relaunch it from the configured scope so the newly installed resident instructions load; reconnecting only the MCP server is insufficient. For production Codex, start the connected session with:

uclusion codex

For another environment, include it before the subcommand, for example uclusion -e stage codex. In the fresh client session, type Go to start the first normal turn. The installed instructions call find_work; when its directions explicitly identify the first AI session and say they are served only once, the agent follows that onboarding immediately in the same turn before yielding. On an ordinary later empty list, the agent instead asks exactly: “Your find work list is empty—would you like instructions for adding and working on a job?”

Secrets and revocation

Agent-led setup keeps the existing Uclusion credential model. One long-lived Uclusion secret is shared by installations for that account. The existing Integrations control can revoke and generate a new secret; doing so disconnects every machine using the previous value.

The setup ID and its proof are separate and temporary. The proof is never written to disk. If the setup MCP or coding client exits during browser authorization, or before it has durably written both the normal credential and an IDs-only receipt, that attempt cannot be recovered: run the bootstrap/setup flow again and approve the new URL. The abandoned request expires automatically.

Once those private local writes succeed, provisioning can be resumed without persisting the proof—even if the acknowledgement was interrupted. The receipt contains only the setup, workspace, and view IDs; the normal Uclusion credential is stored separately. The receipt is removed after activation finishes. If that final cleanup is interrupted, the setup-installed normal MCP launcher validates and removes the matching receipt when the normal server next starts. A resumed activation applies the exact token-usage-note and work-claim choices that were approved in the browser.

Troubleshooting

  • The setup tools are missing: restart the client or reconnect the Uclusion MCP after running the bootstrap command.
  • The authorization page expired: start a new setup to receive a new 15-minute URL.
  • The browser did not open: use the trusted URL returned by create_workspace.
  • Setup stopped after browser approval: call complete_setup again. If the setup process restarted before it wrote its IDs-only receipt, begin a new setup. If the setup tools are still registered and retained a receipt, retry complete_setup with that setup ID so the normal credential can authenticate recovery. If the normal MCP is already registered, perform the final full client relaunch instead; its setup-installed launcher validates and cleans the matching receipt before starting the ordinary server.
  • The bootstrap reports an existing Uclusion registration: keep that registration and use the normal MCP update flow, or deliberately remove it before starting a new-account setup. The setup bootstrap never overwrites it.
  • Setup reports a credential for another account or a malformed credential: the existing credential was left unchanged. Resolve which account this machine should use before retrying setup.
  • Normal tools are missing after completion: perform the final full client relaunch from the configured scope; this also retries safe receipt cleanup if activation was interrupted. Codex users should launch the environment-correct command, such as uclusion codex or uclusion -e stage codex.
  • You prefer manual setup: the existing authenticated Connect AI first and MCP & CLI Integrations flows remain supported.

See Model Context Protocol for normal MCP, client configuration, updates, token usage notes, and work claims after setup.