Universal Local IDE & Workspace MCP Bridge 🚀

Connect Web AI assistants (ChatGPT, Claude Web) and MCP clients directly and securely to ANY local IDE or developer workspace (VS Code, Cursor, Windsurf, JetBrains / IntelliJ / PyCharm, Antigravity, Zed, Neovim, Terminal) — with multi-user isolation, zero open ports, and live interactive terminal logs.

💡 How It Works

Cloud AI models (ChatGPT, Claude Web) cannot reach into your computer because of firewalls and Wi-Fi NAT.

Universal IDE MCP Bridge creates an on-demand, outbound connection between your local computer and your hosted MCP Gateway:

┌──────────────────────────────────────┐
│       Web AI Assistant               │
│             (ChatGPT / Claude)       │
└──────────────────┬───────────────────┘
                   │ 1. Tool Call + Your Private Token
                   ▼
┌────────────────────────────────────────────────────────┐
│ Cloud MCP Gateway (Hosted on Vercel)                   │
│ - Authenticates your private token                     │
│ - Routes tasks exclusively to your computer            │
│ - Supports Upstash Redis for distributed persistence   │
└──────────────────▲─────────────────────────────────────┘
                   │ 2. Outbound polling (Zero inbound ports!)
                   │    Works behind any Wi-Fi or router
┌──────────────────┴─────────────────────────────────────┐
│ Your Local Computer (On-Demand Bridge Session)         │
│ - Run whenever you want, just like `npm run dev`       │
│ - Live real-time debug logs for every tool & action    │
│ - Reads & edits files, runs terminal/git commands      │
│ - Sandboxed strictly to your chosen projects folder    │
└────────────────────────────────────────────────────────┘

Related MCP server: CodeHands

🚀 3-Step Setup Guide (ZERO Git Cloning Required)

You do NOT need to clone this GitHub repository to connect your computer. You only need the single standalone bridge.py script.

Step 1: Download bridge.py Globally

Open your terminal in your root projects directory (for example C:\projects on Windows or ~/projects on macOS/Linux), and download the single bridge file:

Windows (PowerShell or Command Prompt):

curl.exe -o bridge.py https://vscode-antigravity-mcp.vercel.app/bridge.py

macOS / Linux:

curl -o bridge.py https://vscode-antigravity-mcp.vercel.app/bridge.py

(You can place this single bridge.py file anywhere on your computer — no additional project files or repositories needed.)

Step 2: Set Your Token & Projects Folder Path

Configure your bridge with your private authentication token and the parent directory containing your code repositories. Using the --save flag saves these settings globally so you only have to do this once:

python bridge.py --save --root "C:\projects" --key "YOUR_SECRET_KEY"

• --root: The folder containing all your projects (e.g. C:\projects or /Users/username/projects). Your Web AI will be able to navigate and work across any project inside this folder.

• --key: Your private auth token (e.g. D4_PROJECT_MCP_SERVER or any custom secret key).

• --save: Saves this configuration globally to ~/.universal_ide_bridge.json.

Verify Your Saved Configuration Anytime:

python bridge.py --show-config

Output:

📁 Current Saved Global Bridge Configuration:
   Config file: C:\Users\Admin\.universal_ide_bridge.json
   Server:      https://vscode-antigravity-mcp.vercel.app
   Root:        C:\projects
   Token:       YOUR_SECRET_KEY

Step 3: Run the Bridge (On-Demand Like npm run dev)

Whenever you want to use the AI assistant with your local code, run:

python bridge.py

(Or if installed globally, simply run ide-bridge or mcp-bridge)

What Happens When You Run It:

1. Interactive Console: Launches an active developer session with live status streaming.

2. Real-Time Debug Logs: Every time ChatGPT or Claude executes a tool, the parameters, execution time (in ms), and output preview are printed in real-time.

3. Stop Anytime: Press Ctrl+C in your terminal to cleanly disconnect and stop the bridge.

╔════════════════════════════════════════════════════════════════════════════╗
║              🚀 Universal IDE Bridge (On-Demand Dev Session)               ║
╚════════════════════════════════════════════════════════════════════════════╝
📁 Projects Root:    C:\projects
🎯 Active Workspace: C:\projects\my-app
🌐 Cloud Gateway:    https://vscode-antigravity-mcp.vercel.app
🔑 Auth Token:       YOUR_SEC..._KEY
🟢 Status:           ACTIVE & LISTENING (Press Ctrl+C to stop)
────────────────────────────────────────────────────────────────────────
💡 Ready! When ChatGPT or Claude calls a tool, logs will stream below:

[21:30:15] 💚 Gateway heartbeat confirmed (latency: 38ms) | Status: Healthy

──────────────────────────────────────────────────────────────────────
⚡ [21:30:28] INCOMING AI REQUEST: get_active_project
📦 Parameters: {}
📁 Target Project: my-app (C:\projects\my-app)
⚙️ Executing local action...
✅ Local execution completed successfully in 5.8ms
📊 Result: {"projects_root": "C:\\projects", "active_project": "my-app", "git_branch": "main"}
🚀 Delivered result to AI assistant in 12ms (attempt 1)
──────────────────────────────────────────────────────────────────────

🛑 Bridge session stopped by user (Ctrl+C). Clean shutdown complete.
👋 Goodbye!

🌐 Web AI Connection Details (At a Glance)

Connect any Web AI Chat in your browser to your local computer:

💻 Browser AI Setup Walkthrough

🟢 1. ChatGPT Web (chatgpt.com Custom GPT Actions — Recommended)

1. In your browser, open chatgpt.com.

2. Go to Explore GPTs ➔ + Create (top right) ➔ Configure tab.

3. Click Create new action:

   • Authentication Type: API Key ➔ Bearer ➔ Enter YOUR_SECRET_KEY.

   • Schema: Click Import from URL ➔ Enter:

     https://vscode-antigravity-mcp.vercel.app/openapi.json

   • Click Import. ChatGPT imports all tools immediately!

4. Click Create / Save ➔ Select Only me.

5. Start chatting with your local projects in ChatGPT!

🟣 2. Claude Web (claude.ai Custom Connectors)

1. Open claude.ai in your browser.

2. Click your user profile icon (bottom left) ➔ Settings ➔ Connectors (or + Add ➔ Custom connector).

3. Fill in:

   • Name: Universal IDE Bridge

   • URL:

     https://vscode-antigravity-mcp.vercel.app/mcp?token=YOUR_SECRET_KEY

4. Click Continue. Claude connects over official StreamableHTTP and discovers all 17 tools instantly!

🛠️ Complete Tools Reference (17 Tools)

📂 Multi-Project & Workspace Navigation

📝 File & Directory Operations

🔍 Code Search

💻 Terminals & Version Control

⚙️ CLI Reference (bridge.py)

☁️ For Admins: Deploying Your Own Gateway to Vercel

1. Click Deploy

2. Environment Variables in Vercel Settings

Tip for Vercel Serverless: If you enable free Upstash Redis (UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN), the gateway coordinates tasks across isolated serverless containers with 0% dropped tasks and 0 timeouts.

🔒 Security & Sandboxing

• Boundary Protection: The executor enforces strict root directory boundaries. Any attempt by the AI to access files outside your designated root (../../etc/passwd or C:\Windows) raises an immediate PermissionError.

• Zero Inbound Ports: Your computer never opens an incoming network port. All communication uses outbound HTTPS polling.

• Process Isolation: Terminal commands run inside isolated process groups with Windows taskkill /F /T tree-kill timeouts to prevent hanging child processes.

📄 License

MIT License. Open-source and free for personal and commercial use.