Lynx

Lynx is a Windows-first local multi-client MCP gateway + bring-your-own-CLI Agents runtime. It lets ChatGPT, OpenCode, Gemini, IDEs, CLIs, and other MCP-compatible applications access controlled development workspaces, and it can orchestrate coding CLIs already installed on your computer through persisted roles, real task pipelines, and PTY terminals—all while keeping execution, credentials, approvals, workspace boundaries, and activity history under local control.

Author: Domincee

Repository: https://github.com/DominceAseberos/Lynx_MCP

Website: https://dominceaseberos.github.io/Lynx_MCP/

Current release: v0.5.10

Capability reference: Markdown · HTML · DOCX

Lynx is personal, single-user software. It is not a hosted SaaS service and does not upload your project files to a Lynx backend.

What Lynx does

For a consolidated feature/security/tool matrix, see the Lynx Capabilities Reference.

Lynx has two independent local surfaces that reuse the same explicit workspace registry: Gateway for accepted MCP applications, and Agents for coding CLIs already installed/authenticated under your Windows account. Lynx itself does not add another LLM provider.

Agents now includes the Adaptive CLI Bridge. The six known CLIs keep their validated optimized adapters, while a custom executable can be inspected by capabilities instead of brand name. Lynx can infer a candidate headless/stdin transport from safe help/version surfaces, require an explicit Verify adaptive round trip, prove workspace-write capability only inside an isolated temporary directory, cache the learned profile by executable/version fingerprint, and then allow that verified CLI in compatible team roles. If no headless/stdin surface exists, verification can use a hidden PTY with a task-scoped loopback lynx-emit callback or a cryptographic nonce extracted from a rendered headless terminal buffer. Unknown/unverified tools remain interactive-only.

Your MCP client may run locally or remotely while your projects remain on your computer. Lynx provides one authenticated MCP gateway for multiple accepted applications:

ChatGPT / OpenCode / Gemini / IDE / CLI
    |
    | MCP over HTTPS
    v
ngrok / localhost.run tunnel
    |
    v
Lynx on 127.0.0.1
    |
    +-- OAuth / PKCE / per-client authorization
    +-- Accept / Reject connection gate
    +-- Client identities, sessions, revoke / block / lockdown
    +-- Shared / Restricted / Private workspace routing
    +-- File tools
    +-- Search tools
    +-- Bounded command execution
    +-- Git tools
    +-- Optional GitHub / Vercel / Supabase / Neon / Firebase tools
    +-- Cross-provider workspace provisioning
    +-- Global integration approval policy
    +-- Per-client local capability scopes
    +-- Approval policy
    +-- Client-attributed activity + security audit events
    +-- Windows notifications

The public tunnel is transport only. MCP execution, project access, approvals, settings, credentials, and tool execution remain local to the machine running Lynx.

Related MCP server: mise-en-space

Multi-client access and trust

Lynx treats each OAuth registration as a separate local client identity. A newly registered client starts Pending and does not receive usable MCP authorization until you accept it from the Connections tab. Rejecting the request denies the authorization flow. Previously connected clients from releases before multi-client controls are migrated as Previously authorized so existing installations keep working by default; you can turn on Re-approve previous clients to revoke those legacy tokens and require one new Accept decision.

The Connections tab provides:

• pending application name/redirect context with Accept and Reject;

• active session counts, last-seen metadata, Disconnect, Revoke, Block, and Unblock controls;

• Emergency lockdown, which disconnects active sessions and returns 423 Locked for MCP traffic until unlocked;

• pairing control for whether new clients may request authorization;

• per-client local capability presets: Read only, Developer, and Full local access; newly accepted clients start at Developer while migrated legacy clients retain Full for compatibility;

• per-client safety ceilings for concurrent MCP POST requests and requests per minute, with blocked bursts written to the security activity stream;

• one global integration approval mode for all accepted clients.

Application names/icons are recognition metadata only. Security decisions are attached to Lynx's internal OAuth client_id and its access/refresh tokens, so two applications using the same display name do not share authorization.

Workspace access is independent from the client capability preset:

• Shared — visible to every accepted client.

• Restricted — visible only to explicitly selected client identities.

• Private — no automatic visibility; explicit grants are required.

Restricted/private workspaces are filtered before list_workspaces and select_workspace, so a client without a grant does not receive their names or paths. Client capability presets then constrain local mutation tools inside the workspaces that client can see. Integrations intentionally remain Lynx-wide capabilities for every accepted client and follow the global integration permission setting instead of the local capability preset.

Activity records include client ID/name/version, MCP session, workspace, tool, request state, and bounded payload details. The Activity page also groups observable calls by MCP session so simultaneous ChatGPT/OpenCode/Gemini/IDE/CLI sessions are easier to distinguish without pretending Lynx can infer a model's private semantic task. Connection requests, accept/reject decisions, revocations, blocks, workspace-scope changes, request-limit events, policy changes, and lockdown events are also emitted as security activity records.

Optional developer integrations

Lynx exposes developer-provider automation without requiring a Lynx cloud account or backend. These connections live in the dedicated Integrations tab and are completely optional; they do not appear in or affect the normal Getting Started flow.

Supported providers:

• GitHub — create repositories, publish the selected workspace, and call GitHub REST endpoints.

• Vercel — create projects, configure environment variables, inspect deployments, and deploy GitHub-backed projects.

• Supabase — provision projects and use the Management API while keeping generated database passwords local.

