MCPProxy.app: Supercharge AI Agents, Safely

📺 全編のウォークスルーを見る  ·  📚 ドキュメントを読む  ·  🌐 mcpproxy.app

上のデモでは、組み込みのウェブ UIを紹介しています。MCPProxy のコアは macOS、Linux、Windows 用の単一バイナリです。ウェブ UI はその中に含まれているため、追加のサービスを実行する必要はありません。macOSでは、オプションのメニューバーアプリを使うと、ワンクリックで便利に操作できます（起動／停止、サーバーの状態確認、隔離、ログ）。

## MCPProxy を選ぶ理由

• API の制限を超えて拡張 – 数百の MCP サーバーをフェデレーションし、Cursor の 40 ツール制限と OpenAI の 128 関数上限を回避します。
• ツール定義に使うコンテキストを削減 – エージェントには、MCPProxy の検出・実行ツール（retrieve_tools、describe_tool、call_tool_* の各バリアントといくつかの管理ツール）のみが表示されます。上流のツールカタログ全体ではなく、スキーマは必要に応じて取得します（retrieve_tools および code_execution ルーティングの場合。direct ルーティングでは上流のツールが個別に表示されます。ルーティングモードを参照）。削減できるコンテキスト量は、ツール数、ルーティングモード、クライアント、タスクによって異なります。トークン削減：測定対象と対象外を参照してください。
• 使用前にレビュー – 新しいサーバーは隔離され、レビューして承認するまで、そのツールはエージェントに公開されません。また、デフォルトのmanual信頼モードでは、承認済みツールの定義に後から加えられた変更のほとんども、再びレビューの対象になります。既知の例外：scanモード以外での入力スキーマのみの編集、新しく追加された出力スキーマ、説明が空の状態で承認されたツールへの説明の追加は、保留されずに受け入れられます。scanモードでは問題のない変更が受け入れられますが、検出器が見逃す変更もあります。autoモードでは変更は保留されません。これにより、悪意のあるツール定義（ツールポイズニング攻撃）への露出を減らしますが、安全を保証するものではありません。隔離の対象範囲と対象外を参照してください。
• プラグイン式のセキュリティスキャナー – 承認前に、隔離されたサーバーに対して Snyk、Semgrep、Trivy、Cisco などの Docker ベースのスキャナーを実行できます。検出結果は、複合リスクスコアとともに SARIF 形式に正規化されます。セキュリティスキャナープラグインを参照してください。
• オフライン対応、クロスプラットフォーム – macOS（Intel と Apple Silicon）、Windows（x64 と ARM64）、Linux（x64 と ARM64）に対応する単一のコアバイナリを提供し、Web UI を内蔵しています。macOS 版には、オプションのメニューバーアプリも同梱されています。

トークン削減：測定対象と対象外

オンデマンド検出により、エージェントが最初にコンテキストへ読み込む上流ツール定義の数を減らします。削減率は一定ではありません。接続されているツールの数に応じて変化し、ルーティングモード、クライアント、タスクによって異なります。MCPProxy は、トークン削減率や精度向上率の大きな数値を公表しておらず、レイテンシについても主張していません。

リポジトリで測定しているのは、ファーストパーティーによる決定論的な推定値です（測定方法およびgo run ./bench/cmd/benchでの再現方法はbench/README.mdを参照してください）。

• コーパス：固定された45ツールの参照コーパス。ツールの名前と説明のみをカウントし（入力スキーマは除外）、cl100k_baseを使用します。
• 指標：プロキシ独自の検出、呼び出し、管理ツールを含む、初期ツールメニューのトークン数。ワークフロー全体のトークン数、レイテンシ、タスクの成功率ではありません。
• 結果：この45ツールのコーパスでは、プロキシ独自のツールに固定コストがかかるため、プロキシの初期メニューは上流の全ツールを列挙する場合よりも大きくなります（retrieve_toolsモードで2625トークン、code_executionモードで1874トークン。ベースラインは1730トークン）。削減が見込めるのは上流ツールの数が損益分岐点を超えた場合のみです。そのため、パーセンテージを示す際はツール数も併記してください。

---

クイックスタート

