Skip to main content

Desktop Connection

Connect local services running on your machine to MCPBundles. Access PostgreSQL databases, Redis caches, Android Debug Bridge (ADB), and other localhost services from your AI workflows.

Overview​

The MCPBundles Desktop Connection allows your AI assistants to interact with services running locally on your machine:

  • Local Databases - PostgreSQL, MySQL, SQLite
  • Cache Servers - Redis, Memcached
  • Mobile Development - Android ADB, iOS simulators
  • Development Servers - Local APIs, dev environments
  • System Services - Any service listening on localhost
Why Desktop Connection?

Most local services can't be accessed from the cloud for security reasons. The Desktop Connection creates a secure tunnel between your machine and MCPBundles, allowing AI tools to query databases, run commands, and interact with your local environment.

Quick Start​

Installation​

Install the desktop proxy client via pip:

pip install mcpbundles-proxy
Recommended: Use pipx

For a cleaner installation that doesn't affect your global Python environment:

pipx install mcpbundles-proxy

Authenticate​

Connect your local machine to your MCPBundles account:

mcpbundles-proxy login

This will:

  1. Open your browser to authorize the connection
  2. Generate secure credentials for your machine
  3. Store authentication locally

Start the Connection​

Launch the proxy in the background:

mcpbundles-proxy start

The proxy will:

  • Run as a background daemon
  • Auto-discover local services (PostgreSQL, Redis, ADB, etc.)
  • Maintain a secure WebSocket connection to MCPBundles
  • Automatically reconnect if interrupted

Verify Connection​

Check that everything is working:

mcpbundles-proxy status

Expected output:

✓ Connected to MCPBundles
✓ Last seen: Just now

Discovered Services:
  - PostgreSQL (localhost:5432)
  - Redis (localhost:6379)
  - ADB (localhost:5037)

Common Commands​

status​

Check if the proxy is running and view discovered services

mcpbundles-proxy status

stop​

Stop the background proxy daemon

mcpbundles-proxy stop

logs​

View connection logs for debugging

mcpbundles-proxy logs

Tail logs in real-time:

mcpbundles-proxy logs --follow

logout​

Remove stored credentials from your machine

mcpbundles-proxy logout
warning

After logout, you'll need to run mcpbundles-proxy login again to reconnect.

Using Local Services in Your Bundles​

Once connected, local services become available to tools in your bundles.

Example: Query Local PostgreSQL​

Add a PostgreSQL tool to your bundle, then ask your AI:

"Connect to my local PostgreSQL database 'dev_db' and show me 
the schema for the users table"

The AI will:

  1. Detect that dev_db is on localhost
  2. Route the request through your desktop connection
  3. Execute the query on your local machine
  4. Return results to the AI

Example: Use Android ADB​

"List all connected Android devices via ADB"
"Take a screenshot from my Android emulator"

Example: Cache Operations​

"Get the value of 'user:123' from my local Redis cache"
"Set 'feature_flags' in Redis to enable dark mode"

Security & Privacy​

What Gets Sent to MCPBundles?​

Only forwarded requests:

  • When your AI explicitly calls a tool that requires localhost access
  • The specific command/query being executed
  • Response data from your local service

Never sent:

  • Ambient network traffic
  • Services you're not using
  • Data from other processes
  • Passwords or credentials

How Authentication Works​

  1. OAuth Login - Browser-based authorization links your machine to your account
  2. JWT Token - Secure token stored locally at ~/.mcpbundles/proxy.token
  3. WebSocket Tunnel - Encrypted connection using WSS (WebSocket Secure)
  4. Request Validation - Every request is authenticated before execution

Stopping Access​

To immediately revoke access:

mcpbundles-proxy stop
mcpbundles-proxy logout

Or revoke from the dashboard:

  1. Go to Settings
  2. Navigate to Desktop Connection
  3. Click Disconnect

Advanced Configuration​

Custom Port​

Run the proxy on a different local port:

mcpbundles-proxy start --port 9090

Verbose Logging​

Enable detailed logs for debugging:

mcpbundles-proxy start --verbose

Specify Services​

Only expose specific services:

mcpbundles-proxy start --services postgresql,redis

Configuration File​

Create ~/.mcpbundles/config.yaml for persistent settings:

port: 9090
verbose: true
services:
  - postgresql
  - redis
  - adb
auto_reconnect: true

Troubleshooting​