• Neon — provision Postgres projects/branches and keep connection URIs encrypted locally.

• Firebase — use an encrypted service-account credential to manage Firebase projects, Hosting resources, App Hosting API resources, and Cloud Firestore through short-lived Google OAuth access tokens.

The provision_workspace_stack MCP tool can combine these operations in one approved workflow:

selected workspace
  -> create/publish GitHub repository
  -> optional Supabase or Neon database
  -> transfer required environment values inside Lynx
  -> optional Vercel project + deployment

Provider tokens and Firebase service-account JSON are encrypted with Electron safeStorage, decrypted only in the main process when making a provider request, and never returned through the renderer or MCP tool results. Firebase private keys are used locally to sign OAuth assertions; only short-lived Google access tokens are sent to Firebase/Google APIs. Database passwords, service credentials, and connection URIs are redacted or retained locally when a workflow can pass them directly to another provider.

GitHub fine-grained token setup

For broad development automation, create a fine-grained personal access token from GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens. Choose the intended resource owner and either All repositories or only the repositories you want Lynx to manage.

Recommended repository permissions for the broad automation profile are:

• Administration — Read and write

• Contents — Read and write

• Pull requests — Read and write

• Issues — Read and write

• Actions — Read and write

• Workflows — Read and write

• Deployments — Read and write

• Environments — Read and write

• Pages, Secrets, Variables, and Webhooks — Read and write only when needed

Administration: write is required for repository creation. Avoid unrelated account, billing, or organization permissions unless a specific workflow needs them.

The dedicated Integrations tab contains provider logos, credential links, connection testing, disconnect controls, and provider-specific setup guidance for GitHub, Vercel, Supabase, Neon, and Firebase.

Firebase service-account setup

1. Open Firebase Console → Project settings → Service accounts for the project you want Lynx to automate.

2. Generate a new private key and paste the complete downloaded service-account JSON into the Firebase card in Lynx.

3. Give that service account only the Google Cloud IAM roles the intended workflow needs. roles/firebase.admin provides broad Firebase administration; narrower options include roles/firebasehosting.admin for Hosting and roles/firebaseapphosting.admin for App Hosting. Creating or managing Firestore databases may require roles/datastore.owner or equivalent granular permissions.

4. Enable the Firebase Management, Firebase Hosting, Firebase App Hosting, or Firestore APIs when a selected workflow requires them.

Lynx ignores any credential-supplied OAuth host and always exchanges the signed service-account assertion at Google's fixed OAuth token endpoint. The service-account private key remains encrypted locally and is never exposed as an MCP argument, response, or activity payload.

Highlights in v0.5.10

Silent automatic updates

• the normal first-time/manual Windows installer still uses the familiar NSIS setup wizard;

• downloaded in-app updates now call the NSIS updater in silent mode, so users are no longer asked to click Next, Install, or Finish on every release;

• Lynx still waits for MCP requests, approvals, and agent tasks to become idle before installing;

• after the silent update completes, Lynx automatically restarts into the new version.

Highlights in v0.5.9

CLI account setup, browser authentication, and model preflight

• installed optimized coding CLIs now expose Set up account / Manage account directly inside the Agents page;

• Lynx launches each CLI's own supported authentication flow inside an embedded setup console, so users do not need to know or type provider login commands manually;

• secure HTTPS authentication/device URLs emitted during setup are detected and opened in the system default browser automatically, while device codes remain visible in Lynx;

• billing, payment, pricing, subscription, documentation, and support links are excluded from automatic browser opening;

• OpenCode model discovery now consumes live verbose model metadata to distinguish free, paid, and unknown-pricing models without hardcoding a model list;

• provider sign-in and model entitlement are tracked separately, preventing an authenticated provider from being mistaken for guaranteed access to every listed model;

• free model selections are verified with an isolated no-tool preflight, and selected/default models are checked before a real orchestration task starts;

• billing/subscription failures such as No payment method are surfaced before the Thinker/Planner pipeline starts instead of failing deep inside a task;

• setup and model probes run outside the selected project workspace and do not inspect or modify project files.

Highlights in v0.5.8

UI/UX hardening and frustration reduction

• fatal Gateway and Agents startup failures now show the actual error with a Retry action instead of leaving the user on an endless loading screen;

• clearing Activity history now requires a Lynx confirmation dialog, reports failures through the normal error surface, and clearly states that project files/running requests are unaffected;

• removing a custom CLI now uses the same destructive-action confirmation pattern as workspaces, clients, and integrations;

• the 721-900 px compact-sidebar range now keeps Gateway/Agents mode controls usable and preserves notification badges/tooltips instead of hiding pending-work indicators;

• stale hard-coded v0.5.6 renderer fallbacks were removed; the UI now resolves the installed/updater version dynamically;

• terminal session tabs no longer nest an interactive close control inside another button; selection and Close are separate keyboard-accessible buttons;

• filter tabs, connection/toggle controls, and execution-mode controls expose clearer ARIA state, while confirmation/support modals trap focus and restore focus on close;

• long Adaptive CLI verification no longer globally disables unrelated Agents controls, and Gateway busy states are scoped to the operation/page that owns them;

• secondary/help text was increased where it was excessively small, with consistent focus-visible outlines and recoverable loading-error styling;

• 82 total Vitest checks are expected in the clean release gate: 68 Gateway/Agents/UI regression tests plus 14 Adaptive CLI tests, including 5 dedicated UI-hardening contract tests.

