Connect MCP clients

LightNow helps you use MCP servers from the AI clients already installed on your computer. Instead of copying server commands, URLs, headers and secrets into every client by hand, you configure the servers once in LightNow and sync your client with the LightNow CLI.

The recommended setup is Local Proxy mode. Your client gets one LightNow MCP entry. The Local Proxy starts on your machine, fetches the selected LightNow configuration, resolves secrets locally at runtime and forwards MCP requests to the configured servers.

Why use the Local Proxy?

Use the Local Proxy when you want to:

• keep MCP server secrets out of individual client config files,
• manage the available MCP servers centrally in LightNow,
• use the same MCP setup across Codex, Claude Desktop, Cursor, VS Code and Google Antigravity,
• see MCP tool and resource activity in LightNow Insights,
• detect clients that still have unmanaged MCP server entries.

Direct client sync is still available, but it writes each MCP server directly into the client config. Use it only when a client cannot start the Local Proxy or when you intentionally need a standalone local config.

How the Local Proxy works

The MCP client talks only to the local LightNow entry. The Local Proxy then routes the request to the right upstream MCP server. Upstream servers can be local stdio processes or reachable Streamable HTTP endpoints.

Install

You need:

• Python 3.11 or higher,
• pipx,
• a LightNow account,
• the AI client you want to connect.

Install the LightNow CLI:

brew tap lightnow-ai/tap
brew install lightnow-cli

Or with pipx:

pipx install lightnow-cli

Or with uv:

uv tool install lightnow-cli

Install the Local Proxy with Homebrew:

brew tap lightnow-ai/tap
brew install lightnow-proxy

Or with pipx:

pipx install lightnow-proxy

Or with uv:

uv tool install lightnow-proxy

The package installs the lightnow-proxy command that LightNow writes into your MCP client configuration.

Sign in to LightNow:

lightnow login

Check your session:

lightnow status

If you use an organization account, select it once:

lightnow context --tenant acme

Configure a Client

Run one sync command for each client you want to connect. After syncing, restart the client so it reloads its MCP configuration.

Codex

lightnow sync --client codex --local-proxy

Claude Desktop

lightnow sync --client claude-desktop --local-proxy

Claude Code

lightnow sync --client claude-code --local-proxy

Cursor

lightnow sync --client cursor --local-proxy

VS Code

lightnow sync --client vscode --local-proxy

VS Code can expose large MCP tool sets through virtual tools. The LightNow CLI tries to enable the required VS Code setting automatically. If your settings.json contains comments or cannot be updated, the CLI prints the setting you should add manually.

Google Antigravity

lightnow sync --client antigravity --local-proxy

Google has moved individual Gemini CLI users to Antigravity. LightNow keeps gemini-cli support for Enterprise or API-key environments, but Antigravity is the recommended Google client for individual users.

Let LightNow Choose the Mode

If your organization manages client rollout policy in LightNow, use --from-settings. The CLI reads the LightNow policy and writes the correct local configuration for the selected client:

lightnow sync --client codex --from-settings

This is useful for team rollout because the user does not need to know whether their organization currently wants Local Proxy mode or direct sync mode.

If your organization blocks unmanaged client MCP servers, --from-settings keeps only the LightNow entry for managed clients. If unmanaged servers are allowed, the CLI keeps existing user-managed entries and reports the client as mixed so the difference is visible.

Check Configuration Status

Use config-status when a client cannot see tools or when you want to verify that it is still managed through LightNow:

lightnow config-status --client codex

For automation or support bundles, request JSON:

lightnow config-status --client claude-desktop --json

The status output tells you whether:

• the client config exists and can be parsed,
• the LightNow MCP entry is present,
• the Local Proxy config file exists,
• the configured lightnow-proxy command can be started,
• unmanaged MCP servers are still configured next to LightNow,
• older lightnow run wrapper entries are still present,
• which profile, client transport, telemetry flag and Local Proxy policy are stored in the per-client Local Proxy config.

The output is redacted and does not print secret values.

Check Local Proxy Health

config-status checks the client configuration. To check whether the Local Proxy can also resolve the selected profile and reach the configured MCP servers, run:

lightnow-proxy --config ~/.lightnow/lightnow-proxy/codex.yaml --health

For support automation, request JSON:

lightnow-proxy --config ~/.lightnow/lightnow-proxy/codex.yaml --health --json

The health report is redacted. It shows the active profile, upstream aliases, transport, tool counts, durations and error types. It does not include secrets, authorization headers, tool arguments, tool results or resource contents.

If telemetry is enabled, running an active health check also records a metadata-only proxy health event in LightNow Insights. This lets you see whether Codex, Claude Desktop, Cursor, VS Code, Google Antigravity or another managed client is healthy, degraded or failing for the selected profile. A degraded client usually means the Local Proxy starts correctly, but one or more upstream MCP servers cannot be reached or cannot list tools.