Connection Status Shows "Not Connected"​

Possible causes:

  • Proxy not running
  • Network issues
  • Authentication expired

Fix:

# Check if proxy is running
mcpbundles-proxy status

# If not running, start it
mcpbundles-proxy start

# If authentication expired, re-login
mcpbundles-proxy logout
mcpbundles-proxy login
mcpbundles-proxy start

Service Not Discovered​

Possible causes:

  • Service not running on standard ports
  • Service doesn't accept localhost connections

Fix:

  1. Verify service is running:
# PostgreSQL
lsof -i :5432

# Redis
lsof -i :6379

# ADB
adb devices

  1. Check service configuration:

    • PostgreSQL: Ensure listen_addresses includes localhost or *
    • Redis: Ensure bind includes 127.0.0.1
    • MySQL: Ensure binding to 0.0.0.0 or 127.0.0.1

  2. Manually test connection:

# PostgreSQL
psql -h localhost -U postgres

# Redis
redis-cli ping

# MySQL
mysql -h 127.0.0.1 -u root

"Permission Denied" Errors​

Cause: User doesn't have permissions for the local service.

Fix:

Grant your user access to the service:

PostgreSQL:

GRANT ALL PRIVILEGES ON DATABASE dev_db TO your_username;

Redis: Ensure no requirepass in redis.conf, or provide password in tool config

ADB:

adb kill-server
adb start-server

High CPU Usage​

Cause: Too many reconnection attempts or verbose logging enabled.

Fix:

# Stop proxy
mcpbundles-proxy stop

# Restart without verbose mode
mcpbundles-proxy start

# Check logs for errors
mcpbundles-proxy logs

Can't Login (Browser Doesn't Open)​

Cause: Running in a headless environment or SSH session.

Fix:

Use manual authentication:

mcpbundles-proxy login --manual

This will:

  1. Display a URL in the terminal
  2. Copy the URL to a browser on any device
  3. Complete authorization
  4. Return an auth code to paste in the terminal

Platform-Specific Notes​

macOS​

Installation with Homebrew:

brew install pipx
pipx install mcpbundles-proxy

Run at startup:

# Create LaunchAgent
cat > ~/Library/LaunchAgents/com.mcpbundles.proxy.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.mcpbundles.proxy</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/mcpbundles-proxy</string>
        <string>start</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>
EOF

# Load the service
launchctl load ~/Library/LaunchAgents/com.mcpbundles.proxy.plist

Windows​

Installation:

pip install mcpbundles-proxy

Run at startup:

  1. Press Win + R
  2. Type shell:startup
  3. Create shortcut to: mcpbundles-proxy start

Logs location:

%USERPROFILE%\.mcpbundles\logs\proxy.log

Linux​

Installation:

# Ubuntu/Debian
sudo apt install pipx
pipx install mcpbundles-proxy

# Fedora/RHEL
sudo dnf install pipx
pipx install mcpbundles-proxy

Run as systemd service:

# Create service file
sudo tee /etc/systemd/system/mcpbundles-proxy.service > /dev/null << 'EOF'
[Unit]
Description=MCPBundles Desktop Connection
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
ExecStart=/home/YOUR_USERNAME/.local/bin/mcpbundles-proxy start
Restart=always

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
sudo systemctl enable mcpbundles-proxy
sudo systemctl start mcpbundles-proxy

# Check status
sudo systemctl status mcpbundles-proxy

Replace YOUR_USERNAME with your actual username.

FAQ​

Do I need to keep my computer on?​

Yes. The desktop connection only works while your computer is running and the proxy is active.

Can I use the same connection on multiple machines?​

Each machine needs its own proxy instance. Run mcpbundles-proxy login on each machine.

Does this work with Docker containers?​

Yes! Use host.docker.internal instead of localhost in your Docker containers:

# docker-compose.yml
services:
  app:
    extra_hosts:
      - "host.docker.internal:host-gateway"

Then configure tools to use host.docker.internal:5432 instead of localhost:5432.

What happens if the connection drops?​

The proxy automatically reconnects. Your tools will retry requests seamlessly.

Can I use this in production?​

The desktop connection is designed for development and testing only. For production:

  • Use cloud-hosted databases (RDS, Cloud SQL)
  • Expose APIs via proper hosting (Heroku, Vercel, Railway)
  • Use managed services instead of localhost

Next Steps​

Need Help?​