Skip to main content

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Quick Start

This guide will get MCPProxy running in 5 minutes.

Prerequisites​

1. Start MCPProxy​

Choose the method that matches how you installed MCPProxy:

If you installed MCPProxy using the DMG installer (macOS) or Windows installer, the easiest way to run MCPProxy is through the tray application:

  1. Open Launchpad or use Spotlight (Cmd + Space)
  2. Search for "MCPProxy" and click to launch
  3. Look for the MCPProxy icon in your menu bar (top right)
  1. Open the Start Menu
  2. Find "MCPProxy" in your apps list and click to launch
  3. Look for the MCPProxy icon in your system tray (bottom right, near the clock)

What the tray app does:

  • Automatically starts the MCPProxy core server when launched
  • Automatically stops the core server when you quit the tray app
  • Provides quick access to the Web UI, logs, and settings via the tray menu
  • Runs in background - minimize to tray and MCPProxy keeps running
  • Auto-starts on login (optional) - configure in tray settings
Tray Menu Options

Right-click (or click on macOS) the tray icon to access:

  • Open Web UI - Launch the management dashboard
  • View Logs - See server activity
  • Upstream Servers - View status of all MCP servers, enable/disable individual servers
  • Quit - Stop MCPProxy completely

Using the Terminal (For Homebrew/Binary Users)​

If you installed via Homebrew or manual binary download, start MCPProxy from your terminal:

mcpproxy serve

You should see output like:

MCPProxy server started
Listening on http://127.0.0.1:8080
Web UI available at http://127.0.0.1:8080/ui/
Running Both

If you're using the tray app, you don't need to run mcpproxy serve manually - the tray app handles this for you. Running both will cause a port conflict.

2. Open the Web UI​

Open your browser to http://127.0.0.1:8080/ui/ to access the management dashboard.

3. Connect Your AI Client​

MCPProxy exposes an MCP endpoint at http://localhost:8080/mcp. Connect your AI client using one of these methods:

One-Click Install:

Add to Cursor

Manual Setup:

  1. Open Cursor Settings (Cmd/Ctrl + ,)
  2. Go to Features → MCP
  3. Click Add Server
  4. Enter:
    • Name: MCPProxy
    • URL: http://localhost:8080/mcp

Add MCPProxy to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

After saving, restart Claude Desktop to apply the changes.

Why mcp-remote?

Claude Desktop doesn't natively support HTTP MCP servers yet. The mcp-remote package bridges this gap by proxying the HTTP connection through stdio.

Add MCPProxy with a single command:

claude mcp add --transport http mcpproxy http://localhost:8080/mcp

Verify it was added:

claude mcp list
Multiple Clients

You can connect multiple AI clients to the same MCPProxy instance simultaneously. All clients share the same upstream servers and configuration.

4. Add Your First MCP Server​

Now that your AI client is connected to MCPProxy, you can add upstream MCP servers. Choose one of these methods:

The easiest way to add servers is to simply ask your AI agent! MCPProxy provides an upstream_servers tool that lets AI agents manage server configuration directly.

Try it: In your AI client, type:

"Add an upstream server named context7 with URL https://mcp.context7.com/mcp using HTTP protocol"

Your AI agent will use the upstream_servers tool to add the server to your MCPProxy configuration. You can also ask your agent to:

  • Check server status: "Show me the status of all upstream servers"
  • Troubleshoot connections: "Why is the context7 server not connecting?"
  • Enable/disable servers: "Disable the filesystem server"
  • List available tools: "What tools are available from context7?"
Chat-Based Management

You can manage your entire MCPProxy setup through natural conversation with your AI agent - no need to switch between different interfaces!

Via Web UI​

  1. Open http://127.0.0.1:8080/ui/
  2. Click "Add Server"
  3. Enter the server details
  4. Click "Save"

Via Configuration File​

Edit ~/.mcpproxy/mcp_config.json:

{
  "mcpServers": [
    {
      "name": "context7",
      "url": "https://mcp.context7.com/mcp",
      "protocol": "http",
      "enabled": true
    },
    {
      "name": "filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"],
      "protocol": "stdio",
      "enabled": true
    }
  ]
}

5. Verify Connection​

In your AI client, ask it to list available tools. You should see tools from all your configured MCP servers.

Example: "What tools do I have available?"

Next Steps​