Import existing MCP config

Use import when a supported AI client already contains MCP server entries that should become part of a LightNow Runtime Profile. Import changes the target profile; it does not rewrite the source client file.

Supported sources

The current CLI imports codex, claude-code, claude-desktop, cursor, vscode, and antigravity. Use --config-path when the file is not at the client's default location.

Preview a Codex import

lightnow login
lightnow import-config --client codex --profile default --dry-run

What preview does

Preview is non-writing, not offline

The CLI reads the source config and sends its content to the authenticated Registry API import endpoint for classification. --dry-run prevents profile changes and never edits the source file. Review the source before sending it if it contains values that should not leave the machine.

The CLI prints a redacted summary instead of echoing the source config. Each entry is classified, for example as mapped, custom, importable, or blocked. Resolve blocked or ambiguous results before applying the import.

Apply with merge

Merge is the default and safest mode. Accepted imported entries are added to the target Runtime Profile while its existing server membership remains.

Merge into the default Runtime Profile

lightnow import-config --client codex --profile default

The command uses the active personal or organization context. Pass --tenant <id-or-slug> only when the profile belongs to that organization and your account has access to it.

Replace profile membership

Replace changes the entire server list

--replace makes the accepted import result the target profile's server membership. Existing profile servers that are not in the accepted import are removed. Preview the same command first.

Preview and apply replace

lightnow import-config --client codex --profile default --replace --dry-run
lightnow import-config --client codex --profile default --replace

Use replace only when the local source file is intentionally the complete source of truth for that Runtime Profile.

Finish the migration

After the profile contains every server you need, replace the direct client entries with one LightNow Proxy entry:

Connect Codex and verify

lightnow sync --client codex --profile default --local-proxy
lightnow config-status --client codex --json
lightnow-proxy --config ~/.lightnow/lightnow-proxy/codex.yaml --health --json

The sync lists direct entries before removing them, asks for confirmation, and keeps ~/.codex/config.toml.lightnow.bak. Restart Codex after the write.

Done when

1

Every useful source entry is accounted for

It is mapped or imported as custom, or you deliberately excluded it.

2

The Runtime Profile is correct

Existing membership was preserved with merge, or intentionally replaced.

3

The client is managed

config-status reports managed and the proxy health result explains any remaining upstream failures.

Common failures

PathConfig file not found

Pass the exact source file with --config-path.

SourceImport client unsupported

Use one of the six supported import targets listed above.

SessionAuthentication expired

Run lightnow login, then repeat the preview.

MappingEntry is blocked

Keep it out of replace mode until its identity and runtime requirements are understood.

Related guides

• Quickstart
• Connect Codex
• MCP client support