LightNow MCP Proxy

Connect your AI clients to your MCP servers—securely managed in one place.

The LightNow MCP Proxy is the local runtime behind LightNow profiles. Connect Codex, Claude Desktop, Cursor, VS Code, or Antigravity once, then manage the MCP servers available to that client in LightNow instead of copying server configuration and secrets into every tool.

• Keep MCP access organized in personal and organization profiles.
• Connect local stdio and remote Streamable HTTP servers through one entry.
• Resolve credentials on the user's machine instead of embedding them in MCP client configuration.
• Apply profile and policy changes without rebuilding every client setup.
• Observe client, profile, server health, and tool usage. Tool arguments are captured by default with credential-like fields redacted and can be disabled; tool results and resolved secrets are never collected.

The installed command remains lightnow-proxy. It runs locally, uses the identity-bound LightNow CLI session, resolves the selected profile, and routes tool and resource requests to the profile's MCP servers.

Capabilities come from your LightNow profile

The proxy deliberately does not ship demo tools. Its MCP capabilities are the real tools and resources exposed by the servers selected in the active LightNow profile, so the list differs between teams and clients. Names such as github__create_issue identify both the upstream server and its tool and avoid collisions when several servers use the same tool name.

The proxy supports the official MCP 2026-07-28 revision with stateless, per-request protocol metadata and server/discover. It keeps automatic compatibility with handshake-era servers and clients through 2025-11-25.

Tool discovery reads complete pagination from the actual configured upstream. It fails explicitly on repeated cursors, duplicate exact names or limits of 30 seconds, 100 pages, 2,000 tools and 4 MiB of definitions. A complete empty inventory stays distinct from incomplete discovery. Modern HTTP calls prepare their parameter-header schemas from that same fully discovered client. The managed dispatch primitive authorizes that inventory before sending once; schema-mismatch recovery and interactive retries must return to its policy gate.

When Registry API requests an optional sanitized setup preview, the Proxy projects only public input IDs, binding booleans, typed placeholders and explicitly allowed public choice indexes from the native managed context. It does not parse launch commands or copy configuration values, files, endpoints or tool metadata into the preview. Unsupported or mismatched descriptors produce an unavailable preview without failing successful private discovery. Sharing remains a separate explicit API/UI action; this Proxy does not create or publish contributions. The full workflow is specified in Registry API #1340.

For managed connections the existing device heartbeat declares managed-connections.v1 and obtains the actor-owned runtime client ID, even when optional activity capture is disabled. Compatible synchronized proxies poll every 15 seconds and execute at most two queued private discoveries concurrently. They resolve the exact current assignment, compare queued profile, policy and credential revisions before opening the upstream, and report to the original request with If-Match. Shutdown cancels outstanding discovery work; failures report bounded codes without private definitions or raw upstream errors. Legacy presence-only clients retain the 120-second interval. Registry supplies the canonical connection, assignment and bounded bootstrap context. Complete private inventory reporting returns exact allowed original names from the same backend authorizer as dispatch. The Proxy filters discovery and checks that decision again on the actual upstream session before one business call. Expected managed denials return a normal MCP tool error containing a content-free reason code. Absolute expiry and a monotonic deadline both apply; reporting does not renew the lease. Managed contexts do not authorize resource methods. Synchronized profiles bypass persistent tool caches and stale fallbacks. Canonical aliases take precedence; required organization admission also excludes local static and legacy runtime overrides from the managed profile. Managed wire names use ln_<full assignment UUID hex>__<original tool name>. Descriptions and metadata retain readable aliases. Aliases containing underscores, renames, and replacement assignments therefore cannot transfer tool identity. The reserved UUID namespace cannot fall back to static/legacy routing after an assignment is removed; ordinary legacy tool names retain their existing form.

Managed calls also retain content-free required evidence independently of optional activity capture. A private SQLite journal beside the CLI session commits each attempt before startup and handoff intent before dispatch. It retries only the original event UUIDs, subject and reporting receipt; it never retries a business call. Native OS locks distinguish live calls from interrupted ones. Lost outcomes stay unknown. The Registry's explicit RUNTIME_PROFILE_FORBIDDEN response records a denied call using its original reporting receipt; it is not an infrastructure outage. Unavailable storage or exhausted capacity blocks dispatch. Local /status exposes pending/unresolved counts and closed delivery codes. The bounded journal retains rejected/expired facts for explicit resolution. See the evidence contract.

Install

Requirements:

• Python 3.11 or higher
• pipx
• a LightNow account
• the LightNow CLI

pipx install lightnow-cli
lightnow login

Install the proxy with Homebrew:

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

Or install it with pipx:

pipx install lightnow-proxy

Or install it with uv:

uv tool install lightnow-proxy

The Python package installs the lightnow-proxy command used by MCP clients.

For repository-local development:

uv tool install --from . lightnow-proxy

Update supported CLI and Proxy installations through the LightNow CLI:

lightnow update --check
lightnow update

Homebrew, pipx and uv are managed. The proxy only reports its observed version and update state in metadata-only heartbeats; it never invokes a package manager or delays MCP startup to check for releases.