Supported Clients

Client	Sync target	Default config path
Codex	codex	~/.codex/config.toml
Claude Desktop	claude-desktop	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Code	claude-code	~/.claude.json
Cursor	cursor	~/.cursor/mcp.json
VS Code	vscode	~/Library/Application Support/Code/User/mcp.json on macOS
Google Antigravity	antigravity	~/.gemini/config/mcp_config.json
Gemini CLI	gemini-cli	~/.gemini/settings.json
Windsurf	windsurf	~/.codeium/windsurf/mcp_config.json
Continue	continue	~/.continue/config.yaml
LibreChat	librechat	./librechat.yaml
MCP Inspector	mcp-inspector	./lightnow-mcp-inspector.sh

Use --config-path when a client stores its configuration somewhere else:

lightnow sync --client vscode --local-proxy --config-path ~/custom/mcp.json

What Gets Written Locally

Local Proxy mode writes two things:

1. A client config entry named LightNow.
2. A per-client Local Proxy config under ~/.lightnow/lightnow-proxy/.

Example client entry:

{
  "mcpServers": {
    "LightNow": {
      "command": "/Users/you/.local/bin/lightnow-proxy",
      "args": [
        "--config",
        "/Users/you/.lightnow/lightnow-proxy/claude-desktop.yaml",
        "--transport",
        "stdio"
      ]
    }
  }
}

Example Local Proxy config:

local_proxy:
  enabled: true
  profile: "default"
  sync_from_lightnow: true
  client_name: "claude-desktop"
  runner_name: "lightnow-local-proxy"
  client_transport: "stdio"
  telemetry_enabled: true

registry_api:
  enabled: true
  base_url: "https://registry-api.lightnow.ai/v0.1"
  use_cli_session: true
  cli_config_path: "~/.lightnow/config.json"

The Local Proxy uses your existing lightnow login session. If that session is missing or expired, run lightnow login again.

Secrets and Telemetry

In Local Proxy mode, LightNow-managed secrets are resolved by the Local Proxy at runtime. They are not written into the MCP client config.

When telemetry is enabled, the Local Proxy sends metadata-only events to LightNow Insights. Events can include client name, profile, server alias, method, tool name, resource URI, status, duration, error type and byte counts. Health events additionally include the active Local Proxy policy and aggregate upstream counts, such as healthy upstreams, failed upstreams and tool count.

Telemetry does not include tool arguments, tool results, resource contents, workspace paths, git remotes, commit hashes, secrets or authorization headers.

Direct Sync Mode

Direct sync writes each MCP server directly into the client config:

lightnow sync --client codex --profile default

Preview the result without writing:

lightnow sync --client codex --profile default --dry-run

By default, direct sync writes ready-to-use client configs. If a profile uses LightNow-managed secrets, the CLI asks before writing resolved secret values into the local client file.

To write placeholders instead:

lightnow sync --client codex --profile default --secret-mode placeholder

Troubleshooting

Client does not show LightNow tools

1. Restart the MCP client.

2. Run lightnow config-status --client <client>.

3. Check that lightnow-proxy is installed:

   lightnow-proxy --version

4. Run a Local Proxy health check:

   lightnow-proxy --config ~/.lightnow/lightnow-proxy/<client>.yaml --health

5. Run lightnow login if the CLI session expired.

Client still has unmanaged MCP servers

config-status reports mixed when LightNow is configured but other user-managed MCP servers remain in the same client config. This can be intentional when your organization allows unmanaged client entries. Those servers bypass LightNow monitoring and policy, so teams that require all MCP traffic to go through LightNow should block unmanaged entries in LightNow Config and run sync with --from-settings. Internal MCP entries used by a client itself are reported separately and do not make a config mixed.

To remove unmanaged entries manually, run Local Proxy sync again and approve removal when prompted:

lightnow sync --client codex --local-proxy

For a centrally managed client, let LightNow apply the organization policy:

lightnow sync --client codex --from-settings

The CLI creates a local backup before writing.

Local development certificate error

For *.lightnow.local, make sure the local LightNow certificate authority is trusted before running lightnow login or syncing a local stack profile.

Need request-level debug data

Run the Local Proxy with a capture file:

lightnow-proxy --config ~/.lightnow/lightnow-proxy/codex.yaml --transport stdio --capture-path /tmp/lightnow-mcp-capture.txt

The capture file contains redacted MCP metadata such as initialize data, method names, tool names, argument keys and byte sizes. It is intended for local debugging and should be handled like diagnostic data.

More Information

• CLI reference
• Integrations and profiles
• Model Context Protocol