1. インストール

macOS（推奨 — DMG インストーラー）：

お使いのアーキテクチャに対応する最新の DMG インストーラーをダウンロードします。

• Apple Silicon（M1/M2）： DMG をダウンロード → mcpproxy-*-darwin-arm64.dmg
• Intel Mac： DMG をダウンロード → mcpproxy-*-darwin-amd64.dmg

Windows（推奨 — インストーラー）：

お使いのアーキテクチャに対応する最新の Windows インストーラーをダウンロードします。

• x64（64 ビット）： インストーラーをダウンロード → mcpproxy-setup-*-amd64.exe
• ARM64： インストーラーをダウンロード → mcpproxy-setup-*-arm64.exe

インストーラーは自動的に以下を実行します。

• mcpproxy.exe（コアサーバー）と mcpproxy-tray.exe（システムトレイアプリ）の両方を Program Files にインストールします
• コマンドラインからアクセスできるよう、MCPProxy をシステム PATH に追加します
• スタートメニューのショートカットを作成します
• サイレントインストールに対応しています：.\mcpproxy-setup.exe /VERYSILENT

その他のインストール方法：

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

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
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 リポジトリ、自動更新は 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

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

apt および dnf パッケージには、セキュリティ強化済みの systemd ユニットが含まれており、サービスが自動的に起動します。リポジトリ署名鍵のフィンガープリント：3B6F A1AD 5D53 59DA 51F1 8DDC E1B5 9B9B A1CB 8A3B。

単発の .deb / .rpm ダウンロード（ネットワークに接続されていない環境へのインストール）の場合は、最新リリースからダウンロードしてください。

手動ダウンロード（全プラットフォーム）：

• Linux tarball：AMD64 | ARM64
• Windows：AMD64 | ARM64

プレリリースビルド（最新機能）：

最新機能を試してみませんか？next ブランチからプレリリースビルドをダウンロードできます。

1. GitHub Actionsにアクセスします
2. 最新の成功した「Prerelease」ワークフロー実行をクリックします
3. Artifacts からダウンロードします。
   • dmg-darwin-arm64（Apple Silicon Mac）
   • dmg-darwin-amd64（Intel Mac）
   • versioned-linux-amd64、versioned-windows-amd64（その他のプラットフォーム）

注：プレリリースビルドは macOS 向けに署名・公証されていますが、最先端の機能が含まれているため、不安定な場合があります。

• macOS：Intel | Apple Silicon

Go 1.26+ が使える環境：

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

2. 実行

mcpproxy serve          # starts HTTP server on :8080 and shows tray

3. 最初のサーバーを追加して承認する

新しいサーバーはレビューするまで隔離状態に置かれるため、サーバーの追加は「追加してからレビューして承認する」という2段階の手順です。実際のリモートサーバー（Context7）を使った詳しい手順は、公開されているクイックスタートをご覧ください。概要は次のとおりです（Context7は公開されている読み取り専用のドキュメントサーバーです。信頼できる任意のサーバーに置き換えてください）。

# 1. add (held in quarantine until approved)
mcpproxy upstream add context7 https://mcp.context7.com/mcp

# 2. review: capture the tool definitions, run the offline scan, read the verdict
mcpproxy review fetch context7
mcpproxy security rescan context7
mcpproxy review show context7

# 3. approve (with no --tools/--all, only read-only tools with a clean scan are allowed)
mcpproxy review approve context7 --yes

# 4. one harmless read, then see it in the activity log
mcpproxy call tool-read -t context7:resolve-library-id -j '{"libraryName":"vue-router","query":"routing"}'
mcpproxy activity list --limit 3

スキャンに問題がなかったとしても、サーバーが安全だと証明されたわけではありません。オフラインチェックでツール定義に問題が見つからなかったという意味にすぎません。承認する内容は確認してください。

~/.mcpproxy/mcp_config.jsonを手動で編集することもできます。初めて確認されたエントリは、同様にレビューのため保留されます。

{
  "listen": "127.0.0.1:8080",
  "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 }
  ]
}

詳しいリファレンスについては設定とアップストリームサーバーをご覧ください。また、レビューゲートの対象範囲と対象外についてはセキュリティ隔離をご覧ください。