Highlights in v0.5.7

Adaptive CLI Bridge Phase I complete

• the six known task invocation paths are now declarative optimized profiles consumed by one shared builder instead of a product-specific runtime switch;

• a 120-case parity matrix covers Claude Code, Codex CLI, OpenCode, Gemini CLI, Kiro CLI, and GitHub Copilot CLI across all five roles, Safe/Autonomous mode, and with/without explicit model selection, preserving the frozen v0.5.6 invocation behavior exactly;

• deterministic malformed-input fuzzing now covers 500 terminal/nonce cases and 90 callback route/method cases, followed by binary payload and valid-final recovery checks;

• local zero-model-request help probes confirmed the required execution/model/permission surfaces on the installed Claude Code 2.1.226, Codex CLI 0.147.0, OpenCode 1.17.18, Gemini CLI 0.54.4, Kiro CLI 2.16.2, and GitHub Copilot CLI 1.0.78;

• 77/77 Vitest tests now pass: 63 regression tests plus 14 Adaptive CLI tests.

Level 0 native protocols and structured permission automation for unknown TUIs remain separate future capabilities. The Adaptive CLI Bridge v2 implementation checklist is otherwise complete.

Highlights in v0.5.6

Adaptive CLI Bridge - capability-driven BYO CLI automation

• known Claude Code, Codex CLI, OpenCode, Gemini CLI, Kiro CLI, and GitHub Copilot CLI adapters remain optimized fast paths; Lynx does not rip out the working integrations;

• custom executables are no longer permanently terminal-only just because Lynx does not recognize the product name. Lynx inspects safe --version/--help surfaces, builds a conservative adaptive profile, and requires an explicit Verify adaptive model round trip before automation is enabled;

• verified generic Level 1 headless and Level 2 stdin/stdout transports use the same hidden child-process engine as normal Agents tasks. An unknown mock banana-code CLI is covered end-to-end with no product-specific Lynx adapter;

• hidden-TUI Level 3 Agent Callback uses a task-scoped 127.0.0.1 callback, random token/session/nonce, a bounded plain-UTF-8 lynx-emit helper, and process-scoped callback environment values; the callback never routes through the public MCP tunnel;

• Level 4 fallback feeds node-pty output through a headless xterm/VT buffer and extracts only a per-task cryptographic nonce block. Bootstrap instructions intentionally fragment the marker strings so an echoing TUI cannot impersonate a completed response;

• every transport normalizes into a shared AgentEvent contract (capability, status, progress, tool, warning, final, error) before reaching task/UI logic;

• adaptive verification tests workspace mutation only in a disposable temporary directory. If write capability is not proven, the CLI remains limited to prompt-only roles; Lynx never guesses write support;

• learned adaptive profiles persist locally by executable/version fingerprint, automatically invalidate after the executable changes, and downgrade back to re-verification when a verified transport fails in a way that indicates its invocation surface changed;

• no blind TUI Y/approval injection is implemented. Safe/Autonomous flags remain specific to validated known adapters, while unknown TUI permission walls degrade safely instead of bypassing third-party controls;

• 74/74 Vitest tests pass across the Gateway/Agents runtime. Release validation also exercises real lynx-emit callback delivery and native Windows PTY nonce extraction. In headless GitHub Actions, callback delivery is tested directly (CALLBACK_OK_DIRECT) while WinPTY validates the hidden terminal/nonce path (NONCE_OK); a local desktop run additionally verifies the combined ConPTY → lynx-emit path (CALLBACK_OK_PTY).

Level 0 native protocol support (ACP/JSON-RPC/documented local HTTP) remains a future optimization path; v0.5.6 implements and validates Levels 1-4 plus interactive Level 5 fallback.

Highlights in v0.5.5

Secure remote credentials + unattended updates

• integration_create_setup_link creates a random one-time HTTPS credential page that expires after 10 minutes, so you can open it on a phone and send a GitHub/Vercel/Supabase/Neon/Firebase credential directly to Lynx without putting the secret in the MCP chat;

• one-time setup links are invalidated after use, bridge restart, expiry, or repeated failed validation attempts;

• each accepted OAuth client now has an Allow credentials from this client advanced toggle. It is off by default; when enabled, only that client can discover/use integration_save_credential for one-way credential provisioning;

• directly provisioned secrets are validated before storage, encrypted with Electron safeStorage, redacted from Activity, and never readable back through MCP;

• downloaded Lynx updates now install and restart automatically once active MCP requests, pending approvals, and queued/running Agents tasks are idle. The desired bridge-running state is preserved so Lynx resumes it after the updated app starts;

• 62/62 automated tests cover the current release, including the remote setup-token lifecycle.

Highlights in v0.5.4

Background resilience, persistent activity, real support flows, and workspace-isolated parallel Agents

• installed Windows builds can launch Lynx silently at user login, stay available in the system tray after the main window closes, remember an intentionally running bridge, and restore it automatically after relaunch/login;

• a background health watchdog checks the local MCP service and public tunnel, uses bounded recovery/backoff after repeated failures, and re-checks after Windows resumes from sleep;

• Gateway Activity persists the newest 500 bounded records locally, records bridge startup/shutdown lifecycle events, supports free-text search, and exports the current filtered view as sanitized JSON without MCP payloads, project paths, client/session/request identifiers, tokens, or credentials;

