The Bridge

A native macOS menu-bar app that turns your Mac into an MCP server for Notion AI agents and local coding clients.

The Bridge exposes local Mac capabilities and connected services as MCP tools over Streamable HTTP, legacy SSE, and stdio. It is built in Swift 6.2 for macOS 26+ on Apple Silicon and is designed to be always-on, auto-launched, and safe enough for daily operator use.

~173 tools across 25 module groups · 3 transports · 3-tier security model · Customer-owned Cloudflare Tunnel support · Liquid Glass UI (v3.6+)

Latest release: v3.6.0 — Liquid Glass complete (May 2026). Existing v3.4.x installs auto-update via Sparkle.

Product page: https://kup.solutions/notion-bridge

Naming history: "NotionBridge" was the product's original name. As of v3.6.0 the user-facing brand is The Bridge. The Swift target, bundle identifier (kup.solutions.notion-bridge), and Keychain service name (com.notionbridge) are intentionally preserved — that keeps existing user data continuous across the rename.

---

What this repo is

This is the product repository for The Bridge (Swift target name NotionBridge).

It is not a generic Swift experiment and it is not an open-source demo server. It is the source-available codebase for a commercial macOS product that bridges Notion agents, local coding tools, and the user's Mac.

Current commercial posture:

• Direct purchase is the primary distribution path.
• No free tier is planned.
• Setapp distribution may follow later.

---

Current product surface

The Bridge currently ships ~173 tools organized into 25 module groups, surfaced collapsibly in Settings → Tools (PKT-877 ModuleGroup UI). Highlights below; the full registry is in-app.

Module	Tools	Notes
ShellModule	2	shell execution and approved scripts
FileModule	12	files, directories, metadata, clipboard
MessagesModule	6	iMessage and SMS read/send tooling
SystemModule	3	system info, processes, notifications
ContactsModule	4	CNContactStore search, get, resolve — no Contacts.app required
NotionModule	21	Notion pages, blocks, databases, data sources, comments, files, queries
SessionModule	3	session status and tool registry introspection
AppleScriptModule	1	in-process AppleScript execution
AccessibilityModule	5	AX tree, inspection, and actions
ScreenModule	5	capture, OCR, recording, screen analysis
ChromeModule	5	tabs, navigation, page reads, JS, screenshots
CredentialModule	4	Keychain-backed credential storage
PaymentModule	1	Stripe payment execution
SkillsModule	3	fetch_skill, list_routing_skills, manage_skill
ConnectionsModule	5	connection inventory, health, validation
BuiltinModule	1	echo (registered in ServerManager, not a Swift *Module type)
Total	~173	Across 25 ModuleGroups. Includes dynamic Stripe MCP tools (currently 26 when configured) and the v3.5+ additions: CommandStore (10-slot favorites), StandingOrders (per-client overlays), JobsManager (launchd-backed schedules), Git/Gh, BgProcess, LSP, Snippets, Dev, DevServer, Lighthouse, Playwright, Vitest, Wrangler

Core product traits:

• Native macOS menu-bar app with onboarding, settings, and a status popover
• Liquid Glass UI (v3.6+) — BridgeGlassCard, BridgeGlassBubble, dep-link chips, ModuleGroup cards, Standing Orders composer with per-client overlays
• Command Bridge popup — global hotkey (⌃⌥⌘C default) opens a bottom-anchored SwiftUI tray with 10 favorite-slot bubbles + substring search + recents
• Auto-launch via SMAppService
• Streamable HTTP and legacy SSE on the same local server surface
• stdio support for local clients such as Claude Code and Cursor
• Local-first security gate with audit logging + dispatch fail-closed (disabled tool groups return typed BridgeToolError.moduleGroupDisabled, never silent failure)
• Optional remote access through a customer-owned Cloudflare Tunnel

---

Installation

Option 1: Download a release

1. Download the latest DMG from GitHub Releases.
2. Open the DMG.
3. Drag The Bridge (NotionBridge.app in the DMG; renamed on install) into /Applications.
4. Launch the app and complete onboarding.

Option 2: Build from source

git clone https://github.com/KUP-IP/the-bridge.git
cd Notion-bridge
make app

The app bundle is written to .build/NotionBridge.app.

Install naming: The Swift target is NotionBridge (no space), so build output and DMG contents use NotionBridge.app. The Finder display name is Notion Bridge (with space), set by CFBundleName / CFBundleDisplayName in Info.plist. make install places the app at /Applications/The Bridge.app to match the display name. Both names refer to the same product.

---

Requirements

Requirement	Version	Notes
macOS	26.0+	Tahoe or later
Hardware	Apple Silicon	ARM64 only
Xcode	26.0+	Needed for building from source
Swift	6.2+	Defined by Package.swift
Git	2.39+	For cloning and release workflows

