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:

flowifai setup --dry-run

Then run the interactive setup:

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:

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

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 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 before protecting production capabilities.

Status and service diagnostics

List protected profiles, inspect the latest setup run, or name a run explicitly:

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:

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:

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:

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:

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:

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:

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:

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.

View this page as markdown · All docs as one file