• Send feedback and Report an issue open real prefilled GitHub issue drafts. Safe diagnostics are opt-in, and an optional user-selected screenshot is copied to the clipboard for manual paste before submission; Lynx never auto-submits the report;

• Parallel independent tasks is functional in Teams: separate top-level Agents tasks may run concurrently only when they target different saved workspaces, while each task preserves its Thinker → Planner → Implementer → Tester → Reviewer dependency order and Lynx still blocks two mutation pipelines in the same workspace;

• the MCP server/self-description version and desktop release metadata are aligned to v0.5.4.

Highlights in v0.5.3

BYO CLI auth truthfulness and notification-routing reliability

• Windows notification deep-links are now buffered in the preload bridge until the renderer subscribes, so clicking a connection, approval/request, or Agents task notification cannot lose its destination during app/window startup;

• Teams distinguishes credentialed / verified / unverified / unavailable model access instead of treating every CLI-listed model as usable, while CLI default always remains selectable;

• OpenCode model discovery now correlates its live model inventory with providers reported by opencode auth list; credentialed/previously verified models are shown by default and unverified models can be revealed explicitly;

• model-access success/failure state is cached across rescans during the running Lynx session, so a model proven usable or rejected by the current account is not immediately forgotten;

• Gemini CLI readiness now checks its configured local auth type or supported environment credentials without sending an AI/model request, so an installed-but-unauthenticated Gemini no longer appears fully ready;

• authenticated Claude Code model discovery was live-verified against Claude Code 2.1.226 through its screen-reader /model menu without sending an AI prompt; no Claude model names are hardcoded in Lynx;

• built-in Agents continues to expose only first-class automation adapters; unsupported products stay out of the built-in catalog while Custom CLI remains available for terminal-only use.

Highlights in v0.5.2

BYO CLI navigation, live counts, and account-aware model selection

• Windows notifications now deep-link into the exact Lynx surface that owns the event: connection requests open Gateway → Connections, approvals/request activity open Gateway → Activity, and completed/failed agent tasks open Agents → Tasks at the matching item;

• Gateway/Agents mode buttons and the Connections, Activity, and Tasks navigation items show live numeric badges for actionable pending work, including when the sidebar is collapsed;

• agent task success/failure now has a Lynx system notification that opens the exact task, while MCP request-completed notifications remain scoped to observable MCP tool completion rather than claiming semantic client-task completion;

• authenticated Claude Code model choices are discovered dynamically from Claude's own /model UI through its screen-reader terminal mode, without sending an AI prompt or shipping a hardcoded Claude model catalog;

• Refresh CLIs & models is available directly in Teams, and closing an interactive CLI terminal triggers a readiness/model rescan so login/provider/model changes are reflected without restarting Lynx;

• the built-in Agents catalog now advertises only CLIs with an actual Lynx automation adapter: Claude Code, Codex CLI, OpenCode, Gemini CLI, Kiro CLI, and GitHub Copilot CLI. Arbitrary custom executables remain available as clearly labeled terminal-only sessions.

Highlights in v0.5.1

Agents observability, models, readiness, and Windows install hardening

• every orchestrated role step records the exact prompt Lynx sends, assigned CLI/executable, PID, timestamps, live stdout/stderr, model selection, and runtime-limit state;

• CLI readiness now distinguishes installed tools from tools that still need provider/login setup, with zero-request checks for Claude Code, Codex CLI, OpenCode, and Kiro where their CLIs expose a status surface;

• model catalogs are discovered dynamically from the installed CLI instead of hardcoded in Lynx when a stable machine-readable inventory exists (currently OpenCode and Kiro); other adapters keep CLI default and never invent model availability;

• Teams can persist a discovered model per role, while Tasks record selected/reported models, CLI-reported token/cost usage, model-access failures, rate limits, quota exhaustion, and context-limit failures when exposed by the CLI;

• Windows CLI discovery now checks PATH plus per-user install locations used by native/npm/WinGet/pnpm/Scoop/Bun installers, including %USERPROFILE%\\.local\\bin, so successful installs are detected without requiring a full app restart;

• installer terminals automatically rescan after exit, report whether the executable was found, and suppress duplicate concurrent installer tabs for the same CLI;

• Windows install mappings were refreshed against current official instructions, including Anthropic's native Claude Code PowerShell installer and OpenAI's current Codex npm package.

Highlights in v0.5.0

Lynx Agents — real local bring-your-own-CLI runtime

• the approved Gateway / Agents interface is now backed by a real local runtime instead of preview data;

• Rescan CLIs discovers supported executables from PATH and known install locations, probes installed versions, and supports custom executable registration;

• recommended CLI cards expose allowlisted official install commands in a visible Lynx terminal after native confirmation;

• first-class automated adapters cover Claude Code, Codex CLI, OpenCode, Gemini CLI, Kiro CLI, and GitHub Copilot CLI where scripted execution is supported; custom executables remain terminal-only unless a validated adapter exists;

• Teams persist Thinker / Lead, Planner, Implementer, Tester, and Reviewer role assignments without adding an LLM to Lynx;

• Tasks run a deterministic local pipeline through the selected CLIs, including testing, review hand-offs, and bounded revision cycles;

• Safe mode is the default; enabling Autonomous mode requires a native Lynx warning before supported implementation/testing CLIs can use their documented non-interactive permission mode;

• Terminal is now a real multi-session PTY/xterm surface, and the Windows package ships the compatible native PTY runtime explicitly;

