Lynx

Lynx is a Windows-first local MCP bridge that lets Gemini Spark work with development projects on your computer 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.3.6

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

Gemini runs in the cloud, while your projects stay on your computer. Lynx provides the authenticated MCP endpoint between them:

Gemini Spark
    |
    | MCP over HTTPS
    v
ngrok / localhost.run tunnel
    |
    v
Lynx on 127.0.0.1
    |
    +-- OAuth / PKCE / client registration
    +-- Workspace routing
    +-- File tools
    +-- Search tools
    +-- Bounded command execution
    +-- Git tools
    +-- Approval policy
    +-- Activity inspector
    +-- 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.

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 under one connected Gemini custom app.

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

Each Gemini MCP session has one selected workspace context at a time. Gemini can switch between folders that the user explicitly added to Lynx 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.
Gemini -> select_workspace("SPARK_MCP")
Gemini -> read_file(...)
Gemini -> edit_file(...)
Gemini -> run_command(...)

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

Lynx never gives Gemini permission to scan arbitrary folders outside the workspace registry.

Workspace management

The Workspace page supports:

• adding multiple project folders;
• selecting a default workspace for new Gemini sessions;
• renaming a saved workspace label;
• removing a workspace from Lynx without deleting project files;
• showing whether Gemini currently has 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 Gemini 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 Gemini's hidden reasoning or internal model state. It only shows traffic visible to the MCP bridge.

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.

Settings include separate controls for:

• Approval notifications — a risky operation is waiting for Allow / Reject.
• Request started notifications — a Gemini tool request begins. Off by default to reduce noise.
• Request completed notifications — a Gemini 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 Gemini's entire conversational task is complete, because Gemini does not provide Lynx with a universal 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 bring Lynx to the foreground.

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.

Gemini may still show confirmations enforced by Google's own client. Lynx cannot disable Gemini-side UI confirmations.

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 Gemini OAuth registration/token state locally so restarting the application does not normally require recreating the Gemini custom app.

A new MCP transport session is naturally created after a full process restart, but the Gemini app 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;
• provides Update & Restart when a release is ready.

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 Gemini OAuth state;
• bridge resume preference.

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

Main UI sections

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, Gemini-selected/in-use indicators, Git state, activity counts, renaming, removal, and direct activity filtering.

Getting Started

Guided local setup for tunnel provider, ngrok token when needed, workspace setup, bridge startup, and Gemini custom-app connection.

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 for a stable Gemini MCP URL when using a dedicated ngrok development domain.

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 Gemini may need its MCP URL updated after a restart.

Auto

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

MCP tools

Lynx / workspace routing

Tool	Risk	Purpose
lynx_info	Read-only	Describe Lynx capabilities and current workspace-routing rules.
list_workspaces	Read-only	List project roots explicitly saved in Lynx.
select_workspace	Read-only context change	Select a saved workspace for the current MCP session.
workspace_info	Read-only	Inspect the selected workspace.

Files and search

Tool	Risk	Purpose
list_files	Read-only	Bounded directory listing in the selected workspace.
read_file	Read-only	Bounded UTF-8 file reading.
search_text	Read-only	Bounded text search inside the selected workspace.
write_file	Write	Create or replace a text file after local policy approval.
edit_file	Write	Exact old-text/new-text replacement after local policy approval.
create_directory	Write	Create a directory in the workspace.
delete_path	Destructive	Delete a file/directory with explicit safeguards.

Commands

Tool	Risk	Purpose
run_command	High risk	Run a bounded local shell command with the selected workspace as cwd.

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

Tool	Risk	Purpose
git_status	Read-only	Branch and working-tree status.
git_diff	Read-only	Staged or unstaged diff.
git_log	Read-only	Recent bounded history.
git_branches	Read-only	Local/remote branches.
git_add	Write	Stage paths.
git_commit	Write	Commit staged changes.
git_switch	Write	Switch/create a branch.
git_pull	Network/write	Pull from a remote.
git_push	Network/write	Push to a remote.

Lynx intentionally does not expose dedicated force-push, reset --hard, clean -fd, branch deletion, or credential-management tools.

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 so Gemini's cloud client can reach the authenticated MCP endpoint.

Authentication

Lynx implements standards-based MCP authorization for the Gemini custom-app flow, 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 Gemini web, open Connected Apps and add a custom app for Spark.
9. Paste the Lynx MCP URL and complete Gemini's authorization flow.
10. Start using the Lynx app from Gemini.

After the first connection, Lynx persists local configuration and OAuth registration so normal window closes/reopens and application restarts do not require rebuilding the Gemini custom app from scratch.

Example multi-project workflow

With these projects saved:

SPARK_MCP
AGMS_WEB
AGMS_MOBILE

A Gemini conversation can say:

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

Gemini can discover the saved project list, 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;
• path traversal rejection;
• file editing behavior;
• OAuth/DCR/PKCE flow;
• OAuth state restoration;
• multi-workspace discovery and select_workspace routing;
• MCP tool calls;
• tunnel behavior;
• bounded command execution;
• Git status/add/commit/branch/push behavior;
• Git repository-root safety.

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

• Gemini Spark/custom MCP support is controlled by Google and can change independently of Lynx.
• Gemini-side confirmation UI is outside Lynx's control.
• Lynx can detect MCP request/tool lifecycle, not Gemini's hidden model reasoning or a guaranteed end-of-conversation-task event.
• run_command executes with the user's normal OS permissions after Lynx policy approval.
• localhost.run tunnel URLs may change after restart.
• An actual process restart creates a new MCP transport session even though Gemini OAuth/app registration can persist.
• This is a personal local bridge, not a multi-user authorization or hosted collaboration platform.

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 records are currently kept in application memory and are bounded. Sensitive authorization headers/tokens are not captured in the inspector.

Repository

https://github.com/DominceAseberos/Lynx_MCP

Author

Created and maintained by Domincee.

References

Gemini / Spark:

• 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.3.6 — local Gemini MCP bridge for multi-project development.