Skip to main content

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)

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

MCPProxy logs its startup to the console and keeps running in the foreground. To confirm it came up, ask it from a second terminal:

mcpproxy status
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​

The dashboard lives at http://127.0.0.1:8080/ui/, but the REST API behind it always requires an API key (auto-generated on first run). Opening that bare URL loads the page and then raises a 🔒 Authentication Required modal: "The API key is invalid or missing."

Ask the CLI for the URL with your key already in it:

mcpproxy status --web-url
http://127.0.0.1:8080/ui/?apikey=your-generated-api-key

Open that. The Web UI remembers the key, so later visits to /ui/ work without it.

Tray users

The tray menu's Open Web UI in Browser entry opens the dashboard with the key already attached - no key handling needed.

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
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 the Web UI (see step 2) and click Add Server in the top bar. The dialog is titled Add New Server.
  2. Under Server Type, pick HTTP/HTTPS (Remote). The URL field only appears once you do - the default, stdio (Local Command), asks for a command instead.
  3. Server Name: context7 - URL: https://mcp.context7.com/mcp
  4. Leave Trust Mode on Manual: "At add time the server is quarantined until you approve it — the secure default."
  5. Click Add Server.

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. Approve It Out of Quarantine​

However you added it, the server is now quarantined - its tools are withheld from your AI agent until you approve them. This is the point of MCPProxy's security model, and nothing works until you pass this gate. The transcripts below follow the Web UI path, so they show only context7; if you took the configuration-file route, filesystem is listed alongside it and needs the same approval.

mcpproxy upstream list
   NAME      PROTOCOL  TOOLS  STATUS                  ACTION
🔒  context7  http      0      Quarantined for review  Approve in Web UI

Note the 0 tools: they exist, but are not exposed yet.

Review before approving​

Open the server's page in the Web UI. It shows the badge Quarantined for review, an Awaiting manual review banner, and the buttons View report and Approve. The Security tab holds the offline scan that ran on add - for context7 it reports Risk Score 0/100, "2 tool definitions exported for analysis", and No findings.

The same report from the CLI (abbreviated - the real output also carries a Scan ID, a Scanned timestamp, a per-scanner Scanner timing block, and the Path the tool definitions were exported to):

mcpproxy security report context7
Security Report: context7
Risk Score:  0/100
Scanners:    1 run, 0 failed of 1

Scan Context
  Source:           tool_definitions_only
  Protocol:         http
  Docker isolation: false
  Tools analyzed:   2

=== Security Scan (Pass 1) ===
  0 findings

=== Supply Chain Audit (Pass 2) ===
  Not started

Approve​

Click Approve on the server page - it applies immediately, with no confirmation dialog - or from the CLI:

mcpproxy security approve context7
Server "context7" approved.

The header flips to Connected (2 tools) and Admin state to Enabled. The Tools tab does not refill on its own: use Actions → Refresh, or reload the page, to see it go from Tools (0) to Tools (2).

mcpproxy upstream list
   NAME      PROTOCOL  TOOLS  STATUS               ACTION
✅  context7  http      2      Connected (2 tools)  -
Undo any of this
  • Turn it off, keep the config: server page → Actions → Disable.
  • Put it back behind the gate: Actions → Quarantine (the same menu entry reads Approve while the server is quarantined).
  • Remove it entirely: the server page's Actions menu has no Delete. Go to Servers, and on the server's card click Delete → confirm in the Delete Server dialog.
  • Unhook the AI client: see Connect Clients.

See Security Quarantine for what the scanner checks and how to keep servers gated permanently.

6. Make a Real Tool Call​

Now have your agent actually use the server. In your AI client:

"Search my mcpproxy tools for a way to resolve a library ID, then call it for Vue Router."

Your agent calls retrieve_tools first, which searches every upstream server and returns only the matching tools (abbreviated - each entry also carries the description, input schema and a relevance score):

{"total":2,"tools":[
  {"name":"context7:query-docs","server":"context7","call_with":"call_tool_read"},
  {"name":"context7:resolve-library-id","server":"context7","call_with":"call_tool_read"}]}

The call_with field tells the agent which intent variant to use. It then calls call_tool_read on context7:resolve-library-id, which returns real data:

Available Libraries:

- Title: Vue Router
- Context7-compatible library ID: /websites/router_vuejs
- Description: Vue Router is the official client-side routing solution for Vue that enables navigation between components in single-page applications.
- Code Snippets: 863
- Source Reputation: High
- Benchmark Score: 85.45
A first wrong guess is normal

If the agent omits a required argument, MCPProxy rejects the call before it reaches the upstream server and hands back the schema so the agent can retry - "error_type":"invalid_params", missing property 'query', plus the full input_schema. That is the self-healing path working, not a failure.

Confirm it in the audit trail​

Every call is recorded. Both blocks below are abbreviated: activity list also prints the startup and scan rows and a Showing N of N records footer, and activity show opens with an Activity Details banner and also prints ID, Timestamp, Session ID, Request ID and the full Arguments block.

mcpproxy activity list
ID                          SRC  TYPE          SERVER    TOOL                INTENT  SENSITIVE  STATUS              DURATION  TIME
01M1V7SR7357R7NS5M3W33GV0N  MCP  tool_call     context7  resolve-library-id  📖       -          success             1.3s      just now
01M1V7RXY0WRE2KF4XKYPH9QD1  MCP  internal_too            retrieve_tools      -       -          success             0ms       just now
01M1V7QQA2NR500ZMRQMKSZN6C  MCP  tool_quarant  context7  resolve-library-id  -       -          tool_auto_approved  0ms       1 minute ago
01M1V7QPN9WFWR9TTAQ28KN9AD  MCP  quarantine_c  context7                      -       -          enabled             0ms       1 minute ago
mcpproxy activity show 01M1V7SR7357R7NS5M3W33GV0N
Type:         tool_call
Source:       MCP (AI agent via MCP protocol)
Server:       context7
Tool:         resolve-library-id
Status:       success
Duration:     1.3s

Intent Declaration:
  Tool Variant:      call_tool_read
  Operation Type:    📖 read
  Data Sensitivity:  public

The Web UI's Activity Log shows the same rows. You now have a server that was reviewed, approved, discovered and called - end to end.

Next Steps​