# One-shot MCP setup The setup wizard finds MCP servers already configured in Claude Code and Cursor, lets you choose which ones to protect, and installs the flowifai wrapper in their place. One run can onboard several MCPs. Start with the no-side-effects preview: ```sh flowifai setup --dry-run ``` Then run the interactive setup: ```sh flowifai setup ``` The interactive picker starts with every eligible MCP selected. Use the arrow keys to move, space to toggle a selection, and enter to continue. You can also use: ```sh flowifai setup --all flowifai setup --all --yes flowifai setup --accessible flowifai setup --backend https://app.staging.flowif.ai ``` `--all` selects every supported result without opening the picker. `--yes` skips the final terminal confirmation, but does not skip browser authentication or health checks. `--accessible` (or `FLOWIFAI_ACCESSIBLE=1`) replaces the interactive picker with numbered, line-oriented prompts. Setup currently defaults to `https://app.staging.flowif.ai` while the production application remains behind its launch gate. `--backend` is available for self-hosted and local development deployments. ## What the wizard discovers | Client | Scope | Configuration read | | --- | --- | --- | | Claude Code | User | `~/.claude.json` | | Claude Code | Project | `.mcp.json` in the current project | | Claude Code | Local | The current project's local entries in `~/.claude.json` | | Cursor | User | `~/.cursor/mcp.json` | | Cursor | Project | `.cursor/mcp.json` in the current project | Run setup from the project whose project or local entries you want to discover. Discovery is read-only and does not invoke either client. The wizard supports local stdio MCP launches with a command, ordered arguments, optional working directory, and environment values that can be frozen. It lists unsupported entries with a reason. Remote HTTP, SSE, WebSocket, dynamic-input, or ambiguous definitions are not silently converted. Claude entries with literal environment values are also refused because Claude's native mutation CLI would place those values in process arguments; inherited `${NAME}` references remain supported. Claude Desktop, VS Code, Codex, Windsurf, and other MCP clients are not modified by this release. Their discovery and mutation paths are independently capability-gated; use the [manual setup](#manual-or-unsupported-clients) until support for a client and scope is explicitly listed here. ## What dry run reveals Dry run prints the client, scope, source path, executable name, argument count, working directory, and environment variable names. It does not print argument values, environment values, raw configuration, or credentials. It also does not start MCP servers, open a browser, make network requests, or change client or flowifai files. Use it before setup when reviewing a shared or sensitive machine. ## What happens after confirmation For each distinct selected launch, setup: 1. Inspects the real MCP server and requires it to expose at least one tool. 2. Opens a browser for flowifai authentication. If auto-open fails, the terminal still prints the URL. 3. Creates one protected profile with a server-generated credential. 4. Writes private profile configuration and frozen environment data locally. 5. Installs and starts a separate profile broker, then waits for its identity and tool schema to verify. 6. Updates Cursor configuration atomically or uses Claude Code's native MCP config commands, preserving the original client scope. 7. Activates the profiles only after every selected broker and wrapper verifies. Equivalent definitions can share one protected profile, so the same MCP configured in more than one supported scope does not need duplicate broker processes. If a step fails, setup compensates in reverse: it restores client changes, removes services it installed, and revokes the provisional enrollment. Client files are not changed until all selected profile brokers are healthy. ## Profile isolation and the secret boundary Each protected profile has its own local configuration, credential, loopback endpoint, and broker process. The broker starts the real MCP server with the environment frozen during setup; it does not inherit a fresh ambient environment every time it launches. The frozen baseline includes ordinary runtime essentials such as `HOME`, `PATH`, temporary-directory, locale, and certificate-path variables, plus the selected MCP's environment. All `FLOWIFAI_*` variables and setup, enrollment, broker, and server-to-server secret names are stripped from the child MCP environment. The per-profile broker credential is separate and is never passed to the MCP child. This is useful process and configuration isolation, but it is **not** a container, VM, filesystem sandbox, or network firewall. An agent that also has direct credentials, shell access, or an ungated tool path can bypass flowifai. Read the [security model](/docs/security-model/) before protecting production capabilities. ## Status and service diagnostics List protected profiles, inspect the latest setup run, or name a run explicitly: ```sh flowifai profiles list flowifai setup status flowifai setup status RUN_ID flowifai setup logs RUN_ID ``` Setup status prints the durable run state, its profiles and activation state, the exact rollback deadline, and the safe next action. Setup logs prints the run's sanitized lifecycle timeline. The private JSONL source records only run ID, state, outcome, and time; it is mode `0600` and rotates at 1 MiB. Check one profile or all profiles: ```sh flowifai status --profile PROFILE_ID flowifai status --all flowifai doctor --profile PROFILE_ID --strict flowifai doctor --all --strict ``` Inspect or operate the separate profile service: ```sh flowifai broker status --profile PROFILE_ID flowifai broker logs --profile PROFILE_ID flowifai broker reload --profile PROFILE_ID flowifai broker stop --profile PROFILE_ID flowifai broker start --profile PROFILE_ID ``` Stopping or uninstalling a service is an operational action. It does not restore a client configuration or revoke the backend profile, so it is not a rollback. ## Rollback and interrupted-run recovery A successful setup prints its run ID and retains the exact client preimages and inverse operations for 30 days. During that window, roll back the entire setup run: ```sh flowifai setup rollback RUN_ID ``` Rollback requires browser authorization. It revokes the run's backend profiles before disabling local profiles, restoring the original Cursor and Claude Code configuration, and removing the run's broker services. It is resumable: if a rollback step fails, correct the underlying problem and run the same command again. Exact restoration is refused after the printed deadline because the retained client preimages are no longer safe to depend on. Use `flowifai setup status RUN_ID` before recovery rather than guessing which effects completed. If setup committed on the backend but was interrupted before publishing local activation, status directs you to: ```sh flowifai setup resume RUN_ID ``` Resume is intentionally fail-closed. It idempotently finishes `backend_committing` and `activation_pending`. For an interruption at `authorized`, it reconciles the exact journaled enrollment attempt and then performs a revoke-first rollback. For an already durable `enrolled` state, it continues that rollback. It never replays uncertain MCP inspection or client edits; other interrupted states require status-guided recovery. ## Remove one profile To permanently decommission one profile without affecting its siblings: ```sh flowifai profiles remove PROFILE_ID ``` Removal first verifies that every mapped client entry is still the exact flowifai wrapper for that profile. It then requires fresh browser authorization bound to the profile's setup run, revokes only that backend profile, disables only its local activation, removes its exact wrapper entries, stops and uninstalls its broker service, and deletes its local profile state. Sibling profiles remain active. This is decommissioning, not exact restoration: it removes the flowifai wrapper entry but does not reconstruct the original direct MCP definition. Use whole-run `flowifai setup rollback RUN_ID` within the 30-day window when you need the retained original definitions restored. A client entry changed since setup causes removal to stop rather than overwrite the change. ## Create-only profile changes Setup creates protected profiles; it does not edit a profile's MCP launch, frozen environment, or credential in place. If the underlying MCP command, arguments, working directory, or credentials change, treat that as a new setup operation rather than assuming a running profile was updated. ## Accessible terminal behavior The default interactive MCP picker uses keyboard navigation and cursor repainting. Run `flowifai setup --accessible`, or set `FLOWIFAI_ACCESSIBLE=1`, to replace it with numbered, line-oriented selection and confirmation prompts without ANSI styling or cursor control. Redirected input/output and `TERM=dumb` also receive stable plain output. All progress after selection is append-only, every status has a text label, and no meaning depends on color alone. This mode is designed for screen readers, dictation, terminal logs, and copied text; it is not a claim of certification with every terminal and assistive-technology combination. `--all --yes` can remove the selection and confirmation prompts, but browser authentication remains interactive. ## Manual or unsupported clients For a client or transport not listed above, keep using the explicit enrollment path: ```sh flowifai connect --backend https://app.staging.flowif.ai --name my-agent --pairing-token-stdin -- /path/to/mcp-server --flag value flowifai broker install-service flowifai broker start ``` Then print a wrapper path or supported manual client configuration: ```sh flowifai wrapper-path flowifai client-config claude --print ``` The manual singleton flow remains supported, but it does not provide the setup wizard's multi-profile orchestration.