MCP client support

Use this reference to choose the exact --client value and understand what the CLI can write today. Local Proxy means the client receives one managed LightNow entry. Bridge means LightNow renders a native compatibility file from a Runtime Profile; it is not managed Local Proxy support.

Support matrix

Client	CLI target	Default config	Local Proxy	Import source
Codex	codex	~/.codex/config.toml	stdio and local HTTP	yes
Google Antigravity	antigravity	~/.gemini/config/mcp_config.json	stdio	yes
Claude Code	claude-code	~/.claude.json	stdio	yes
Claude Desktop	claude-desktop	~/Library/Application Support/Claude/claude_desktop_config.json	stdio	yes
Cursor	cursor	~/.cursor/mcp.json	stdio	yes
Gemini CLI	gemini-cli	~/.gemini/settings.json	stdio	no
VS Code	vscode	user-level Code mcp.json	stdio	yes
Windsurf / Devin Desktop	windsurf	~/.codeium/windsurf/mcp_config.json	bridge	no
Continue	continue	~/.continue/config.yaml	bridge	no
LibreChat	librechat	./librechat.yaml	bridge	no
MCP Inspector	mcp-inspector	./lightnow-mcp-inspector.sh	bridge helper	no

VS Code's default file is ~/Library/Application Support/Code/User/mcp.json on macOS, %APPDATA%/Code/User/mcp.json on Windows and ~/.config/Code/User/mcp.json on Linux. Override any default with --config-path.

Choose the workflow

Use these modes deliberately:

Mode	Command shape	Result
Managed Local Proxy	lightnow sync --client <client> --local-proxy	One LightNow entry plus a per-client Proxy config
Organization policy	lightnow sync --client <client> --from-settings	LightNow Config selects profile, mode and unmanaged-entry policy
Direct sync	lightnow sync --client <client>	Client-native per-server entries
Runner mode	lightnow sync --client <client> --runner	One lightnow run wrapper per profile server
Import	lightnow import-config --client <client>	Supported existing entries merge into a Runtime Profile

Do not combine --runner, --local-proxy or --from-settings. Preview file changes with lightnow sync ... --dry-run when using a write path you have not already tested.

Local Proxy contract

Local Proxy stdio sync supports Codex, Antigravity, Claude Code, Claude Desktop, Cursor, Gemini CLI and VS Code. Codex is currently the only client target that also supports a client-facing local HTTP entry:

Connect Codex to an already running local Proxy

lightnow sync --client codex --profile default --local-proxy --local-proxy-transport http --local-proxy-url http://127.0.0.1:8080/mcp

Every Local Proxy sync writes:

1. the target AI-client config with one LightNow entry, and
2. ~/.lightnow/lightnow-proxy/<client>.yaml unless --local-proxy-config-path overrides it.

For the default profile, the CLI also maintains ~/.lightnow/lightnow-proxy/default.yaml unless an explicit Proxy config path was supplied. The per-client YAML identifies the profile, client transport, Registry API, organization context and policy posture. Upstreams are resolved from LightNow at runtime.

Import contract

lightnow import-config accepts Antigravity, Claude Code, Claude Desktop, Codex, Cursor and VS Code as sources. It does not accept Gemini CLI, bridge targets or MCP Inspector.

Preview, merge or replace

lightnow import-config --client codex --profile default --dry-run
lightnow import-config --client codex --profile default
lightnow import-config --client vscode --profile platform --tenant acme --replace

• --dry-run parses and previews without applying the import.
• The default operation merges supported entries into the target profile.
• --replace replaces the target profile's complete server list.
• --config-path selects a non-standard source file.

Import never makes the source client file the ongoing source of truth. After the profile is ready, sync the client back to the intended managed or compatibility mode.

Direct sync, runner and bridge paths

Direct sync asks LightNow for a client-native export and patches the selected file. It can materialize server details and secret values according to the chosen secret mode, so prefer Local Proxy for normal managed use.

Runner mode writes wrappers shaped like:

lightnow run --profile <profile> --server <alias>

Runner mode requires registry-linked profile servers with versions and fails instead of writing a partial result when the selected profile cannot be rendered. Windsurf, Continue and LibreChat use their native JSON or YAML output as bridge paths. MCP Inspector uses a generated shell helper for focused inspection.

Config posture states

lightnow config-status --client <client> inspects the client file and expected Proxy config without printing secrets.

State	Meaning	Next action
managed	One valid LightNow Proxy entry and no bypassing entries	No config action required
mixed	LightNow Proxy and unmanaged MCP entries coexist	Confirm policy or re-sync
legacy_runner	Old lightnow run wrappers remain	Re-sync with Local Proxy
unmanaged	Direct MCP entries exist without LightNow Proxy	Import useful entries, then sync
empty	No MCP entries were found	Sync the intended profile
invalid	The client file could not be parsed	Repair or restore the file before sync

lightnow config-status --client codex
lightnow config-status --client codex --json

Continue with the client task

Safe pathConnect MCP clients

Install, preserve useful config, sync one pilot and verify the runtime.

Decision guideChoose an MCP client workflow

Select managed, policy-driven or compatibility mode for a real deployment.