Skip to content
Back to search

mcpproxy-go

Supercharge AI Agents, Safely

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/smart-mcp-proxy/mcpproxy-go with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/smart-mcp-proxy/mcpproxy-go'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/smart-mcp-proxy--mcpproxy-go/badge.svg)](/listings/smart-mcp-proxy--mcpproxy-go)

HTML

<a href="/listings/smart-mcp-proxy--mcpproxy-go"><img src="/api/listings/smart-mcp-proxy--mcpproxy-go/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install

**macOS (Recommended - DMG Installer):**

Download the latest DMG installer for your architecture: - **Apple Silicon (M1/M2):** [Download DMG](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest) → `mcpproxy-*-darwin-arm64.dmg` - **Intel Mac:** [Download DMG](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest) → `mcpproxy-*-darwin-amd64.dmg`

**Windows (Recommended - Installer):**

Download the latest Windows installer for your architecture: - **x64 (64-bit):** [Download Installer](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest) → `mcpproxy-setup-*-amd64.exe` - **ARM64:** [Download Installer](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest) → `mcpproxy-setup-*-arm64.exe`

The installer automatically: - Installs both `mcpproxy.exe` (core server) and `mcpproxy-tray.exe` (system tray app) to Program Files - Adds MCPProxy to your system PATH for command-line access - Creates Start Menu shortcuts - Supports silent installation: `.\mcpproxy-setup.exe /VERYSILENT`

**Alternative install methods:**

macOS (Homebrew):

# macOS — GUI tray app (recommended):
brew install --cask smart-mcp-proxy/mcpproxy/mcpproxy

# macOS / Linux — headless CLI only:
brew install smart-mcp-proxy/mcpproxy/mcpproxy

The cask installs the menu-bar app (bundles the CLI); the formula is the CLI binary only. Both update via `brew upgrade`.

Linux (Debian/Ubuntu) — apt repository, auto-updates via `apt upgrade`:

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://apt.mcpproxy.app/mcpproxy.gpg \
  | sudo tee /etc/apt/keyrings/mcpproxy.gpg > /dev/null
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/mcpproxy.gpg] https://apt.mcpproxy.app stable main" \
  | sudo tee /etc/apt/sources.list.d/mcpproxy.list > /dev/null
sudo apt update && sudo apt install mcpproxy

Linux (Fedora / RHEL / Rocky / AlmaLinux) — dnf repository, auto-updates via `dnf upgrade`:

sudo dnf config-manager --add-repo https://rpm.mcpproxy.app/mcpproxy.repo
# Fedora 41+ (dnf5): sudo curl -fsSL https://rpm.mcpproxy.app/mcpproxy.repo -o /etc/yum.repos.d/mcpproxy.repo
sudo dnf install -y mcpproxy