• one orchestrated mutation task may run per workspace at a time; dependency-aware parallel scheduling remains intentionally disabled until that scheduler is implemented and validated;

• the existing multi-client MCP Gateway remains independent and unchanged in purpose.

Highlights in v0.4.2

Lynx Agents interface preview

• added the persistent top-level Gateway / Agents mode switch and approved Agents information architecture;

• added the independent Agents sidebar and visual previews that became the foundation of the v0.5.0 runtime;

• no CLI execution was performed by the v0.4.2 preview.

Highlights in v0.4.1

Known-client cleanup

• added Delete client for inactive MCP client identities in the Connections page;

• deletion requires confirmation and is unavailable while the client has active sessions or requests;

• deleting a client removes its OAuth registration/tokens, saved local capability scope, request-limit settings, and explicit workspace grants;

• a deleted application must register and be accepted again before it can use Lynx.

Highlights in v0.4.0

Multi-client MCP gateway

• added desktop Accept / Reject authorization for new MCP applications before tokens become usable;

• preserved previously authorized clients during migration, with an optional re-approval switch;

• added the Connections page with disconnect, revoke, block, pairing, emergency lockdown, client identity, local capability scope, and request-limit controls;

• added Shared / Restricted / Private workspace access with explicit per-client grants;

• added per-client Read only / Developer / Full local capability presets while keeping configured developer integrations globally available to accepted clients;

• added per-client concurrent-request and requests-per-minute ceilings for MCP POST traffic;

• added client-attributed security audit events, approvals, activity filtering, and MCP-session grouping;

• generalized the app and documentation from a Gemini-only bridge to a multi-client gateway for ChatGPT, OpenCode, Gemini, IDEs, CLIs, and other compatible MCP applications;

• upgraded lynx_info and MCP initialization instructions so each accepted client can inspect its current scope, visible workspaces, allowed tool categories, integrations, security rules, and request limits without exposing provider credentials.

Highlights in v0.3.9

Integration readability

• increased provider names, descriptions, setup instructions, field labels, inputs, buttons, and status badge font sizes on the Integrations page;

• slightly increased integration card spacing and logo sizing while preserving the existing responsive two-column layout;

• retained provider credential validation before credentials are saved.

Highlights in v0.3.8

Dedicated integrations and Firebase

• moved optional developer providers into a dedicated Integrations sidebar tab instead of Getting Started or Settings;

• added provider logos for GitHub, Vercel, Supabase, Neon, and Firebase;

• added Firebase service-account authentication with encrypted local storage and short-lived Google OAuth access tokens;

• added Firebase project, Hosting, Firestore, and advanced allowlisted REST MCP tools with approval and activity redaction safeguards;

• added Firebase credential/OAuth tests and expanded MCP tool coverage.

Highlights in v0.3.6

Live MCP activity stream redesign

• redesigned the Activity request list into a clearer live request stream with stronger row hierarchy and more readable spacing;

• active and pending requests now use a subtle live indicator and clearer Live / Waiting status labels;

• request rows separate workspace, tool, status, start time, and duration instead of compressing everything into one line;

• expanded request details remain available while improving truncation and responsive behavior for smaller windows;

• the redesigned activity stream uses the shared Light / Dark theme variables and preserves existing filters, activity tracking, and payload inspection behavior.

Highlights in v0.3.5

Lynx brand identity

• added the new transparent Lynx logo across the Windows app executable, installer, uninstaller, taskbar/window icon, system tray, renderer favicon, and sidebar branding;

• normalized the logo into a tightly framed square asset so it stays legible at Windows icon sizes;

• replaced the old generic tray image and the sidebar letter mark with the Lynx brand logo.

Highlights in v0.3.4

In-app confirmation modal

Destructive actions now use a Lynx-styled confirmation modal instead of the generic browser confirmation dialog.

• workspace removal opens a themed Light / Dark confirmation modal;

• the modal shows the exact workspace path and clearly states that project files stay on disk;

• if Gemini currently has the workspace selected, the modal explains what happens to that session before removal;

• Cancel receives initial focus for safer destructive actions;

• Escape or clicking the backdrop cancels the action;

• the reusable confirmation component can be used by future destructive actions instead of window.confirm().

Highlights in v0.3.3

Persistent light / dark appearance

Lynx now has a one-click Light / Dark appearance toggle at the bottom of the sidebar.

• the selected theme is persisted in Lynx's existing local settings;

• Electron applies the theme before creating the window to avoid a mismatched startup background;

• the full renderer uses shared semantic theme variables, including cards, approvals, activity, workspaces, inputs, badges, and settings controls;

• collapsed-sidebar mode keeps the appearance control available as a compact sun/moon icon;

• the active navigation state is flatter and more desktop-tool-like, with a subtle background and thin left indicator instead of the previous outlined pill.

Multi-workspace project routing

Lynx can save multiple local projects behind one MCP gateway and expose them to multiple accepted MCP applications.