---

Configuration

Primary configuration path:

~/.config/notion-bridge/config.json

The Bridge supports:

• Notion workspace connections
• connection health checks
• customer-owned remote-access configuration
• local security preferences

If you are using Notion tools, add a valid Notion integration token through the app's connection flow or config file.

Factory reset (Settings → Maintenance)

Factory Reset clears local config, Keychain entries for The Bridge, resets macOS permissions for the app, and reloads in-memory workspace connection state. Skills are cleared to an empty list.

Credentials (Settings → Credentials) are opt-in: enable “Keychain credentials & MCP tools” to use credential_* and payment_execute with stored payment methods. When disabled, those MCP tools are omitted from listings and fail closed if called.

If you launch the app with NOTION_API_TOKEN or NOTION_API_KEY set in the environment, Notion can still resolve a token after reset (that path is intentional for developers). Unset those variables when testing a truly empty workspace. Restart the app after reset so permission and connection UIs stay consistent.

---

Transport surface

Streamable HTTP

POST http://127.0.0.1:9700/mcp

This is the primary HTTP MCP endpoint. The listener is bound to loopback only. For remote agents (e.g. cloud IDEs) that reach your Mac through an HTTPS tunnel to that port, set Settings → Connections → Remote access → Tunnel URL to your tunnel’s base URL (for example https://xyz.trycloudflare.com). That extends Streamable HTTP Origin / Host validation to include the tunnel hostname while keeping the default localhost-only behavior when the field is empty.

Remote MCP security

When a tunnel URL is set, POST /mcp requires a configured MCP remote token in the same settings section (generate/copy there) and matching Authorization: Bearer … in your MCP client. Without a token, new MCP sessions are rejected (fail closed). With an empty tunnel URL, local use is unchanged and a bearer is optional (you can still set a token to harden localhost-only clients). Tokens are stored in the Keychain in the app; com.notionbridge.mcpBearerToken remains a legacy read path. For defense in depth at the edge, operators can put Cloudflare Access in front of the tunnel hostname — see docs/operator/cloudflare-access-notion-bridge.md. Browser-based clients such as Claude chat generally cannot supply Cloudflare service-token headers, and Cloudflare browser challenges or Browser Integrity Check on /mcp can block valid MCP traffic before it reaches the app. In that case, use a narrow path-scoped bypass for POST /mcp and rely on the NotionBridge bearer token at the app layer.

Legacy SSE

GET  http://127.0.0.1:9700/sse
POST http://127.0.0.1:9700/messages

This is retained for clients that still use split SSE transport behavior.

stdio

Use stdio when connecting local clients such as Claude Code or Cursor directly to the app process.

Using Bridge with Antigravity

Google Antigravity enforces a strict 100-tool limit per MCP server, whereas The Bridge exposes ~173 tools. To use Bridge with Antigravity, we have curated a subset of ~84 tools to stay under the limit.

You can launch the Bridge process with a --multi-instance flag (bypasses single-instance GUI guard) and --allow-tools flag pointing to the Antigravity allowlist:

{
  "mcpServers": {
    "Bridge MCP": {
      "command": "/path/to/NotionBridge",
      "args": [
        "--multi-instance",
        "--allow-tools",
        "/path/to/the-bridge/configs/antigravity-allowlist.json"
      ]
    }
  }
}

---

Security model

The Bridge currently uses a 3-tier execution model:

• Open
  • Executes immediately
  • Intended for read-only or low-risk operations
• Notify
  • Executes immediately
  • Sends a post-execution macOS notification
• Request
  • Requires explicit approval before execution
  • Used for sensitive or high-impact actions

The security gate also enforces command-aware escalation rules, sensitive-path handling, and handoff behavior for commands that should not run automatically.

---

Permissions

Depending on the tools you use, The Bridge may require:

• Auto-prompted on first launch: Contacts, Notifications, and Automation target registration
• Manual in System Settings: Accessibility, Screen Recording, and Full Disk Access
• Separate grants for Contacts privacy access and Automation access to Contacts.app

The onboarding flow and Settings window surface current grant state, trigger native prompts when macOS allows it, and deep-link to recovery panes when manual re-authorization is required.

---

Build and test

make build
make test
make app
make dmg

Other useful targets:

make clean
make install
make install-copy    # or: make install-agent-safe — copy .app to /Applications without full notarize (agent-safe)
make release

Sparkle cache-busting is handled at the app level via httpHeaders (PKT-431). Pre-release manual QA: docs/pre-ship-qa-checklist.md. Local MCP smoke (app running): python3 scripts/qa_local_mcp_smoke.py.

---

Repo structure

the-bridge/
├── NotionBridge/
│   ├── App/
│   ├── Config/
│   ├── Modules/
│   ├── Notion/
│   ├── Security/
│   ├── Server/
│   └── UI/
├── NotionBridgeTests/
├── .github/
├── Package.swift
├── Makefile
├── README.md
├── SECURITY.md
└── AGENTS.md

---

Security disclosures

Report security issues per SECURITY.md (scope, out-of-scope, and contact).

Public updates (Sparkle)

The app’s SUFeedURL (see Info.plist) points at the Sparkle appcast (appcast.xml). For automatic updates to work for end users, that URL must return valid XML without logging into GitHub:

• Option A — Public GitHub repo: Keep the default https://raw.githubusercontent.com/KUP-IP/the-bridge/main/appcast.xml and set the repository to public (anonymous curl / incognito browser must show XML).
• Option B — Private repo: Host appcast.xml at any public HTTPS URL you control (e.g. CDN or static site), then set SUFeedURL to that URL and ship a new build. The file must match the repo’s generated appcast (make dmg / make appcast); length and sparkle:edSignature must match the exact DMG you publish.

Verify locally: make check-appcast (committed appcast.xml vs Info.plist), then make verify-sparkle-feed (reads SUFeedURL from Info.plist and curls the live feed).

Purchase download (kup.solutions)

Stripe fulfillment uses the Cloudflare Worker in the kup.solutions repo (workers/nb-fulfillment). After each release:

1. Run make dmg in this repo — artifact is .build/the-bridge-v$(VERSION).dmg, where VERSION is CFBundleShortVersionString in Info.plist (same as DMG_NAME in the Makefile).
2. Upload that file to R2 bucket nb-downloads with object key DMG_OBJECT_KEY from kup.solutions/workers/nb-fulfillment/wrangler.toml (must match the filename exactly).
3. Deploy the worker if DMG_OBJECT_KEY changed: cd workers/nb-fulfillment && npx wrangler deploy --env production.

Until the new object exists in R2, paid downloads return 500 (“Download artifact not found”).

License and distribution

The Bridge is source-available commercial software.

This repository is licensed under the KUP Solutions Source-Available License (Version 1.0, April 2026). You may view and reference the source code. Copying, modification, redistribution, derivative works, and commercial use are prohibited without written permission from KUP Solutions.

See LICENSE for the full license text. See also PRIVACY.md and TERMS.md.

Commercial use

For commercial use of The Bridge, a separate Commercial Use License is required. See COMMERCIAL_LICENSE.md for the full terms and purchase at thebridge.kup.solutions/pricing.

---

LSP server prerequisites (optional, for lsp_* tools)

The lsp_* tools (PKT-745, v2.2 · 2.3) wrap external Language Server Protocol implementations. The tools register and report capability_missing if the underlying servers are absent, so they are safe to leave uninstalled — they only become functional once the matching server is on disk. (The Bridge's Tools group lsp cleanly fails-closed via BridgeToolError.moduleGroupDisabled when the operator toggles the entire group off in Settings.)

Language	LSP server	Install
TypeScript / JavaScript	typescript-language-server	npm install -g typescript-language-server typescript
Swift	sourcekit-lsp	Ships with the Xcode toolchain (/Applications/Xcode.app/...). Falls back to Command Line Tools (xcode-select --install).

Probe-supported install locations (checked in order):

• typescript-language-server: /opt/homebrew/bin, /usr/local/bin, ~/.npm-global/bin, ~/.local/bin
• sourcekit-lsp: Xcode default toolchain, then CommandLineTools

If you install via a non-standard npm prefix, symlink the binary into one of the supported directories.

LSP session supervision (lsp_session_list)

LSP servers are long-running processes; The Bridge supervises them out-of-band from the short-lived shell processes managed by bg_process_*. Each (language, workspaceRoot) pair gets a single LspSession lazy-spawned on first request, idle-disposed after 15 minutes of inactivity, and observable via lsp_session_list (PID, server name/version, spawn / last-used timestamps, idle seconds, request count, open-file count).

• lsp_session_list — LSP server processes only (typescript-language-server, sourcekit-lsp). Use this for LSP-specific lifecycle questions: “is the TS server up?”, “how many open files does the Swift session have?”, “when will it idle out?”.
• bg_process_list — Foreground-detached shell processes spawned via bg_process_* (long-running builds, watchers, dev servers). Use this for user-launched commands; LSP servers are not listed here.

The two surfaces are deliberately separated so observability for LSP supervision (which has its own RPC lifecycle, didOpen tracking, and capability probe) does not collide with generic shell lifecycle (which has none of those). When debugging cross-cutting state, query both.