4. IDE／AI ツールに接続する

📖 セットアップガイドの全文 - Cursor、VS Code、Claude Desktop、Gooseの詳しい手順

Cursorにプロキシを追加する

ワンクリックでCursor IDEにインストール

手動インストール

1. Cursorの設定を開きます
2. 「Tools & Integrations」をクリックします
3. MCPサーバーを追加します

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

---

MCPProxyを通じてAIエージェントが動作する仕組み

接続すると、エージェントにはアップストリームのスキーマが何百件も表示される代わりに、MCPProxyに組み込まれた少数のツールが表示されます。一般的なセッションは「検索、呼び出し、監査」の3段階で進みます。無人の自動化では、オプションの事前チェックゲートも利用できます。

1. 検索 — コンテキストウィンドウではなく、クエリを1回使う

エージェントはretrieve_toolsを使い、必要なものを平易なキーワードで問い合わせます。

{ "query": "create github issue", "limit": 5 }

MCPProxyは接続されているすべてのサーバーを対象にBM25検索を実行し、ランキング上位の候補だけを返します。各候補には、アノテーションに応じた適切な呼び出しバリアントを推奨するcall_withヒントが含まれます。

{
  "tools": [
    { "name": "github:create_issue", "score": 0.89, "call_with": "call_tool_write" },
    { "name": "gitlab:create_issue", "score": 0.72, "call_with": "call_tool_write" }
  ]
}

ここでトークンを節約できます。エージェントが必要としなかった何百ものツールのスキーマは、コンテキストに取り込まれません。エージェントは、これから使用するツールに限り、describe_toolを使って必要に応じて完全なスキーマを読み込みます（一度に最大5個のIDを指定できます）。

2. 呼び出し — 意図を明示する

エージェントは、意図に一致するバリアント（call_tool_read、call_tool_write、またはcall_tool_destructive）を使ってツールを実行し、server:tool形式で指定します。

{
  "name": "github:create_issue",
  "args": { "repo": "acme/api", "title": "Bug report" },
  "intent_reason": "Filing bug per user request"
}

MCPProxyは、ツールのアノテーションに照らして意図を検証します（「読み取り」呼び出しで破壊的なツールを実行することはできません）。また、呼び出しを転送する前に、隔離状態と承認状態を確認します。機密データ検出機能は、引数や応答に含まれる可能性のある秘密情報にフラグを付け、アクティビティログに記録します。デフォルトでは呼び出しをブロックしません。オプションの出力サニタイズでは、検出された秘密情報を編集するか、対応するテキスト応答内で重大な検出があった場合に、転送前にブロックできます。ツールの引数、テキスト以外のコンテンツ、直接ルーティングモード、アップストリームのエラー応答は対象外です。

3. 監査 — すべての呼び出しが記録される

呼び出しはリクエストIDとともにローカルのアクティビティログに記録されるため、エージェントが行った操作を確認できます。ログには設定可能な保持期間（経過時間、レコード数、サイズ）と、レコードごとの応答サイズ上限があります。そのため、これは調査やデバッグを支援するものであり、コンプライアンスを保証するものではありません。

mcpproxy activity list                          # everything, newest first
mcpproxy activity list --request-id <id>        # one workflow, correlated

トークンを消費する前にゲート自動化を行う

定期的に実行するヘッドレスジョブ（cron、CI、n8n）では、不足しているツールをエージェントが高コストな方法で見つけることがないようにしましょう。事前チェック用のコマンドを実行すれば、上流サーバーに接続せずに、必要なすべてのツールが利用可能な状態かを確認できます。利用できない場合は、その理由（サーバーが隔離されている、承認後にツールが変更された、OAuth の有効期限切れ、ID の入力ミス）を正確に報告します。

mcpproxy tools preflight gh-ops:sync_issues slack:post_message --wait 10s
case $? in
  0)  run-agent-session ;;   # all ready — go
  10) exit 75 ;;             # transient (server starting) — let the next cron tick retry
  11) page-operator ;;       # blocked — someone must approve / enable / log in
  12) fail-pipeline ;;       # unknown tool id — the automation itself is misconfigured