Lynx
  |-- SPARK_MCP
  |-- AGMS_WEB
  |-- AGMS_MOBILE
  `-- other saved projects

Each MCP session has one selected workspace context at a time. An accepted client can switch between folders that the user explicitly added and granted to it without restarting the bridge.

Lynx advertises workspace-routing instructions during MCP initialization and exposes these read-only/context tools:

• lynx_info — describes Lynx capabilities and workspace rules.

• list_workspaces — lists only folders explicitly saved in Lynx.

• select_workspace — selects a saved project by exact name or ID for the current MCP session.

• workspace_info — returns metadata about the currently selected workspace.

Example:

User: Work only on SPARK_MCP.
MCP client -> select_workspace("SPARK_MCP")
MCP client -> read_file(...)
MCP client -> edit_file(...)
MCP client -> run_command(...)

All later project tools in that MCP session resolve against the selected workspace until the client explicitly selects another one.

Lynx never gives an accepted MCP client permission to scan arbitrary folders outside the workspace registry and that client's workspace grants.

Workspace management

The Workspace page supports:

• adding multiple project folders;

• selecting a default workspace for new MCP sessions;

• renaming a saved workspace label;

• removing a workspace from Lynx without deleting project files;

• showing whether one or more MCP sessions currently have a workspace selected;

• showing active request counts per workspace;

• opening activity filtered to a specific workspace;

• detecting whether each project is a Git repository.

Changing the default workspace does not silently move an already-running MCP session to another project. Existing sessions keep their own workspace context until select_workspace changes it.

Git awareness without forcing Git

Lynx checks each saved workspace using Git and displays one of these states:

• Git repository — the workspace matches the repository root.

• Inside Git repository — the folder is inside a larger Git repository.

• No Git repository — normal file tools still work; Lynx only shows a warning.

• Git unavailable — Git may not be installed or accessible.

Git is recommended because it gives better history, diff review, rollback, and change control, but Lynx does not require a project to use Git for normal file editing.

Dedicated Git mutation tools keep stricter repository-root checks.

Workspace-aware Activity inspector

Every observable MCP transaction is tagged with its workspace when a workspace context exists.

The Activity page can be filtered first by project and then by status:

Workspace
[All workspaces] [SPARK_MCP] [AGMS_WEB] [AGMS_MOBILE]

Status
[All] [Ongoing] [Done] [Failed]

Captured activity can include:

• workspace name and root;

• MCP method;

• tool name;

• JSON-RPC request ID;

• MCP session ID;

• protocol version;

• request arguments;

• bounded request/response payloads;

• HTTP status;

• start/finish timestamps;

• duration;

• approval state;

• errors.

Lynx does not expose a connected client's hidden reasoning, model state, or chain of thought. It only shows protocol/tool traffic visible to the MCP gateway.

Captured request and response payloads are bounded, authorization headers are not captured, and OAuth/ngrok credentials are not written into the activity inspector.

Request lifecycle notifications

Lynx can send Windows notifications for MCP tool activity and agent-task completion. Clicking a Lynx notification focuses/opens the app, switches to the owning Gateway or Agents surface, navigates to the relevant tab, scrolls to the matching request/task when it is still present, and briefly highlights it.

Settings include separate controls for:

• Approval notifications — a risky operation is waiting for Allow / Reject.

• Request started notifications — an MCP tool request begins. Off by default to reduce noise.

• Request completed notifications — an MCP tool request succeeds or fails. On by default.

Example:

Lynx · Request done
edit_file completed · SPARK_MCP · 842 ms

A completed notification means that a request/tool response Lynx can observe has finished. It does not claim that the connected application's entire conversational or agent task is complete, because MCP does not provide Lynx with a universal semantic end-of-task event.

Approval modes

Lynx has two local approval policies:

Review requests

• write/delete/command/Git/network requests enter the Lynx approval queue;

• the GUI shows Allow and Reject;

• approval cards include the affected workspace name and root;

• optional Windows approval notifications open Gateway → Activity at the matching approval card.

Always approve

• Lynx automatically passes its own local approval gate;

• there is no Lynx approval popup for supported risky operations;

• workspace sandboxing, authentication, command limits, Git checks, and activity logging still remain active.

A connected MCP application may still show its own confirmations or policy UI. Lynx cannot disable confirmation prompts enforced by the client application itself.

Persistent desktop bridge

Lynx is designed to run as a background Windows tray application.

• Closing the main window hides Lynx instead of stopping the bridge.

• MCP and the active tunnel continue running from the tray.

• Opening Lynx again restores the dashboard.

• Stop Bridge intentionally stops MCP/tunnel access.

• Quit Lynx exits the application.

• Installed Windows builds can launch at login.

Lynx also persists accepted MCP client OAuth registration/token state locally so restarting the application does not normally require re-authorizing previously accepted clients.

A new MCP transport session is naturally created after a full process restart, but accepted client registration and authorization can be reused.

Automatic updates

Installed builds use GitHub Releases for in-app updates.

Lynx:

• checks for updates shortly after startup;

• checks again periodically while running;

• downloads compatible releases in the background;

• shows update state in the About page;

• automatically installs and restarts once MCP requests, pending approvals, and queued/running Agents tasks are idle;

• preserves the bridge-running preference so an intentionally running bridge resumes after the updated app starts;

• keeps the manual install-now action only as an optional fallback.

Updates replace application files but preserve the same local user-data identity. Existing settings remain available after an upgrade, including:

• ngrok token;

• workspace registry;

• default workspace;

• approval policy;

• notification preferences;

• tunnel provider;

• encrypted MCP client OAuth registration/token state;

• bridge resume preference.

Updater releases publish the installer, .blockmap, latest.yml, and SHA256SUMS.txt through GitHub Actions.

Main UI sections

Lynx Agents

The top-level Agents mode provides a local bring-your-own-CLI runtime with CLI discovery/install actions, persisted team roles, orchestrated task execution, real PTY terminal sessions, agent-specific activity, workspace reuse, and Safe / Autonomous execution settings. Lynx itself still has no integrated LLM and uses each installed CLI's existing login/account.

Overview

Shows bridge state, current/default workspace information, approval policy, recent activity metrics, public MCP URL, and bridge controls.

Activity

Workspace-aware MCP inspector with live request lifecycle, status filters, expandable payload details, timing, response/error information, and approval records.

Workspace

Manage saved projects, default workspace selection, Shared / Restricted / Private access, client grants, in-use indicators, Git state, activity counts, renaming, removal, and direct activity filtering.

Connections

Review pending MCP applications, Accept / Reject new connections, inspect known client identities, disconnect sessions, revoke or block clients, set Read only / Developer / Full local capability scopes, tune request ceilings, control pairing, require legacy re-approval, and trigger Emergency Lockdown.

Integrations

Configure and validate optional GitHub, Vercel, Supabase, Neon, and Firebase credentials. Integrations are Lynx-wide capabilities for accepted clients and follow the global integration approval setting. For remote use, an accepted client can request a one-time setup URL so the credential is submitted directly from your phone/browser to Lynx. A separate per-client advanced toggle can opt a trusted client into one-way direct credential provisioning; stored secrets remain unreadable through MCP.

Getting Started

Guided local setup for tunnel provider, ngrok token when needed, workspace setup, bridge startup, and connection of any compatible MCP client. Gemini remains available as a convenience shortcut, not as the only supported client.

Settings

Controls:

• tunnel provider;

• persistent Light / Dark appearance from the sidebar footer;

• Review requests / Always approve;

• approval notifications;

• request-start notifications;

• request-completed notifications.

About

Displays:

• what Lynx is;

• current application version;

• author: Domincee;

• Windows/system information;

• CPU architecture;

• Electron version;

• repository link;

• updater controls;

• Feedback and Report UI placeholders.

Tunnel providers

Lynx supports:

ngrok

Recommended when you want a more stable public MCP URL, especially for cloud-hosted MCP clients.

The @ngrok/ngrok runtime is embedded. A separate global ngrok CLI installation is not required.

The user's ngrok authtoken is encrypted locally with Electron safeStorage and is never returned to the renderer after storage.

localhost.run

Alternative SSH reverse-tunnel provider that does not require an ngrok account. It requires a working local SSH/OpenSSH client.

localhost.run URLs are temporary and can change when the tunnel restarts, so connected MCP applications may need their Lynx endpoint updated after a restart.

Auto

Uses ngrok when configured/available and can fall back to localhost.run when appropriate.

MCP tools

Lynx / workspace routing

Files and search

Commands

Command execution uses the current user's normal OS permissions. It is not an OS-level security sandbox. Review Requests is therefore recommended unless full local autonomy is intentional.

Git

Lynx intentionally does not expose dedicated force-push, reset --hard, clean -fd, or branch deletion tools. Credential setup is limited to a short-lived one-time browser flow plus an explicitly enabled per-client one-way provisioning tool; Lynx never exposes a credential readback tool.

Workspace security model

The selected MCP workspace is the primary file-tool security boundary.

File operations:

1. resolve the requested path relative to the selected workspace;

2. canonicalize/realpath relevant path components;

3. reject traversal outside the root;

4. reject symlink/junction escapes;

5. apply file/output limits.

Workspace selection itself is restricted to folders explicitly saved by the user in Lynx.

The bridge binds locally to 127.0.0.1 and uses a public HTTPS tunnel only when a remote/cloud MCP client needs to reach the authenticated MCP endpoint.

Authentication

Lynx implements standards-based MCP authorization for compatible MCP clients, including:

• OAuth discovery metadata;

• Dynamic Client Registration;

• Authorization Code flow;

• PKCE;

• access tokens;

• refresh tokens;

• encrypted persistent OAuth state.

OAuth state and other sensitive settings are stored locally using Electron/Windows-backed secure storage where applicable.

Installation

Download the latest Windows installer from:

https://github.com/DominceAseberos/Lynx_MCP/releases/latest

Installer naming:

Lynx-Setup-<version>.exe

Windows SmartScreen may warn about unsigned builds until the project is distributed with a trusted code-signing certificate.

First-time setup

1. Install and open Lynx.

2. Choose a tunnel provider.

3. If using ngrok, save your ngrok authtoken.

4. Add one or more local workspaces.

5. Choose a default workspace.

6. Click Start Bridge.

7. Copy the generated /mcp URL.

8. In ChatGPT, OpenCode, Gemini, an IDE, CLI, or another compatible MCP application, add the Lynx MCP URL.

9. When the application requests authorization, review its name/redirect context in Lynx and choose Accept or Reject.

10. After acceptance, use Lynx tools from that client. Configure workspace access, local capability scope, and request ceilings from Connections as needed.

After the first accepted connection, Lynx persists local configuration and OAuth registration so normal window closes/reopens and application restarts do not require rebuilding that client authorization from scratch.

Example multi-project workflow

With these projects saved:

SPARK_MCP
AGMS_WEB
AGMS_MOBILE

Any connected MCP client can be instructed like:

Use Lynx. Work only on AGMS_MOBILE and inspect the Flutter app.

The client can discover only the workspaces it is allowed to see, select AGMS_MOBILE, and all following file/search/edit/command/Git calls will use that workspace until the project context is changed.

For ambiguous project names, Lynx instructions tell the MCP client not to silently guess.

Development

Requirements:

• Node.js

• npm

• Windows is the primary packaged target

Install dependencies:

npm install

Run the Electron development build:

npm run dev

In VS Code, the launch configuration is named:

Lynx: Dev

Validation

Run:

npm run typecheck
npm run lint
npm test
npm run build

Current automated coverage includes:

• workspace sandbox behavior and symlink/junction escape rejection;

• Shared / Restricted / Private workspace ACL filtering;

• file editing behavior;

• OAuth/DCR/PKCE flow, pending Accept / Reject authorization, and state restoration;

• per-client local capability policy enforcement;

• per-client concurrent/rate request limits;

• multi-workspace discovery and select_workspace routing;

• client-aware lynx_info instructions and scope reporting;

• MCP tool calls and emergency-lockdown rejection;

• tunnel behavior;

• bounded command execution;

• Git status/add/commit/branch/push behavior and repository-root safety;

• provider credential handling, integration redaction, Firebase OAuth, one-time remote credential setup, opt-in one-way secret provisioning, and cross-provider provisioning;

• Windows notification deduplication and lifecycle behavior;

• Agents CLI catalog/install-command regression coverage;

• custom local CLI discovery/version probing;

• Safe/Autonomous adapter invocation behavior for supported CLI roles;

• durable Activity persistence and sanitized-export privacy rules;

• Agents same-workspace serialization and cross-workspace parallel-task gating.

v0.5.4 local validation: 59/59 tests passed, plus lint, TypeScript typecheck, and the production Electron/Vite build. The tagged GitHub Actions Windows runner is the final NSIS installer/package gate and publishes the updater assets.

Build the installer

npm run dist

Output:

release/Lynx-Setup-<version>.exe

Unpacked application:

release/win-unpacked/Lynx.exe

Releases

GitHub Actions builds the Windows installer for release tags.

Release workflow:

push v* tag
    |
    v
install dependencies
    |
    v
tests + lint
    |
    v
Electron/NSIS package
    |
    +-- Lynx-Setup-<version>.exe
    +-- Lynx-Setup-<version>.exe.blockmap
    +-- latest.yml
    +-- SHA256SUMS.txt
    |
    v
GitHub Release

electron-builder itself is configured not to publish implicitly during the package step; the GitHub Actions workflow owns release publication.

Local persistence and upgrades

The visible product was renamed to Lynx, but the application intentionally keeps its original internal app identity/user-data location so existing users do not lose settings during the rename.

On Windows, current settings are kept under the existing Lynx/Spark bridge user-data location based on:

%APPDATA%\spark-mcp-bridge

Do not rename or migrate this directory casually without an explicit migration strategy. It contains persistent application state required for seamless upgrades.

Important limitations

• Compatibility details, client-side confirmations, and MCP support can change independently in ChatGPT, OpenCode, Gemini, IDEs, CLIs, and other client applications.

• Lynx can observe MCP request/tool lifecycle, not a client's hidden model reasoning or a guaranteed end-of-conversation-task event.

• Application names/logos are recognition metadata; authorization is bound to Lynx's OAuth client identity and tokens.

• run_command executes with the user's normal OS permissions after Lynx policy approval; Lynx is not an OS-level sandbox.

• tunnel URLs may change after restart or automatic recovery depending on the provider; clients configured with an old temporary URL may need to be updated.

• An actual process restart creates new MCP transport sessions even though accepted client OAuth registrations can persist.

• Shared/Restricted/Private access protects the Lynx workspace catalog; it does not create Windows user-account isolation between processes running under the same OS account.

• This is personal local gateway/orchestration software, not a hosted multi-user collaboration or enterprise IAM platform.

• Lynx Agents may run independent top-level tasks concurrently across different saved workspaces when enabled, but each individual task still executes its role dependencies deterministically and Lynx never overlaps two orchestrated mutation tasks in the same workspace.

• Background mode is a per-user Windows tray process rather than a machine-level Windows Service; the Windows user must remain signed in for Lynx to stay reachable.

Privacy and local data

Lynx has no custom hosted backend for project contents, settings, or activity.

Local data includes:

• workspace registry;

• application preferences;

• encrypted ngrok token when configured;

• encrypted OAuth registration/token state;

• bridge resume preference.

Activity keeps the newest 500 records locally so recent Gateway history survives app restarts. Captured request/response fields are bounded to 32 KiB each, authorization headers/tokens are not captured, and sanitized JSON export deliberately omits payloads, project paths, client/session/request identifiers, and credentials.

Repository

https://github.com/DominceAseberos/Lynx_MCP

Author

Created and maintained by Domincee.

References

Example MCP client documentation (Gemini convenience path):

• https://support.google.com/gemini/answer/17209137

• https://support.google.com/gemini/answer/17094507

• https://support.google.com/gemini/answer/17171264

Model Context Protocol:

• https://modelcontextprotocol.io/specification/2025-11-25

• https://modelcontextprotocol.io/specification/2025-11-25/basic/transports

• https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization

• https://modelcontextprotocol.io/specification/2025-11-25/server/tools

• https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices

• https://modelcontextprotocol.io/docs/sdk

Lynx v0.5.4 — local multi-client MCP gateway plus a bring-your-own-CLI Agents runtime with background bridge recovery, persistent searchable Activity, sanitized export, real GitHub support drafts, and workspace-isolated parallel tasks.