Configure a Client

Use the LightNow CLI. It writes the client MCP entry and the per-client Local Proxy config.

lightnow sync --client codex --local-proxy
lightnow sync --client claude-desktop --local-proxy
lightnow sync --client cursor --local-proxy
lightnow sync --client vscode --local-proxy
lightnow sync --client antigravity --local-proxy

Restart the MCP client after syncing.

Multiple accounts and organizations

Use a distinct --connection alias for every account, organization or profile that should appear in the same MCP client:

lightnow login
lightnow sync --client codex --local-proxy \
  --connection lightnow-personal --profile default

# Sign in with the organization account before creating this connection.
lightnow login
lightnow sync --client codex --local-proxy \
  --connection lightnow-acme --tenant <tenant-id> --profile engineering

Each generated proxy config has a stable connection ID and points to one named CLI session under ~/.lightnow/sessions/. It also records the expected issuer and subject. The proxy refuses Registry requests when those values do not match, so a later CLI login cannot silently switch an existing connection. No access or refresh token is written to the proxy YAML.

Check the local setup:

lightnow config-status --client codex

Check whether the proxy can resolve the selected profile and reach its upstream MCP servers:

lightnow-proxy --health
lightnow-proxy --health --json

By default this reads ~/.lightnow/lightnow-proxy/default.yaml, which is written when the default profile is synced into Local Proxy mode. For a client-specific config, pass the generated path explicitly:

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

Named connections use separate files such as ~/.lightnow/lightnow-proxy/codex-lightnow-acme.yaml. The JSON health report shows their non-secret connection alias, ID, account label, scope, profile and identity-binding status. Legacy configs that use cli_config_path remain readable, but are restricted to the configured authentication issuer.

When telemetry is enabled, active health checks and runtime events are sent to the LightNow Control Plane. Tool-call arguments are captured by default and can be disabled independently in the Local Proxy settings. Credential-like fields are redacted before transmission. The proxy also sends device presence immediately at startup and every two minutes. The Control Plane can then show which devices, clients and profiles are active, healthy, degraded, or failing, along with CLI/Proxy versions and update status. Tool results, resolved LightNow secrets, unredacted authorization values, network addresses, hardware identifiers and local paths are not stored. Credential-like argument fields, including authorization headers, are replaced with [REDACTED] before transmission.

Vault providers configured for runtime resolution are resolved on this host, after Registry API has returned a provider reference without credentials or a secret value. HashiCorp Vault Proxy auto-auth on 127.0.0.1:8200 is the default. Provider-specific loopback listeners can be mapped under runtime_secrets.providers in the generated YAML; LightNow CLI preserves these non-secret mappings on subsequent syncs. The optional OS-keyring path is available with lightnow-proxy[keyring]. Resolution failures are fail-closed and plaintext values are never added to the tool-schema cache.

Managed runtime files

STDIO servers may attach bounded, non-secret runtime_files to their Runtime Profile client configuration. LightNow Proxy writes each file set below ~/.lightnow/runtime-files in an immutable content-addressed directory before the upstream process starts. Files use mode 0600; managed directories use mode 0700.

Reference the resolved directory with ${LIGHTNOW_RUNTIME_DIR} in arguments, environment values, or the working directory:

{
  "transport": "stdio",
  "command": "npx",
  "args": [
    "@bytebase/dbhub@latest",
    "--config",
    "${LIGHTNOW_RUNTIME_DIR}/dbhub.toml"
  ],
  "env": {
    "DBHUB_DSN": "${DBHUB_DSN}"
  },
  "runtime_files": [
    {
      "path": "dbhub.toml",
      "content": "[[sources]]\nid = \"analytics\"\ndsn = \"${DBHUB_DSN}\"\n"
    }
  ]
}

Runtime files are UTF-8 text and are limited to 16 files, 64 KiB per file, and 256 KiB per server configuration. Paths must be relative and cannot contain traversal segments or backslashes. Secret values must remain in LightNow's runtime secret buckets; files may refer to the corresponding environment names but must not embed plaintext credentials. Invalid or modified materializations fail closed before the upstream starts.

More Documentation

Detailed setup guides, examples, diagrams, supported client paths, telemetry behavior and troubleshooting live in the LightNow docs:

• Connect MCP clients
• CLI reference
• Release process

Local Development

For contributors working on this repository:

uv venv
uv pip install -e .[dev]
make test

Jenkins builds the runtime image, runs the Ruff and pytest commands from make lint test inside it, then checks lightnow-proxy --help. The checkout is mounted read-only and test environments live in the container. The Jenkinsfile uses the native build-agent capability pool and removes only its own validation image. The timeout includes agent allocation. GitHub Actions continues to run the Python version matrix. Before merging an Ops dependency update, require terminal Jenkins success at the current PR head. The pipeline validates changes without publishing an image or changing accounts.

Run the proxy with the example config:

uv run lightnow-proxy --config config.example.yaml

Run the proxy as a stdio MCP server:

uv run lightnow-proxy --config config.example.yaml --transport stdio

Run a local health check against the example config:

uv run lightnow-proxy --config config.example.yaml --health