<p align="center">
<a href="https://mcpproxy.app" target="_blank" rel="noopener">
<img src="https://raw.githubusercontent.com/smart-mcp-proxy/mcpproxy-go/HEAD/docs/social.png" alt="MCPProxy — AI 에이전트의 성능을 안전하게 증폭시키다 · 모든 MCP 서버 앞에 위치한 단 하나의 안전한 엔드포인트" width="100%" />
</a>
</p>
<div align="center">
Release
Build
Go Report Card
Go Reference
License: MIT
GitHub stars
OpenSSF Scorecard
</div>
<p align="center">
<img src="https://raw.githubusercontent.com/smart-mcp-proxy/mcpproxy-go/HEAD/docs/demo.gif" alt="MCPProxy 웹 UI 데모: 서버 대시보드, 도구 검색, 활동 로그 및 보안 격리" width="900" />
</p>
<p align="center">
<strong >📺 <a href="https://youtu.be/2aKrgJnbbcw">전체 워크스루 시청</a></strong> ·
<strong >📚 <a href="https://docs.mcpproxy.app/">문서 읽기</a></strong> ·
<strong >🌐 <a href="https://mcpproxy.app">mcpproxy.app</a></strong>
</p>
위 데모는 임베디드 웹 UI를 보여줍니다. MCPProxy의 핵심은 macOS, Linux 및 Windows용 단일 바이너리이며, 웹 UI가 그 내부에 포함되어 있어 별도의 서비스 실행이 필요하지 않습니다. macOS에서는 선택적인 **메뉴 바 앱(menu-bar app)**을 통해 원클릭 편의성(시작/중지, 서버 상태 확인, 격리, 로그)을 추가로 제공합니다.
<div align="center">
<img src="https://raw.githubusercontent.com/smart-mcp-proxy/mcpproxy-go/HEAD/docs/screenshot-macos-tray.png" height="300" alt="MCPProxy macOS 메뉴 바 앱" />
<img src="https://raw.githubusercontent.com/smart-mcp-proxy/mcpproxy-go/HEAD/docs/screenshot-macos-activity.png" height="300" alt="MCPProxy macOS 앱 — 민감 데이터 탐지 기능이 포함된 활동 로그" />
<br />
<em style="font-size: 1.1em;">macOS 메뉴 바 앱 · macOS 앱의 활동 기록 및 감사(audit)</em>
</div>
왜 MCPProxy를 사용해야 하는가?
- API 제한을 초월한 확장성 확보 – Cursor의 40개 도구(tool) 제한과 OpenAI의 128개 함수(function) 한도를 우회하면서 수백 개의 MCP 서버를 페더레이션(federate)할 수 있습니다.
- 도구 정의에 필요한 컨텍스트 절감 – 에이전트(Agents)는 전체 업스트림 도구 카탈로그 대신 MCPProxy의 발견 및 실행 도구 세트(
retrieve_tools, describe_tool, call_tool_* 변형, 그리고 몇 가지 관리 도구)만 확인하며, 필요할 때 스키마를 가져옵니다 (retrieve_tools 및 code_execution 라우팅에서; direct 라우팅은 업스트림 도구를 개별적으로 노출합니다. 라우팅 모드(Routing modes) 참조). 이로 절약되는 컨텍스트 양은 도구의 수, 라우팅 모드, 클라이언트 및 작업에 따라 달라지므로, 토큰 절감: 측정되는 것과 그렇지 않은 것을 참고하십시오.
- 사용 전 검토 – 새로운 서버는 격리(quarantined)되며, 사용자가 이를 검토하고 승인할 때까지 에이전트로부터 도구가 차단됩니다. 또한 기본
manual 신뢰 모드에서는 승인된 도구 정의에 대한 대부분의 후속 변경 사항은 다시 검토를 위해 보류됩니다. 알려진 예외: scan 모드가 아닌 경우 입력 스키마만 수정하는 편집, 새로 추가된 출력 스키마, 그리고 빈 설명으로 승인된 도구에 추가된 설명은 보류 없이 허용됩니다. scan 모드는 깨끗한 변경 사항을 허용하며 탐지기가 놓치는 것은 놓칩니다. auto 모드는 변경 사항을 보류하지 않습니다. 이는 악성 도구 정의(Tool Poisoning Attacks)에 대한 노출 위험을 줄여줍니다. 하지만 안전성을 보장하는 것은 아닙니다.
확산 방지(quarantine)가 무엇을 포함하고 무엇을 포함하지 않는지 확인하세요([https://docs.mcpproxy.app/features/security-quarantine/#what-quarantine-does-and-does-not-cover]).
- 플러그인 보안 스캐너 (Pluggable security scanners) – 승인하기 전에 Snyk, Semgrep, Trivy, Cisco 및 기타 Docker 기반 스캐너를 격리된 서버에 실행할 수 있습니다. 발견된 결과는 SARIF 형식으로 정규화되며 복합 위험 점수(composite risk score)가 부여됩니다. 보안 스캐너 플러그인([https://docs.mcpproxy.app/features/security-scanner-plugins/])을 확인하세요.
- 오프라인 및 크로스 플랫폼 작동 (Works offline & cross-platform) – macOS(Intel 및 Apple Silicon), Windows(x64 및 ARM64), Linux(x64 및 ARM64)를 위한 단일 코어 바이너리를 제공하며, 웹 UI가 내장되어 있습니다. 또한, macOS는 선택적 메뉴 바 앱을 추가로 제공합니다.
토큰 절약: 측정되는 것과 그렇지 않은 것
온디맨드 디스커버리(On-demand discovery)는 에이전트가 사전에 컨텍스트에 로드하는 업스트림 도구 정의의 양을 줄여줍니다. 이 절약량은 고정된 비율이 아니며, 연결된 도구 수와 라우팅 모드, 클라이언트 및 작업에 따라 달라집니다. MCPProxy는 헤드라인 토큰 감소나 정확도 개선 수치를 공개하지 않으며, 지연 시간(latency)에 대한 주장도 하지 않습니다.
저장소에서 자체적으로 측정하는 바는 다음과 같으며, 이는 일차적이고 결정론적인 추정치입니다 (방법 및 재현을 위해서는 bench/README.md를 참조하고 go run ./bench/cmd/bench로 실행하세요):
- 코퍼스(Corpus): 동결된 45개 도구 참조 코퍼스; 도구 이름과 설명만 계산하며 (입력 스키마 제외), cl100k_base를 사용합니다.
- 메트릭(Metric): 프록시 자체의 디스커버리, 호출 및 관리 도구를 포함한 초기 도구 메뉴 크기(토큰 단위). 전체 워크플로우 토큰이나 지연 시간, 작업 성공률은 아닙니다.
- 결과: 이 45개 도구 코퍼스에서 프록시의 초기 메뉴는 모든 업스트림 도구를 나열하는 것보다 더 큰 크기입니다 (retrieve_tools 모드에서 2625 토큰, code_execution 모드에서 1874 토큰으로, 기준선인 1730 토큰 대비). 이는 프록시 자체의 도구가 고정된 비용을 가지기 때문입니다. 따라서 절약량은 업스트림 도구 수가 손익분기점(break-even number)을 넘어서야 나타나므로, 백분율로 도구 수를 언급하지 마십시오.
빠른 시작 (Quick Start)
1. 설치
macOS (권장 - DMG 설치 프로그램):
사용자의 아키텍처에 맞는 최신 DMG 설치 프로그램을 다운로드하세요:
- Apple Silicon (M1/M2): DMG 다운로드 →
mcpproxy-*-darwin-arm64.dmg
- Intel Mac: DMG 다운로드 →
mcpproxy-*-darwin-amd64.dmg
Windows (권장 - 설치 프로그램):
사용자의 아키텍처에 맞는 최신 Windows 설치 프로그램을 다운로드하세요:
설치 프로그램은 자동으로 다음 작업을 수행합니다:
mcpproxy.exe (핵심 서버, core server)와 mcpproxy-tray.exe (시스템 트레이 앱, system tray app)를 Program Files에 모두 설치합니다.
- 명령줄 접근을 위해 시스템 PATH에 MCPProxy를 추가합니다.
- 시작 메뉴 바로가기를 생성합니다.
- 무인 설치(silent installation)를 지원합니다:
.\mcpproxy-setup.exe /VERYSILENT
대체 설치 방법:
macOS (Homebrew):
brew install --cask smart-mcp-proxy/mcpproxy/mcpproxy
...
Cask는 메뉴 바 앱(CLI를 번들로 포함)을 설치하며, Formula는 CLI 바이너리만 설치합니다. 둘 다 brew upgrade를 통해 업데이트됩니다.
Linux (Debian/Ubuntu) — apt 저장소, 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
...
Linux (Fedora / RHEL / Rocky / AlmaLinux) — dnf 저장소, dnf upgrade를 통한 자동 업데이트:
sudo dnf config-manager --add-repo https://rpm.mcpproxy.app/mcpproxy.repo
sudo dnf install -y mcpproxy
아치 리눅스 (AUR): mcpproxy-bin
yay -S mcpproxy-bin
git clone https://aur.archlinux.org/mcpproxy-bin.git && cd mcpproxy-bin && makepkg -si
apt 및 dnf 패키지는 강화된 systemd 유닛을 포함하며 서비스를 자동으로 시작합니다. 저장소 서명 키 지문(fingerprint): 3B6F A1AD 5D53 59DA 51F1 8DDC E1B5 9B9B A1CB 8A3B.
일회성 .deb / .rpm 다운로드(에어 갭 설치)의 경우, [최신 릴리스]에서 받으세요.
수동 다운로드 (모든 플랫폼):
프리릴리스 빌드 (최신 기능):
가장 새로운 기능을 사용해 보고 싶으신가요? next 브랜치에서 프리릴리스 빌드를 다운로드하세요:
- [GitHub Actions]로 이동합니다(https://github.com/smart-mcp-proxy/mcpproxy-go/actions)
- 가장 최근에 성공한 "Prerelease" 워크플로우 실행을 클릭합니다.
- Artifacts에서 다운로드합니다:
dmg-darwin-arm64 (Apple Silicon Mac용)
dmg-darwin-amd64 (Intel Mac용)
versioned-linux-amd64, versioned-windows-amd64 (기타 플랫폼용)
참고: 프리릴리스 빌드는 macOS용으로 서명 및 공증되었지만, 불안정할 수 있는 최첨단 기능을 포함하고 있습니다.
Go 1.26 이상 버전이 설치된 환경 어디서든:
go install github.com/smart-mcp-proxy/mcpproxy-go/cmd/mcpproxy@latest
2. 실행 (Run)
3. 첫 번째 서버 추가 및 승인하기
새 서버는 검토할 때까지 격리(quarantine) 상태로 유지되므로, 서버 추가는 '추가'와 '검토 및 승인'의 2단계 과정입니다. 실제 원격 서버(Context7)를 사용한 전체 워크스루는 Quick Start에 게시되어 있습니다. 간단히 말해 (Context7은 공개적이고 읽기 전용의 문서화 서버이므로, 신뢰하는 다른 서버로 대체할 수 있습니다):
mcpproxy upstream add context7 https://mcp.context7.com/mcp
...
깨끗한 스캔(clean scan)이 서버가 안전하다는 증거는 아닙니다. 단지 오프라인 검사(offline checks)에서 도구 정의(tool definitions)에 아무것도 찾지 못했다는 의미일 뿐입니다. 승인할 항목을 검토하십시오.
또한, 수동으로 ~/.mcpproxy/mcp_config.json을 편집할 수도 있습니다. 처음 발견된 항목(first-seen entry)도 같은 방식으로 검토를 위해 보류됩니다:
{
"listen": "127.0.0.1:8080",
"mcpServers": [
...
전체 참조는 Configuration 및 Upstream Servers를 참고하고, 검토 게이트(review gate)가 무엇을 다루고 무엇을 다루지 않는지는 Security Quarantine를 참조하십시오.
4. IDE/AI 도구에 연결하기
📖 전체 설정 가이드 - Cursor, VS Code, Claude Desktop, Goose에 대한 상세 지침
Cursor에 프록시 추가하기
Cursor IDE에서 원클릭 설치
Install in Cursor IDE
수동 설치
- Cursor 설정 열기
- "도구 및 통합(Tools & Integrations)" 클릭
- MCP 서버 추가하기
"MCPProxy": {
"type": "http",
"url": "http://localhost:8080/mcp/"
...
AI 에이전트가 MCPProxy를 통해 작동하는 방식
연결되면, 에이전트는 수백 개의 상위 스키마(upstream schemas) 대신 소수의 내장된 MCPProxy 도구를 보게 됩니다. 일반적인 세션은 디스커버(discover), 콜(call), 감사(audit)의 세 단계와 비감독 자동화(unattended automations)를 위한 선택적 사전 점검 게이트(preflight gate)가 포함됩니다.
1. 디스커버(Discover) — 컨텍스트 창이 아닌 단 하나의 쿼리만 사용
에이전트는 retrieve_tools를 통해 필요한 것을 일반 키워드로 요청합니다:
{ "query": "create github issue", "limit": 5 }