Sync MCP clients

LightNow can export a runtime profile as a native MCP configuration for the tools you already use. The recommended workflow is the LightNow CLI: it logs in to your LightNow account, asks the Registry API for the client-specific configuration, and updates only the LightNow-managed block in your local client file.

The CLI preserves user-owned configuration, creates a backup before writing, and keeps secrets out of terminal previews.

For command-by-command flags and examples, see the CLI reference.

Installation

Install the CLI with pipx:

pipx install lightnow-cli

You can also install it directly from the lightnow-ai/lightnow-cli repository:

git clone https://github.com/lightnow-ai/lightnow-cli.git
cd lightnow-cli
pipx install --force --editable .

If you already have the repository checked out, run the same pipx install command from your local lightnow-cli directory.

Check that the command is available:

lightnow --version

Login

lightnow login

The CLI opens your browser and starts the LightNow device-login flow. After login, tokens are stored locally in ~/.lightnow/config.json. Commands refresh expired access tokens automatically while the refresh token is valid.

If you work in an organization, select it once:

lightnow context

The selection is stored locally and reused by context-aware commands such as sync, run, search, favorites, info, and publish. Use lightnow context --personal to switch back to your personal account, or pass --tenant <tenant-id> to a single command when automation needs an explicit organization context.

To inspect the current session:

lightnow status
lightnow whoami

To clear the local session:

lightnow logout

Publish and sync your own server

The same CLI can publish an MCP server specification and then sync the configured runtime profile into local clients.

Create a small stdio server metadata file:

mkdir lightnow-mcp-example
cd lightnow-mcp-example
cat > server.json <<'JSON'
{
  "name": "your-namespace.example/memory",
  "version": "1.0.0",
  "description": "A runnable stdio MCP server example for validating LightNow CLI publish and sync workflows.",
  "license": "MIT",
  "keywords": ["mcp", "server", "example", "stdio"],
  "transport": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-memory"]
  },
  "packages": [
    {
      "registry": "npm",
      "name": "@modelcontextprotocol/server-memory",
      "version": "2026.1.26",
      "transport": "stdio"
    }
  ]
}
JSON

Create a short documentation file:

cat > docs.md <<'MD'
# Memory MCP Server

This server is launched with `npx -y @modelcontextprotocol/server-memory`.
MD

Validate the artifacts:

lightnow validate --server server.json --docs docs.md

Before publishing, replace your-namespace.example/memory with a namespace you own in LightNow. Then publish:

lightnow publish --server server.json --docs docs.md

After publishing:

1. Open Integrations in LightNow.
2. Add the published server to your default runtime profile.
3. Save the server configuration.
4. Sync the profile into your MCP client:

lightnow sync --client codex --profile default

For a local config that keeps the secret as a placeholder, run:

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

Sync a profile with client-side secrets

This mode writes a ready-to-use client configuration. If the profile uses LightNow-managed secrets, the CLI asks for confirmation before writing resolved secret values into the local client file.

Sync the default profile into Codex:

lightnow sync --client codex --profile default

For organization profiles, select the organization context once:

lightnow context --tenant acme
lightnow sync --client codex --profile default

Preview a redacted diff without writing:

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

By default, sync writes ready-to-use client configs with LightNow-managed secret values included in the local client file after explicit confirmation. To write placeholders instead, use:

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

Sync a profile with the Local Runner

The Local Runner keeps secrets in LightNow. The client configuration contains only wrapper commands such as lightnow run --profile default --server sonarqube. When the client starts the MCP server, lightnow run fetches the secret-bearing runtime context from LightNow, starts the real local MCP server as a child process, and injects secrets only into that child process.

Use this mode when you do not want MCP clients to store or prompt for secrets:

lightnow sync --client codex --profile default --runner

For organization profiles:

lightnow context --tenant acme
lightnow sync --client codex --profile default --runner

You can run a single configured server directly:

lightnow run --profile default --server sonarqube

Local Runner sync requires the profile server to be linked to a Registry server version. Custom or unresolved servers are rejected until they are linked in Integrations. This is deliberate: the runner uses the Registry version to fetch the canonical runtime context and does not guess mappings.

Supported clients

Client	Default target	Format
Codex	~/.codex/config.toml	TOML
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json	JSON
Claude Code	~/.claude/mcp.json	JSON
Cursor	~/.cursor/mcp.json	JSON
Windsurf	~/.codeium/windsurf/mcp_config.json	JSON
Continue	~/.continue/config.yaml	YAML
Gemini CLI	~/.gemini/settings.json	JSON
LibreChat	./librechat.yaml	YAML
VS Code	./.vscode/mcp.json	JSON
MCP Inspector	./lightnow-mcp-inspector.sh	shell

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

lightnow sync --client vscode --config-path ~/work/my-project/.vscode/mcp.json

How secrets are handled

Secrets stored in LightNow are never printed in terminal output. The CLI supports three practical workflows:

• plaintext: writes the resolved secret value into the local client configuration after explicit confirmation. This is the default for lightnow sync, because many current MCP clients need secrets in their own local config.
• placeholder: writes references such as ${SONARQUBE_TOKEN} or client-native input prompts where supported. Use this when you prefer to supply secrets through your shell, editor prompts, or deployment environment.
• runner: writes lightnow run wrappers and keeps secret values out of client config files. Use lightnow sync --runner for this mode.

Browser exports in the LightNow UI default to placeholders. Plaintext export is policy-gated and requires explicit confirmation.

Organizations can disable Local Runner access through integration policy. If disabled, lightnow run fails with an explicit policy error instead of falling back to client-side secrets.

What sync changes

For TOML, YAML, and shell targets, the CLI writes a marked LightNow block and leaves everything outside that block untouched.

For JSON targets, comments are not available. The CLI merges the generated mcpServers or servers entries into the file and writes a sibling .lightnow-managed.json manifest so the next sync knows which entries it owns. User-managed server entries and VS Code inputs are preserved.

Before any write, the CLI creates a backup next to the target file:

config.toml.lightnow.bak
mcp.json.lightnow.bak

Troubleshooting

Access token expired

If a command prints:

Access token has expired. Please run 'lightnow login' again.

run lightnow login again. This means the stored refresh token is no longer valid.

Local development certificate error

For *.lightnow.local, make sure the local LightNow certificate authority is trusted by macOS before running lightnow login.

Missing values before export

If the UI reports missing values, open the server in Integrations, add the required secret under Secrets, and save. Stored LightNow-managed secrets are exported automatically; you do not need to add the same value again under Environment variables.

For --runner, missing or broken secrets are detected when lightnow run fetches the runtime context. The runner stops with an explicit error and does not start the child MCP server with partial configuration.

Client does not pick up changes

Most MCP clients read configuration at startup. Restart the client after sync. LibreChat also requires a service restart after editing librechat.yaml.