esac

理由の分類、REST エンドポイント、GitHub Actions／n8n のレシピについては、必須ツールの事前チェックをご覧ください。

---

🔐 HTTPS の任意設定

MCPProxy は、簡単にセットアップできるよう、デフォルトで HTTP を使用します。HTTPS は任意で、主に本番環境や、より厳格なセキュリティが必要な場合に役立ちます。

💡 注記：サポート対象のすべてのクライアント（Claude Desktop、Cursor、VS Code など）で問題なく動作するため、ほとんどのユーザーはデフォルトの HTTP のままで構いません。

HTTPS のクイックセットアップ

1. HTTPS を有効にする（いずれかの方法を選択）：

# Method 1: Environment variable
export MCPPROXY_TLS_ENABLED=true
mcpproxy serve

# Method 2: Config file
# Edit ~/.mcpproxy/mcp_config.json and set "tls.enabled": true

2. 証明書を信頼する（初回のみ）：

mcpproxy trust-cert

3. HTTPS の URL を使用する：

• MCP エンドポイント：https://localhost:8080/mcp
• Web UI：https://localhost:8080/ui/

Claude Desktop との連携

Claude Desktop の場合は、claude_desktop_config.json に次の設定を追加します。

HTTP（デフォルト — 推奨）：

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

HTTPS（証明書を信頼する場合）：

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

証明書の管理

• 自動生成：HTTPS の初回起動時に証明書が作成されます
• 複数ドメインのサポート：localhost、127.0.0.1、::1 で動作します
• 信頼のインストール：mcpproxy trust-cert を使用して、システムのキーチェーンに追加します
• 証明書の場所：~/.mcpproxy/certs/（ca.pem、server.pem、server-key.pem）

HTTPS のトラブルシューティング

証明書の信頼に関する問題：

# Re-trust certificate
mcpproxy trust-cert --force

# Check certificate location
ls ~/.mcpproxy/certs/

# Test HTTPS connection
curl -k https://localhost:8080/api/v1/status

Claude Desktop の接続に関する問題：

• NODE_EXTRA_CA_CERTS が正しい ca.pem ファイルを指していることを確認してください
• 設定を変更した後は、Claude Desktop を再起動してください
• HTTPS が有効になっていることを確認してください：mcpproxy serve --log-level=debug

---

ドキュメント

はじめに

• インストール
• クイックスタート

設定

• 設定ファイルのリファレンス
• 上流サーバー
• 環境変数

機能

• 検索とツールの検出
• セキュリティ隔離
• セキュリティスキャナープラグイン
• Docker セキュリティ分離
• シークレットとキーチェーンの連携
• OAuth 認証
• コード実行
• アクティビティログ
• 必須ツールの事前チェック
• エージェントトークン
• 機密データの検出

CLI リファレンス

• コマンドリファレンス
• 管理コマンド
• アクティビティコマンド
• セキュリティコマンド

API

• REST API
• MCP プロトコル

---

コントリビューション

Issue、機能のアイデア、PR を歓迎します！

開発環境のセットアップ

make dev-setup                # Install swag, frontend deps, Playwright
brew install prek             # Install pre-commit hook runner (or: uv tool install prek)
prek install                  # Install pre-commit hooks
prek install --hook-type pre-push  # Install pre-push hooks

コミット前フック

CI に到達する前に問題を検出するため、prek を使用しています。

フック	ステージ	内容
gofmt	pre-commit	ステージされた Go ファイルを自動フォーマットします
trailing-whitespace	pre-commit	行末の空白を削除します
end-of-file-fixer	pre-commit	ファイルが改行で終わるようにします
check-merge-conflict	pre-commit	マージコンフリクトのマーカーを検出します
swagger-verify	pre-push	OpenAPI 仕様が最新でない場合に失敗します
go-build	pre-push	プロジェクトがコンパイルできることを確認します

フックを手動で実行します：prek run --all-files

ビルドとテスト

make build          # Build frontend + backend
make swagger        # Regenerate OpenAPI spec
make test           # Unit tests
make test-e2e       # E2E tests
make lint           # Run linters