Arch Linux (AUR): [`mcpproxy-bin`](https://aur.archlinux.org/packages/mcpproxy-bin)

yay -S mcpproxy-bin
# or
git clone https://aur.archlinux.org/mcpproxy-bin.git && cd mcpproxy-bin && makepkg -si

The apt and dnf packages ship a hardened `systemd` unit and start the service automatically. Repository signing key fingerprint: `3B6F A1AD 5D53 59DA 51F1 8DDC E1B5 9B9B A1CB 8A3B`.

For one-off `.deb` / `.rpm` downloads (air-gapped installs), grab them from the [latest release](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest).

Manual download (all platforms): - **Linux tarball**: [AMD64](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest/download/mcpproxy-latest-linux-amd64.tar.gz) | [ARM64](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest/download/mcpproxy-latest-linux-arm64.tar.gz) - **Windows**: [AMD64](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest/download/mcpproxy-latest-windows-amd64.zip) | [ARM64](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest/download/mcpproxy-latest-windows-arm64.zip)

**Prerelease Builds (Latest Features):**

Want to try the newest features? Download prerelease builds from the `next` branch:

1. Go to [GitHub Actions](https://github.com/smart-mcp-proxy/mcpproxy-go/actions) 2. Click the latest successful "Prerelease" workflow run 3. Download from **Artifacts**: - `dmg-darwin-arm64` (Apple Silicon Macs) - `dmg-darwin-amd64` (Intel Macs) - `versioned-linux-amd64`, `versioned-windows-amd64` (other platforms)

> **Note**: Prerelease builds are signed and notarized for macOS but contain cutting-edge features that may be unstable.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 447 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <a href="https://mcpproxy.app" target="_blank" rel="noopener">
  3. <img src="docs/social.png" alt="MCPProxy — Supercharge AI Agents, Safely · One safe endpoint in front of every MCP server" width="100%" />
  4. </a>
  5. </p>
  6. <div align="center">
  7. [![Release](https://img.shields.io/github/v/release/smart-mcp-proxy/mcpproxy-go?sort=semver)](https://github.com/smart-mcp-proxy/mcpproxy-go/releases)
  8. [![Build](https://github.com/smart-mcp-proxy/mcpproxy-go/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/smart-mcp-proxy/mcpproxy-go/actions/workflows/unit-tests.yml)
  9. [![Go Report Card](https://goreportcard.com/badge/github.com/smart-mcp-proxy/mcpproxy-go)](https://goreportcard.com/report/github.com/smart-mcp-proxy/mcpproxy-go)
  10. [![Go Reference](https://pkg.go.dev/badge/github.com/smart-mcp-proxy/mcpproxy-go.svg)](https://pkg.go.dev/github.com/smart-mcp-proxy/mcpproxy-go)
  11. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  12. [![GitHub stars](https://img.shields.io/github/stars/smart-mcp-proxy/mcpproxy-go?style=social)](https://github.com/smart-mcp-proxy/mcpproxy-go/stargazers)
  13. [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/smart-mcp-proxy/mcpproxy-go/badge)](https://securityscorecards.dev/viewer/?uri=github.com/smart-mcp-proxy/mcpproxy-go)
  14. </div>
  15. <p align="center">
  16. <img src="docs/demo.gif" alt="MCPProxy web UI demo: server dashboard, tool discovery, activity log, and security quarantine" width="900" />
  17. </p>
  18. <p align="center">
  19. <strong>📺 <a href="https://youtu.be/2aKrgJnbbcw">Watch the full walkthrough</a></strong> &nbsp;·&nbsp;
  20. <strong>📚 <a href="https://docs.mcpproxy.app/">Read the docs</a></strong> &nbsp;·&nbsp;
  21. <strong>🌐 <a href="https://mcpproxy.app">mcpproxy.app</a></strong>
  22. </p>
  23. > The demo above shows the **embedded web UI**. The MCPProxy **core is a single binary for macOS, Linux, and Windows** — the web UI ships inside it, with no extra service to run. On **macOS**, an optional **menu‑bar app** adds one‑click convenience (start/stop, server health, quarantine, logs).
  24. <div align="center">
  25. <img src="docs/screenshot-macos-tray.png" height="300" alt="MCPProxy macOS menu-bar app" />
  26. &nbsp;&nbsp;&nbsp;&nbsp;
  27. <img src="docs/screenshot-macos-activity.png" height="300" alt="MCPProxy macOS app — Activity log with sensitive-data detection" />
  28. <br />
  29. <em>macOS menu‑bar app &nbsp;&nbsp;·&nbsp;&nbsp; Activity log &amp; audit in the macOS app</em>
  30. </div>
  31. ## Why MCPProxy?
  32. - **Scale beyond API limits** – Federate hundreds of MCP servers while bypassing Cursor's 40-tool limit and OpenAI's 128-function cap.
  33. - **Spend less context on tool definitions** – Agents see a small set of MCPProxy discovery and execution tools (`retrieve_tools`, `describe_tool`, the `call_tool_*` variants and a few management tools) instead of the full upstream tool catalog, and fetch schemas on demand (in `retrieve_tools` and `code_execution` routing; `direct` routing exposes upstream tools individually, see [Routing modes](https://docs.mcpproxy.app/features/routing-modes/)). How much context this saves depends on the number of tools, the routing mode, the client and the task; see [Token savings: what is and is not measured](#token-savings-what-is-and-is-not-measured).
  34. - **Review before use** – New servers are quarantined and their tools are withheld from agents until you review and approve them, and, under the default `manual` trust mode, most later changes to an approved tool's definition are held for review again. Known exceptions: input-schema-only edits outside `scan` mode, a newly added output schema, and a description added to a tool that was approved with an empty description are admitted without a hold; `scan` mode admits clean changes and misses what its detectors miss; `auto` mode does not hold changes. This reduces exposure to malicious tool definitions (Tool Poisoning Attacks); it is not a guarantee of safety. See [What quarantine does and does not cover](https://docs.mcpproxy.app/features/security-quarantine/#what-quarantine-does-and-does-not-cover).
  35. - **Pluggable security scanners** – Run Snyk, Semgrep, Trivy, Cisco, and other Docker-based scanners against quarantined servers before you approve them; findings are normalized to SARIF with a composite risk score. See [Security scanner plugins](https://docs.mcpproxy.app/features/security-scanner-plugins/).
  36. - **Works offline & cross-platform** – A single core binary for macOS (Intel & Apple Silicon), Windows (x64 & ARM64), and Linux (x64 & ARM64), with the **web UI embedded**. macOS additionally ships an optional menu-bar app.
  37. ## Token savings: what is and is not measured
  38. On-demand discovery reduces how many upstream tool definitions an agent loads into context up front. The saving is not a fixed percentage: it grows with the number of connected tools and depends on the routing mode, the client and the task. MCPProxy does not publish a headline token-reduction or accuracy-improvement figure, and it makes no latency claim.
  39. What the repository does measure, as a first-party, deterministic estimate (see [`bench/README.md`](bench/README.md) for the method and to reproduce it with `go run ./bench/cmd/bench`):
  40. - Corpus: the frozen 45-tool reference corpus; counting tool **name and description only** (input schemas excluded), `cl100k_base`.
  41. - Metric: size of the initial tool menu in tokens, including the proxy's own discovery, call and management tools. Not total workflow tokens, not latency, and not task success.
  42. - Result: on that 45-tool corpus the proxy's initial menu is **larger** than listing every upstream tool (2625 tokens in `retrieve_tools` mode and 1874 in `code_execution` mode, against 1730 for the baseline), because the proxy's own tools have a fixed cost. A saving appears only above a break-even number of upstream tools, so quote the tool count with any percentage.
  43. ---
  44. ## Quick Start
  45. ### 1. Install
  46. **macOS (Recommended - DMG Installer):**
  47. Download the latest DMG installer for your architecture:
  48. - **Apple Silicon (M1/M2):** [Download DMG](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest) → `mcpproxy-*-darwin-arm64.dmg`
  49. - **Intel Mac:** [Download DMG](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest) → `mcpproxy-*-darwin-amd64.dmg`
  50. **Windows (Recommended - Installer):**
  51. Download the latest Windows installer for your architecture:
  52. - **x64 (64-bit):** [Download Installer](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest) → `mcpproxy-setup-*-amd64.exe`
  53. - **ARM64:** [Download Installer](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest) → `mcpproxy-setup-*-arm64.exe`
  54. The installer automatically:
  55. - Installs both `mcpproxy.exe` (core server) and `mcpproxy-tray.exe` (system tray app) to Program Files
  56. - Adds MCPProxy to your system PATH for command-line access
  57. - Creates Start Menu shortcuts
  58. - Supports silent installation: `.\mcpproxy-setup.exe /VERYSILENT`
  59. **Alternative install methods:**
  60. macOS (Homebrew):
  61. ```bash
  62. # macOS — GUI tray app (recommended):
  63. brew install --cask smart-mcp-proxy/mcpproxy/mcpproxy
  64. # macOS / Linux — headless CLI only:
  65. brew install smart-mcp-proxy/mcpproxy/mcpproxy
  66. ```
  67. The cask installs the menu-bar app (bundles the CLI); the formula is the CLI binary only. Both update via `brew upgrade`.
  68. Linux (Debian/Ubuntu) — apt repository, auto-updates via `apt upgrade`:
  69. ```bash
  70. sudo install -m 0755 -d /etc/apt/keyrings
  71. curl -fsSL https://apt.mcpproxy.app/mcpproxy.gpg \
  72. | sudo tee /etc/apt/keyrings/mcpproxy.gpg > /dev/null
  73. echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/mcpproxy.gpg] https://apt.mcpproxy.app stable main" \
  74. | sudo tee /etc/apt/sources.list.d/mcpproxy.list > /dev/null
  75. sudo apt update && sudo apt install mcpproxy
  76. ```
  77. Linux (Fedora / RHEL / Rocky / AlmaLinux) — dnf repository, auto-updates via `dnf upgrade`:
  78. ```bash
  79. sudo dnf config-manager --add-repo https://rpm.mcpproxy.app/mcpproxy.repo
  80. # Fedora 41+ (dnf5): sudo curl -fsSL https://rpm.mcpproxy.app/mcpproxy.repo -o /etc/yum.repos.d/mcpproxy.repo
  81. sudo dnf install -y mcpproxy
  82. ```
  83. Arch Linux (AUR): [`mcpproxy-bin`](https://aur.archlinux.org/packages/mcpproxy-bin)
  84. ```bash
  85. yay -S mcpproxy-bin
  86. # or
  87. git clone https://aur.archlinux.org/mcpproxy-bin.git && cd mcpproxy-bin && makepkg -si
  88. ```
  89. The apt and dnf packages ship a hardened `systemd` unit and start the service automatically. Repository signing key fingerprint: `3B6F A1AD 5D53 59DA 51F1 8DDC E1B5 9B9B A1CB 8A3B`.
  90. For one-off `.deb` / `.rpm` downloads (air-gapped installs), grab them from the [latest release](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest).
  91. Manual download (all platforms):
  92. - **Linux tarball**: [AMD64](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest/download/mcpproxy-latest-linux-amd64.tar.gz) | [ARM64](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest/download/mcpproxy-latest-linux-arm64.tar.gz)
  93. - **Windows**: [AMD64](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest/download/mcpproxy-latest-windows-amd64.zip) | [ARM64](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest/download/mcpproxy-latest-windows-arm64.zip)
  94. **Prerelease Builds (Latest Features):**
  95. Want to try the newest features? Download prerelease builds from the `next` branch:
  96. 1. Go to [GitHub Actions](https://github.com/smart-mcp-proxy/mcpproxy-go/actions)
  97. 2. Click the latest successful "Prerelease" workflow run
  98. 3. Download from **Artifacts**:
  99. - `dmg-darwin-arm64` (Apple Silicon Macs)
  100. - `dmg-darwin-amd64` (Intel Macs)
  101. - `versioned-linux-amd64`, `versioned-windows-amd64` (other platforms)
  102. > **Note**: Prerelease builds are signed and notarized for macOS but contain cutting-edge features that may be unstable.
  103. - **macOS**: [Intel](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest/download/mcpproxy-latest-darwin-amd64.tar.gz) | [Apple Silicon](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest/download/mcpproxy-latest-darwin-arm64.tar.gz)
  104. Anywhere with Go 1.26+:
  105. ```bash
  106. go install github.com/smart-mcp-proxy/mcpproxy-go/cmd/mcpproxy@latest
  107. ```
  108. ### 2. Run
  109. ```bash
  110. mcpproxy serve # starts HTTP server on :8080 and shows tray
  111. ```
  112. ### 3. Add your first server and approve it
  113. New servers are held in quarantine until you review them, so adding a server is a two-step journey: add, then review and approve. The full walkthrough, with a real remote server (Context7), is the published [Quick Start](https://docs.mcpproxy.app/getting-started/quick-start/). In short (Context7 is a public, read-only documentation server; substitute any server you trust):
  114. ```bash
  115. # 1. add (held in quarantine until approved)
  116. mcpproxy upstream add context7 https://mcp.context7.com/mcp
  117. # 2. review: capture the tool definitions, run the offline scan, read the verdict
  118. mcpproxy review fetch context7
  119. mcpproxy security rescan context7
  120. mcpproxy review show context7
  121. # 3. approve (with no --tools/--all, only read-only tools with a clean scan are allowed)
  122. mcpproxy review approve context7 --yes
  123. # 4. one harmless read, then see it in the activity log
  124. mcpproxy call tool-read -t context7:resolve-library-id -j '{"libraryName":"vue-router","query":"routing"}'
  125. mcpproxy activity list --limit 3
  126. ```
  127. A clean scan is not proof that a server is safe; it only means the offline checks found nothing in the tool definitions. Review what you approve.
  128. You can also edit `~/.mcpproxy/mcp_config.json` by hand; a first-seen entry is held for review in the same way:
  129. ```jsonc
  130. {
  131. "listen": "127.0.0.1:8080",
  132. "mcpServers": [
  133. { "name": "local-python", "command": "python", "args": ["-m", "my_server"], "protocol": "stdio", "enabled": true },
  134. { "name": "remote-http", "url": "http://localhost:3001", "protocol": "http", "enabled": true }
  135. ]
  136. }
  137. ```
  138. See [Configuration](https://docs.mcpproxy.app/configuration/config-file/) and [Upstream Servers](https://docs.mcpproxy.app/configuration/upstream-servers/) for the full reference, and [Security Quarantine](https://docs.mcpproxy.app/features/security-quarantine/) for what the review gate does and does not cover.
  139. ### 4. Connect to your IDE/AI tool
  140. 📖 **[Complete Setup Guide](docs/setup.md)** - Detailed instructions for Cursor, VS Code, Claude Desktop, and Goose
  141. ## Add proxy to Cursor
  142. ### One-click install into Cursor IDE
  143. [![Install in Cursor IDE](https://img.shields.io/badge/Install_in_Cursor-3e44fe?logo=data:image/svg+xml;base64,PHN2ZyB2aWV3Qm94P…&style=for-the-badge)](https://mcpproxy.app/cursor-install.html)
  144. ### Manual install
  145. 1. Open Cursor Settings
  146. 2. Click "Tools & Integrations"
  147. 3. Add MCP server
  148. ```json
  149. "MCPProxy": {
  150. "type": "http",
  151. "url": "http://localhost:8080/mcp/"
  152. }
  153. ```
  154. ---
  155. ## How AI Agents Work Through MCPProxy
  156. Once connected, your agent sees a handful of built-in MCPProxy tools instead of hundreds of upstream schemas. A typical session has three beats — discover, call, audit — plus an optional preflight gate for unattended automations.
  157. ### 1. Discover — spend one query, not your context window
  158. The agent asks for what it needs in plain keywords via `retrieve_tools`:
  159. ```json
  160. { "query": "create github issue", "limit": 5 }
  161. ```
  162. MCPProxy runs a BM25 search across every connected server and returns only the top-ranked matches — each with a `call_with` hint recommending the right call variant for its annotations:
  163. ```json
  164. {
  165. "tools": [
  166. { "name": "github:create_issue", "score": 0.89, "call_with": "call_tool_write" },
  167. { "name": "gitlab:create_issue", "score": 0.72, "call_with": "call_tool_write" }
  168. ]
  169. }
  170. ```
  171. This is where the token savings come from: the schemas of the hundreds of tools the agent *didn't* need never enter its context. The agent loads full schemas on demand with `describe_tool` (batch up to 5 ids) only for the tools it's about to use.
  172. ### 2. Call — with declared intent
  173. The agent executes the tool through the variant matching its intent (`call_tool_read`, `call_tool_write`, or `call_tool_destructive`), addressing it as `server:tool`:
  174. ```json
  175. {
  176. "name": "github:create_issue",
  177. "args": { "repo": "acme/api", "title": "Bug report" },
  178. "intent_reason": "Filing bug per user request"
  179. }
  180. ```
  181. MCPProxy validates the intent against the tool's annotations (a "read" call can't reach a destructive tool) and checks quarantine and approval state before the call is forwarded. Sensitive-data detection flags potential secrets in arguments and responses in the activity log; it does not block the call by default. Optional [output sanitisation](https://docs.mcpproxy.app/features/output-sanitisation/) can redact detected secrets or block critical detections in supported text responses before they are forwarded. It does not cover tool arguments, non-text content, direct routing mode, or upstream error responses.
  182. ### 3. Audit — every call is on the record
  183. Calls are recorded in the local [Activity Log](https://docs.mcpproxy.app/features/activity-log/) with a request ID, so you can inspect what an agent did. The log is bounded by configurable retention (age, record count and size) and a per-record response size cap, so it is an inspection and debugging aid, not a compliance guarantee:
  184. ```bash
  185. mcpproxy activity list # everything, newest first
  186. mcpproxy activity list --request-id <id> # one workflow, correlated
  187. ```
  188. ### Gate automations before they burn tokens
  189. For recurring headless jobs (cron, CI, n8n), don't let the agent discover a missing tool the expensive way. One preflight command checks that every required tool is ready — without contacting any upstream server — and reports exactly why when it isn't (server quarantined, tool changed since approval, OAuth expired, typo'd id):
  190. ```bash
  191. mcpproxy tools preflight gh-ops:sync_issues slack:post_message --wait 10s
  192. case $? in
  193. 0) run-agent-session ;; # all ready — go
  194. 10) exit 75 ;; # transient (server starting) — let the next cron tick retry
  195. 11) page-operator ;; # blocked — someone must approve / enable / log in
  196. 12) fail-pipeline ;; # unknown tool id — the automation itself is misconfigured
  197. esac
  198. ```
  199. See [Required-Tools Preflight](https://docs.mcpproxy.app/features/tools-preflight/) for the full reason taxonomy, REST endpoint, and GitHub Actions / n8n recipes.
  200. ---
  201. ## 🔐 Optional HTTPS Setup
  202. MCPProxy works with HTTP by default for easy setup. HTTPS is optional and primarily useful for production environments or when stricter security is required.
  203. **💡 Note**: Most users can stick with HTTP (the default) as it works perfectly with all supported clients including Claude Desktop, Cursor, and VS Code.
  204. ### Quick HTTPS Setup
  205. **1. Enable HTTPS** (choose one method):
  206. ```bash
  207. # Method 1: Environment variable
  208. export MCPPROXY_TLS_ENABLED=true
  209. mcpproxy serve
  210. # Method 2: Config file
  211. # Edit ~/.mcpproxy/mcp_config.json and set "tls.enabled": true
  212. ```
  213. **2. Trust the certificate** (one-time setup):
  214. ```bash
  215. mcpproxy trust-cert
  216. ```
  217. **3. Use HTTPS URLs**:
  218. - MCP endpoint: `https://localhost:8080/mcp`
  219. - Web UI: `https://localhost:8080/ui/`
  220. ### Claude Desktop Integration
  221. For Claude Desktop, add this to your `claude_desktop_config.json`:
  222. **HTTP (Default - Recommended):**
  223. ```json
  224. {
  225. "mcpServers": {
  226. "mcpproxy": {
  227. "command": "npx",
  228. "args": [
  229. "-y",
  230. "mcp-remote",
  231. "http://localhost:8080/mcp"
  232. ]
  233. }
  234. }
  235. }
  236. ```
  237. **HTTPS (With Certificate Trust):**
  238. ```json
  239. {
  240. "mcpServers": {
  241. "mcpproxy": {
  242. "command": "npx",
  243. "args": [
  244. "-y",
  245. "mcp-remote",
  246. "https://localhost:8080/mcp"
  247. ],
  248. "env": {
  249. "NODE_EXTRA_CA_CERTS": "~/.mcpproxy/certs/ca.pem"
  250. }
  251. }
  252. }
  253. }
  254. ```
  255. ### Certificate Management
  256. - **Automatic generation**: Certificates created on first HTTPS startup
  257. - **Multi-domain support**: Works with `localhost`, `127.0.0.1`, `::1`
  258. - **Trust installation**: Use `mcpproxy trust-cert` to add to system keychain
  259. - **Certificate location**: `~/.mcpproxy/certs/` (ca.pem, server.pem, server-key.pem)
  260. ### Troubleshooting HTTPS
  261. **Certificate trust issues**:
  262. ```bash
  263. # Re-trust certificate
  264. mcpproxy trust-cert --force
  265. # Check certificate location
  266. ls ~/.mcpproxy/certs/
  267. # Test HTTPS connection
  268. curl -k https://localhost:8080/api/v1/status
  269. ```
  270. **Claude Desktop connection issues**:
  271. - Ensure `NODE_EXTRA_CA_CERTS` points to the correct ca.pem file
  272. - Restart Claude Desktop after config changes
  273. - Verify HTTPS is enabled: `mcpproxy serve --log-level=debug`
  274. ---
  275. ## Documentation
  276. ### Getting Started
  277. - [Installation](https://docs.mcpproxy.app/getting-started/installation/)
  278. - [Quick Start](https://docs.mcpproxy.app/getting-started/quick-start/)
  279. ### Configuration
  280. - [Config File Reference](https://docs.mcpproxy.app/configuration/config-file/)
  281. - [Upstream Servers](https://docs.mcpproxy.app/configuration/upstream-servers/)
  282. - [Environment Variables](https://docs.mcpproxy.app/configuration/environment-variables/)
  283. ### Features
  284. - [Search & Tool Discovery](https://docs.mcpproxy.app/features/search-discovery/)
  285. - [Security Quarantine](https://docs.mcpproxy.app/features/security-quarantine/)
  286. - [Security Scanner Plugins](https://docs.mcpproxy.app/features/security-scanner-plugins/)
  287. - [Docker Security Isolation](https://docs.mcpproxy.app/features/docker-isolation/)
  288. - [Secrets & Keyring Integration](https://docs.mcpproxy.app/features/keyring-integration/)
  289. - [OAuth Authentication](https://docs.mcpproxy.app/features/oauth-authentication/)
  290. - [Code Execution](https://docs.mcpproxy.app/features/code-execution/)
  291. - [Activity Log](https://docs.mcpproxy.app/features/activity-log/)
  292. - [Required-Tools Preflight](https://docs.mcpproxy.app/features/tools-preflight/)
  293. - [Agent Tokens](https://docs.mcpproxy.app/features/agent-tokens/)
  294. - [Sensitive Data Detection](https://docs.mcpproxy.app/features/sensitive-data-detection/)
  295. ### CLI Reference
  296. - [Command Reference](https://docs.mcpproxy.app/cli/command-reference/)
  297. - [Management Commands](https://docs.mcpproxy.app/cli/management-commands/)
  298. - [Activity Commands](https://docs.mcpproxy.app/cli/activity-commands/)
  299. - [Security Commands](https://docs.mcpproxy.app/cli/security-commands/)
  300. ### API
  301. - [REST API](https://docs.mcpproxy.app/api/rest-api/)
  302. - [MCP Protocol](https://docs.mcpproxy.app/api/mcp-protocol/)
  303. ---
  304. ## Contributing
  305. We welcome issues, feature ideas, and PRs!
  306. ### Development Setup
  307. ```bash
  308. make dev-setup # Install swag, frontend deps, Playwright
  309. brew install prek # Install pre-commit hook runner (or: uv tool install prek)
  310. prek install # Install pre-commit hooks
  311. prek install --hook-type pre-push # Install pre-push hooks
  312. ```
  313. ### Pre-commit Hooks
  314. We use [prek](https://github.com/j178/prek) to catch issues before they reach CI:
  315. | Hook | Stage | What it does |
  316. |------|-------|-------------|
  317. | `gofmt` | pre-commit | Auto-formats staged Go files |
  318. | `trailing-whitespace` | pre-commit | Removes trailing whitespace |
  319. | `end-of-file-fixer` | pre-commit | Ensures files end with newline |
  320. | `check-merge-conflict` | pre-commit | Detects merge conflict markers |
  321. | `swagger-verify` | pre-push | Fails if OpenAPI spec is out of date |
  322. | `go-build` | pre-push | Verifies the project compiles |
  323. Run hooks manually: `prek run --all-files`
  324. ### Build & Test
  325. ```bash
  326. make build # Build frontend + backend
  327. make swagger # Regenerate OpenAPI spec
  328. make test # Unit tests
  329. make test-e2e # E2E tests
  330. make lint # Run linters
  331. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.