MCPProxy Setup Guide

A comprehensive guide to connect mcpproxy (http-streamable) to popular MCP clients: Cursor IDE, VS Code, Claude Desktop, and Goose.

What is MCPProxy?

MCPProxy is a smart Model Context Protocol (MCP) proxy that provides intelligent tool discovery and proxying for MCP servers. It runs as an HTTP server that aggregates multiple upstream MCP servers into a single endpoint, making it easy to connect multiple AI tools and services to your favorite IDE or AI assistant.

Key Features:

• HTTP Streamable: Uses MCP's streamable HTTP transport for efficient communication
• Smart Tool Discovery: Automatically indexes and searches tools from multiple upstream servers
• Unified Interface: Single endpoint for multiple MCP servers
• OAuth Support: Built-in authentication for secure services
• Cross-Platform: Works on macOS, Windows, and Linux

Quick Start

1. Install MCPProxy

macOS (Recommended - DMG Installer): Download the DMG installer from GitHub Releases for the easiest installation experience.

macOS (Homebrew):

brew install smart-mcp-proxy/mcpproxy/mcpproxy

Linux (Debian / Ubuntu):

VERSION=$(curl -fsSL https://api.github.com/repos/smart-mcp-proxy/mcpproxy-go/releases/latest \
  | grep -oE '"tag_name": *"v[^"]+"' | sed -E 's/.*"v([^"]+)"/\1/')
ARCH=$(dpkg --print-architecture)
curl -fLO "https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest/download/mcpproxy_${VERSION}_${ARCH}.deb"
sudo apt install "./mcpproxy_${VERSION}_${ARCH}.deb"

The .deb ships a systemd unit and starts the service automatically, bound to 127.0.0.1:8080 by default. To reach it from other machines on your LAN, edit /etc/mcpproxy/mcp_config.json, switch listen to 0.0.0.0:8080, set a strong api_key, and restart the service. See Installation › Network exposure for the full security checklist, and Installation › Linux for .rpm, ARM64, and tarball options.

Go Install:

go install github.com/smart-mcp-proxy/mcpproxy-go/cmd/mcpproxy@latest

2. Run MCPProxy

From Terminal:

mcpproxy serve

macOS (DMG Install): Use Launchpad or Spotlight search to find and launch MCPProxy.

This starts MCPProxy on the default port :8080 with HTTP endpoint at http://localhost:8080/mcp/

📝 Note:

• MCPProxy starts with HTTP by default for immediate compatibility
• HTTPS is available optionally for enhanced security (see HTTPS Setup below)
• At first launch, MCPProxy will automatically generate a minimal configuration file if none exists

3. Check if Port is Available

Check if port 8080 is already in use:

macOS/Linux:

lsof -i :8080
# or
netstat -an | grep 8080

Windows:

netstat -an | findstr 8080

Change Default Port:

mcpproxy serve --listen :8081
# or set in config file

Configuration Paths

MCPProxy looks for configuration in these locations (in order):

Sample Configuration:

{
  "listen": ":8080",
  "data_dir": "~/.mcpproxy",

  // Search & tool limits
  "tools_limit": 15,
  "tool_response_limit": 20000,

  "mcpServers": [
    {
      "name": "local-python",
      "command": "python",
      "args": ["-m", "my_server"],
      "protocol": "stdio",
      "enabled": true
    },
    {
      "name": "remote-http",
      "url": "http://localhost:3001",
      "protocol": "http",
      "enabled": true
    }
  ]
}

📝 Note: At first launch, MCPProxy will automatically generate a minimal configuration file if none exists.

📚 For complete configuration reference: See Configuration Documentation for all available options, including tokenizer settings, TLS configuration, Docker isolation, and more.

Client Setup Instructions

🎯 Cursor IDE

Method 1: One-Click Install

1. Visit: https://mcpproxy.app/cursor-install.html
2. Click "Install in Cursor IDE"

Method 2: Manual Setup

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Click "Tools & Integrations"
3. Add MCP Server with this configuration:

{
  "MCPProxy": {
    "type": "http",
    "url": "http://localhost:8080/mcp/"
  }
}

Verification:

• Option 1: Restart Cursor completely
• Option 2: Disable and re-enable the MCP server in Cursor Settings > Tools & Integrations
• ⚠️ Important: Make sure MCPProxy is running (check for tray icon if enabled)
• Open chat and ask: "What tools do you have available?"

🛠️ VS Code

VS Code has built-in MCP support starting from version 1.102.

Setup Steps:

1. Install GitHub Copilot and Copilot Chat extensions
2. Open VS Code Settings (Cmd/Ctrl + ,)
3. Search for "mcp" in settings
4. Click "Edit in settings.json" in the MCP section
5. Add this configuration:

{
  "chat.mcp.discovery.enabled": true,
  "mcp": {
    "servers": {
      "mcpproxy": {
        "type": "http",
        "url": "http://localhost:8080/mcp/"
      }
    }
  }
}

Alternative: Workspace Configuration Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "MCPProxy": {
      "type": "http",
      "url": "http://localhost:8080/mcp/"
    }
  }
}

Usage:

1. Open Copilot Chat
2. Select Agent Mode
3. Click Tools icon to see available tools
4. MCPProxy tools will be listed

📚 Reference: VS Code MCP Documentation

🧩 OpenCode

OpenCode can be connected through MCPProxy's Connect Clients flow.

• Client ID: opencode
• Config section: mcp
• macOS/Linux global config path: ~/.config/opencode/opencode.json
• Windows global config path: %LOCALAPPDATA%\opencode\opencode.json
• OpenCode config must already exist; MCPProxy does not create it for you.
• On connect, MCPProxy writes or updates only the OpenCode mcp subtree and preserves unrelated root config.
• MCPProxy treats endpoint-equivalent existing entries as already connected, even if they use a non-canonical server name.

🤖 Claude Desktop

Claude Desktop supports two different approaches depending on your plan:

A) Free Plan — Local JSON Configuration Run mcpproxy as a local process and register it in the JSON configuration file. This method uses stdio transport with a bridge package.

B) Paid Plans — Remote Custom Connector Add mcpproxy as a remote MCP server via Settings → Connectors → Add Custom Connector. This method connects directly via HTTP.

Configuration Paths:

Setup Steps:

Option A: Free Plan — JSON Configuration

💡 One-click: mcpproxy's built-in Connect wizard (Web UI / tray) can write this bridge configuration for you automatically — pick Claude Desktop and click Connect. It registers the npx -y mcp-remote bridge shown below (Node.js required). The manual steps remain available if you prefer to edit the file yourself.

1. Create the config file if it doesn't exist:

macOS:

mkdir -p ~/Library/Application\ Support/Claude/
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:

mkdir "%APPDATA%\Claude"
type nul > "%APPDATA%\Claude\claude_desktop_config.json"

Linux:

mkdir -p ~/.config/Claude/
touch ~/.config/Claude/claude_desktop_config.json

2. Add this configuration:

{
  "mcpServers": {
    "mcpproxy": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8080/mcp"]
    }
  }
}

📝 Note: This approach uses mcp-remote to bridge HTTP to stdio transport, which is required for the JSON configuration method.

3. Restart Claude Desktop
4. Look for MCP tools in the conversation interface

Option B: Paid Plans — Remote Custom Connector

1. Open Claude Desktop
2. Go to Settings → Connectors
3. Click Add Custom Connector
4. Enter the URL: http://localhost:8080/mcp
5. Save the configuration

📝 Note: Remote servers defined in the JSON configuration are NOT used by Claude Desktop for paid plans. You must add them through the UI, and this feature is gated by your subscription plan.

📚 Reference: Claude Desktop MCP Setup

🪿 Goose

Goose is a command-line AI agent that supports MCP servers through its extension system.

Prerequisites:

• Python 3.8+ or Go 1.19+
• Goose installed: https://github.com/block/goose

Setup via CLI:

# Configure Goose
goose configure

# Choose: Add Extension
# Choose: Remote Extension
# Name: MCPProxy
# URL: http://localhost:8080/mcp/
# Timeout: 300 (default)

Setup via Configuration File: Edit ~/.config/goose/config.yaml:

extensions:
  mcpproxy:
    type: "remote"
    url: "http://localhost:8080/mcp/"
    timeout: 300

Usage:

# Start Goose session
goose

# Check available tools
goose> What tools do you have?

# Use MCPProxy tools
goose> Help me search for files related to authentication

📚 Reference: Goose Documentation

🚀 Google Antigravity

Google Antigravity is an AI-powered IDE built on VS Code with deep Gemini integration and built-in MCP support.

⚠️ Important: Antigravity uses serverUrl (not url) for HTTP-based MCP servers. Using url will cause a connection error.

Config file location:

Setup via UI:

1. Open the Agent Panel (right sidebar)
2. Click "..." (More Options) → MCP Servers → Manage MCP Servers
3. Click "View raw config"
4. Add the MCPProxy configuration (see below)
5. Click Refresh to apply changes

Setup via Configuration File:

Edit your mcp_config.json:

{
  "mcpServers": {
    "mcpproxy": {
      "serverUrl": "http://127.0.0.1:8080/mcp"
    }
  }
}

📝 Note: MCPProxy's MCP endpoint does not require API key authentication, so no headers block is needed. Antigravity does not support ${workspaceFolder} — use absolute paths in any server configuration.

📚 Reference: Antigravity MCP Documentation

Optional HTTPS Setup

MCPProxy supports secure HTTPS connections with automatic certificate generation. HTTP is enabled by default for immediate compatibility, but HTTPS provides enhanced security for production use.

