LightNow Proxy runtime
LightNow Proxy is the MCP server process that a supported AI client starts. It
turns one client-side LightNow entry into the MCP servers selected in a
Runtime Profile and keeps their commands, URLs and secret values out of the
normal client file.
Request flow
The Proxy runs in the same execution environment as the AI client. That can be a workstation, remote development host, server or CI runner. A local stdio upstream also runs in that environment; an HTTP upstream only needs to be reachable from it.
What stays on the client host
- the AI-client configuration,
- the per-client Proxy YAML below
~/.lightnow/lightnow-proxy/, - local stdio processes and their filesystem access,
- tool arguments and tool results, and
- resource contents and workspace paths.
The generated Proxy YAML identifies the selected profile, client, transport, Registry API, organization context and policy posture. It does not need to copy the full Runtime Profile into the client file.
How the profile becomes runnable
When it starts, the Proxy uses the authenticated LightNow CLI session or explicit runtime credentials from its configuration. It resolves the selected Runtime Profile, then resolves each linked or custom server into an upstream configuration.
An upstream is one of two supported runtime shapes:
| Transport | Proxy action | Typical use |
|---|---|---|
stdio | Starts a local command with fixed arguments, working directory and environment | Local tools and filesystem-aware servers |
streamable-http | Opens an MCP session against a reachable HTTP URL | Hosted or network-reachable servers |
If required runtime inputs cannot be resolved, the Proxy fails explicitly. It does not invent a partial server configuration or silently replace the missing upstream.
How MCP methods are routed
The Proxy aggregates tools, resources and prompts from the active profile.
Tool aliases are prefixed as <upstream>__<tool> so duplicate tool names remain
unambiguous. Resource URIs are represented through a LightNow URI that retains
the upstream identity while the original content stays on the request path.
The Proxy handles these MCP families today:
- tools: list and call,
- resources: list, read and templates,
- prompts: list and get, and
- logging and progress notifications where the upstream supports them.
Tool discovery can be cached for a short period to make repeated client startup more reliable. A health check performs active discovery and reports the actual upstream state rather than trusting only cached metadata.
Runtime events and privacy boundary
When telemetry is enabled, LightNow Proxy sends metadata-only events for lifecycle, MCP operations and active health checks. Events may include method, status, duration, upstream alias, transport, tool name, resource URI, item counts, byte counts, content type and normalized client context.
Runtime events must not contain:
- tool arguments or tool results,
- resource contents,
- workspace paths, Git remotes or commit hashes,
- secrets or authorization headers.
This boundary makes it possible to investigate which route failed without turning LightNow into storage for MCP payloads.
Status and active health checks
config-status inspects the expected client and Proxy files. It does not start
upstreams. lightnow-proxy --health resolves the profile, performs tool
discovery against every upstream and returns one of three outcomes:
| Result | Meaning | Exit code |
|---|---|---|
healthy | The profile resolves and every upstream answers | 0 |
degraded | The Proxy can run, but an upstream fails or the profile is empty | 2 |
failed | The selected profile cannot be resolved | 1 |
lightnow config-status --client codex --json lightnow-proxy --config ~/.lightnow/lightnow-proxy/codex.yaml --health --json
Failure boundaries
Use the signal closest to the failure:
- A missing or invalid client entry belongs to client sync.
- A missing Proxy YAML or wrong profile belongs to local configuration.
- Authentication or organization-context failure blocks profile resolution.
- A failed upstream health row belongs to that server's command, credentials, transport or availability.
- A client-visible MCP error after healthy discovery belongs to the routed method or upstream implementation.