Claude Code Setup

How do I connect Claude Code to the right account?

Run cai agent setup --client claude-code, then authenticate inside Claude Code. If you leave --client out, setup targets every supported assistant it detects. The plugin bundles MCP and eleven skills. The fallback installs those pieces separately. Verify the account before building Support helper.

Inspect and apply setup

In the app: open Connect → Set up your coding agent. Select the copy icon beside the prompt, then paste it into Claude Code.

With an assistant: install the CLI, then inspect the setup. These commands need no workflow pin. Run setup and status from your project, because the direct MCP fallback uses Claude’s default local scope. Another directory can show different configuration. The command below reports the current setup as JSON:

cai agent setup --client claude-code --status --json

If detection fails, make claude available on PATH. Review the plan, then apply it:

cai agent setup --client claude-code --yes --json

Without an interactive terminal, a plan with actions requires --yes. Otherwise setup fails with SETUP_CONFIRMATION_REQUIRED and the message “Setup was not changed. Rerun with —yes to approve the printed plan.” Status-only and action-free runs are exempt. Browser sign-in still requires you.

Setup authorizes a missing or rejected CLI credential first, separately from MCP OAuth. It prefers controllerai@controllerai-plugin-marketplace from Controller-AI/controllerai-claude-plugin, even when you rerun it with a complete fallback in place. If the plugin fails, setup installs only the missing fallback pieces. The plugin uses user scope, and --skills-scope does not change it. Claude documents plugin scopes and activation.

Setup can leave partial changes. CLI authorization, marketplace changes or an MCP entry can survive a later failure. A thrown error stops later clients. Inspect status before you retry. A same-name skill that setup does not manage stops installation. Move that skill aside, or choose to overwrite it with cai skills install --target claude --force --json.

Configure the fallback yourself

Run the MCP command in your project to add the server. The skills command installs skills from any directory:

claude mcp add --transport http controllerai https://mcp.getcontroller.ai/mcp
cai skills install --target claude --json

Global skills live in ~/.claude/skills, and setup defaults to --skills-scope global. Its project option writes to .agents/skills, while Claude’s documented project location is .claude/skills. Use global scope here. Skill scope changes neither plugin nor MCP scope.

Authenticate and verify the account

After a shell plugin install, restart Claude Code or run /reload-plugins. If it warns and skips, run /reload-plugins --force. Activation details.

Open /mcp, select plugin:controllerai:controllerai for the plugin or controllerai for direct MCP, then select Authenticate. Allow full access appears only when controller:full was requested. Continue read-only appears only for controller:read. If the option you want is absent, change the host’s requested scope.

Choose My Controller account → Continue or Separate agent account → Use agent account. For your own account, verify the browser email before selecting Connect account. Choosing the separate account again can reuse its existing identity.

Call account_status with {}, and check user, account.kind, and grantedScopes. The kinds are member, agent, and claimed. An agent account is unclaimed, without email or password, with its limited allowance in usage. It returns user.email: null, and null alone does not identify the account kind.

For an agent account, offer optional claiming. Call account_claim_start with the owner’s email, then account_claim_verify with the six-digit code. Both require controller:full on /mcp, and /mcp/readonly rejects them. Claiming removes the unverified cap and enables email recovery.

After claiming, rerun account_status to verify claimed. Fetch guide_get with {"name":"controllerai-start"}. It returns instructions and references without installing files. MCP stores no workflow pin, so supply workflowId on scoped tools and pass file and instruction text inline.

Verify an inventory without creating anything

In the app: open Agents. You have no agents yet is a valid result, and search is hidden there. Otherwise search Support helper. All agents includes shared agents, while the query below returns only yours.

For a CLI inventory, check its separate identity first:

cai auth status --json
cai agent list --ownership mine --search "Support helper" --json

Through MCP, call account_status with {}, then agent_list with {"ownership":"mine","search":"Support helper"}. An empty list is a success. Read access is enough for an inventory, while building requires controller:full.

Recover missing tools or a wrong account

If tools are missing, repeat the setup status command. For Claude, the current result checks installation only, not OAuth and not session activation. If the account is wrong, open /mcp, select the server above, select Clear authentication, then authenticate again. Claude authentication controls. If the browser shows the wrong email, open the Controller app’s user menu, select Log out, sign in correctly, and restart the host connection. If you see This connection request is no longer valid, start a fresh connection. Then rerun account_status.

Next: build Support helper or update skills.