Why Use HTTPS?

• 🔒 Encrypted Communication: All data between clients and MCPProxy is encrypted
• 🛡️ Production Ready: Secure for network-exposed deployments
• 🔑 Certificate Authentication: Prevents man-in-the-middle attacks
• 🌐 Standard Compliance: Follow web security best practices

Quick HTTPS Setup

Step 1: Install Certificate (One-time setup)

# Trust the mcpproxy CA certificate
mcpproxy trust-cert

This command will:

• Generate a local CA certificate if needed
• Install it to your system's trusted certificate store
• Prompt for your password once (required for keychain access)

Step 2: Enable HTTPS

Choose one of these methods:

Option A: Environment Variable (Temporary)

export MCPPROXY_TLS_ENABLED=true
mcpproxy serve

Option B: Configuration File (Permanent) Edit ~/.mcpproxy/mcp_config.json:

{
  "listen": ":8080",
  "tls": {
    "enabled": true,
    "require_client_cert": false,
    "hsts": true
  }
}

📚 For complete TLS configuration options: See Configuration Documentation - TLS/HTTPS.

Step 3: Update Client Configurations

After enabling HTTPS, update your client configurations to use https:// URLs:

Cursor IDE:

{
  "MCPProxy": {
    "type": "http",
    "url": "https://localhost:8080/mcp/"
  }
}

VS Code:

{
  "mcp": {
    "servers": {
      "mcpproxy": {
        "type": "http",
        "url": "https://localhost:8080/mcp/"
      }
    }
  }
}

Claude Desktop (with certificate trust):

{
  "mcpServers": {
    "mcpproxy": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://localhost:8080/mcp"],
      "env": {
        "NODE_EXTRA_CA_CERTS": "~/.mcpproxy/certs/ca.pem"
      }
    }
  }
}

HTTPS Configuration Options

Basic HTTPS (Recommended):

{
  "tls": {
    "enabled": true
  }
}

Advanced HTTPS with mTLS:

{
  "tls": {
    "enabled": true,
    "require_client_cert": true,
    "certs_dir": "~/.mcpproxy/certs",
    "hsts": true
  }
}

Configuration Options:

• enabled: Enable/disable HTTPS (default: false)
• require_client_cert: Enable mutual TLS (mTLS) for client authentication
• certs_dir: Custom directory for certificates (default: {data_dir}/certs)
• hsts: Enable HTTP Strict Transport Security headers

📚 For complete TLS configuration reference: See Configuration Documentation - TLS/HTTPS.

Certificate Management

Certificate Locations:

• CA Certificate: ~/.mcpproxy/certs/ca.pem
• Server Certificate: ~/.mcpproxy/certs/localhost.pem
• Private Keys: ~/.mcpproxy/certs/*.key (automatically secured)

View Certificate Details:

# View CA certificate info
openssl x509 -in ~/.mcpproxy/certs/ca.pem -text -noout

# Verify certificate chain
openssl verify -CAfile ~/.mcpproxy/certs/ca.pem ~/.mcpproxy/certs/localhost.pem

Regenerate Certificates:

# Remove existing certificates
rm -rf ~/.mcpproxy/certs

# Start mcpproxy with HTTPS (will generate new certificates)
MCPPROXY_TLS_ENABLED=true mcpproxy serve

# Trust the new certificate
mcpproxy trust-cert

Troubleshooting HTTPS

Certificate Trust Issues:

If you get SSL/TLS errors, verify certificate trust:

# Test certificate trust
curl -f https://localhost:8080/health

# If it fails, re-trust the certificate
mcpproxy trust-cert --force

Claude Desktop Certificate Issues:

If Claude Desktop shows certificate errors:

1. Ensure NODE_EXTRA_CA_CERTS points to the correct certificate path
2. Use absolute path: /Users/yourusername/.mcpproxy/certs/ca.pem
3. Restart Claude Desktop after configuration changes

Browser Certificate Warnings:

When accessing the Web UI at https://localhost:8080/ui/:

1. Click "Advanced" on the certificate warning
2. Click "Proceed to localhost (unsafe)"
3. This is expected for self-signed certificates

Security Notes

• 🔒 Local Development: Self-signed certificates are perfect for local development
• 🏢 Production: Consider using proper CA-signed certificates for production deployments
• 🔑 Certificate Rotation: Certificates are valid for 10 years but can be regenerated anytime
• 🛡️ mTLS: Enable require_client_cert: true for maximum security in sensitive environments

Port Management

Check Current Port Usage

Find MCPProxy Process:

# macOS/Linux
ps aux | grep mcpproxy
lsof -i :8080

# Windows
tasklist | findstr mcpproxy
netstat -ano | findstr :8080

Change Default Port

Command Line:

mcpproxy serve --listen :8081
mcpproxy serve --listen :9000
mcpproxy serve --listen 127.0.0.1:8080  # Bind to specific interface

Configuration File:

{
  "listen": ":8081"
  // ... rest of config
}

📚 For all network binding options: See Configuration Documentation - Basic Configuration.

Environment Variable:

export MCPPROXY_LISTEN=":8081"
mcpproxy serve

📝 Note: Environment variables are prefixed with MCPPROXY_. For example, MCPPROXY_LISTEN controls the listen address.

Multiple Instances

Run multiple MCPProxy instances on different ports:

# Instance 1 - Development
mcpproxy serve --config dev_config.json --listen :8080

# Instance 2 - Production
mcpproxy serve --config prod_config.json --listen :8081

Troubleshooting

Common Issues

1. Port Already in Use

# Kill process using port 8080
lsof -ti:8080 | xargs kill -9  # macOS/Linux
netstat -ano | findstr :8080   # Windows - note PID, then:
taskkill /PID <PID> /F          # Windows

2. MCPProxy Not Starting

# Check logs
mcpproxy serve --log-level debug

# Check configuration
mcpproxy serve --config ~/.mcpproxy/mcp_config.json --log-level debug

3. Client Connection Issues

• Verify MCPProxy is running: Check process with ps aux | grep mcpproxy
• Check firewall settings
• Ensure correct URL in client config
• Try different port: mcpproxy serve --listen :8081
• Check tray icon (if enabled) for status

4. Tools Not Appearing

• Check MCPProxy upstream server configuration
• Verify upstream servers are running
• Check MCPProxy logs for errors
• Use the retrieve_tools tool in your MCP client to test tool discovery
• Use mcpproxy tools list --server=SERVER_NAME to test individual servers

5. Server Connection Problems

• Test individual servers: mcpproxy tools list --server=SERVER_NAME --log-level=trace
• Check authentication: Look for OAuth URLs in console output
• Verify server configuration: Ensure URL, command, and protocol are correct
• Check environment: For stdio servers, verify command and arguments are correct

Debug Commands

Test MCPProxy Status:

# Check if MCPProxy is running
ps aux | grep mcpproxy

# Check port usage
lsof -i :8080

# View logs (with debug mode)
mcpproxy serve --log-level debug

Debug Individual Servers:

# List tools from a specific server with detailed debugging
mcpproxy tools list --server=github-server --log-level=trace

# Test slow servers with extended timeout
mcpproxy tools list --server=slow-server --timeout=60s

# Output tools in machine-readable format
mcpproxy tools list --server=weather-api --output=json

📝 Note: The mcpproxy tools list command is perfect for debugging connection issues, authentication problems, or verifying that a server is working correctly. It connects directly to the server, bypasses the proxy's cache, and shows detailed logging.

📝 Note: MCPProxy uses the MCP protocol over HTTP, not simple REST endpoints. Use MCP clients to interact with the server, not direct curl commands.

View Logs:

# Real-time logs (macOS/Linux)
tail -f ~/Library/Logs/mcpproxy/main.log

# Windows
Get-Content -Path "$env:LOCALAPPDATA\mcpproxy\logs\main.log" -Wait

# Filter logs for specific server debugging
tail -f ~/Library/Logs/mcpproxy/main.log | grep -E "(github-server|oauth|error)"

Advanced Configuration

📚 For complete configuration reference: See Configuration Documentation for all available options.

Security Settings

{
  "listen": "127.0.0.1:8080", // Bind to localhost only
  "read_only_mode": true, // Prevent configuration changes
  "disable_management": true, // Disable server management tools
  "allow_server_add": false, // Prevent adding new servers
  "allow_server_remove": false // Prevent removing servers
}

Performance Tuning

{
  "tools_limit": 25, // More tools per request
  "tool_response_limit": 50000 // Larger response limit
}

OAuth Configuration

For servers requiring authentication:

{
  "mcpServers": [
    {
      "name": "github",
      "url": "https://api.github.com/mcp/",
      "protocol": "http",
      "oauth": {
        "scopes": ["repo", "user"]
      },
      "enabled": true
    }
  ]
}

Next Steps

1. Add Upstream Servers: Configure MCPProxy to connect to your MCP servers
2. Explore Tools: Use your AI assistant to discover available tools
3. Customize: Adjust settings for your workflow
4. Share: Use workspace configs to share setups with your team

Additional Resources

• MCPProxy Website: https://mcpproxy.app
• Documentation: https://mcpproxy.app/docs
• Configuration Reference: Configuration Documentation - Complete configuration schema reference
• GitHub Repository: https://github.com/smart-mcp-proxy/mcpproxy-go
• MCP Specification: https://modelcontextprotocol.io
• Available MCP Servers: https://github.com/modelcontextprotocol/servers

Need help? Join our community or open an issue on GitHub.