Phantom Secrets：実際のシークレットを AI コーディングエージェントに見せないローカルプロキシと MCP サーバー

誰に向いているか

AI コーディングエージェントを日常の開発に取り込んでいて、プロジェクトの .env に実際のシークレットを保存している場合、ログ、エラー出力、コンテキスト片方がシークレット漏洩の経路になりえます。Phantom は「アプリはそのまま実値を取得できる」と「エージェントには決してシークレットの値が見えない」の間に明確な境界を引きたい開発者、およびシークレットを一度に配布・更新したいが、各個人のツールチェーンへ配り込むことを避けたいチームのためのものです。

その形態は「ローカルプロキシ + MCP サーバー」です。プロジェクトのシークレットはスコープ付きの phm_ プレースホルダに置き換えられ、アプリは認証済みのローカルプロキシ経由で実値を取得します。エージェント側には値が見えない MCP ツールだけが現れ、棚卸し・診断・制御されたリクエストに使われます。前提は、自分のマシンでプロキシプロセスを常駐させ、.env の書き換えを自分のバージョン管理の流れに組み込むことです。この手順を適当に省略することはできません。

3 分で最初の試行を

推奨される公式手順は Homebrew です。リポジトリが示す macOS へのインストールは 3 ステップの流れで、まず tap、次に trust、最後に install です。導入されるのは phantom と phantom-mcp の 2 つの実行ファイルで、リポジトリが示す v0.7.9 に対応します。

brew tap ashlrai/phantom
brew trust --formula ashlrai/phantom/phantom
brew install ashlrai/phantom/phantom

前提条件: macOS に Homebrew がインストール済みであること。Homebrew を使わずにソースから自前でビルドする場合、リポジトリはコンパイラツールチェーンのバージョンを固定しているため、ビルド環境には該当バージョンの Rust ツールチェーンが必要です。

続いては順序どおり 2 段の設定です。まずプロジェクトディレクトリに入って phantom init を実行します。これは書き込み操作である点に注意してください。該当プロジェクトの .env を書き換え、実際のキー値を phm_ プレースホルダに差し替えます。チェックポイントは実行前に .env のバックアップまたはコミットを確認し、コマンド出力で差し替え件数が想定どおりかを確認することです。2 段目はクライアントごとの設定を書き込む手順です。

phantom init
phantom setup --client claude

そのあとは読み取り専用の一歩で低リスクの検証をします。phantom list はシークレットの棚卸しを表示しますが、値は一切表示しません。確認できる成功のシグナルは、端末に項目名だけが列挙され、各項目の後ろに実際のシークレット文字が続かないことです。さらにエージェントにリポジトリをもう一度読ませると、取得されるのは phm_ で始まるものであって実値ではありません。

コマンドとオプションの完全な説明は公式リポジトリ https://github.com/ashlrai/phantom-secrets を参照してください

ユースケース

ケース 1：エージェントに「一覧は見えるが値は見えない」通路を渡す。エージェント側が得る MCP ツールは value-blind で、棚卸し・診断・制御されたリクエストの 3 つの用途をカバーします。リポジトリはこれらのツールを、能力的・状態的な検査およびリポジトリ状態の検査として位置づけており、プロバイダ側のアクションは一切発生しません。そのため「このプロジェクトにはどのシークレットが設定されているか、現在の経路は通っているか、リポジトリ内のどのファイルがプレースホルダを参照しているか」をエージェントに安心して尋ねられます。エージェントがシークレット値を返すことも、検査の合間にクラウド資源を勝手に変更することもありません。

ケース 2：アプリケーションのコードは実値で動かし続けつつ、実値をエージェントの視界から遮ります。置き換えは初期化段階で起こります。.env 内の実際のキー値はスコープ付きの phm_ プレースホルダになり、アプリは環境変数を通常どおり読み、送信したリクエストはローカルプロキシが受け取り、認証後に実値を取り戻します。プロキシ側の制御されたリクエスト入口は、棚卸し・診断の入口と同じ「値を見ない」制約を共有しているため、アプリは動作し続けながら、エージェントは依然としてシークレットそのものを手に入れることはできません。リポジトリの資料が示しているのはプロキシが「認証済み」のローカルプロキシだという点までで、認証方式の具体形は説明されていないため、この層はリポジトリの記述に従ってください。

使用上の境界

第一に、phantom init は .env を書き換えます。これは本物の書き込み操作です。実行前にバックアップまたはコミットし、置換前後の差分をそのまま公開チャンネルに貼らないでください。

第二に、エージェント側ツールの value-blind な性質が保証するのは「値が見えない」ことだけで、「何でもできる」ことではありません。リポジトリはこれらを能力・状態・リポジトリ状態の検査として位置づけており、プロバイダのアクション代行は行いません。実際のクラウド呼び出しは、アプリはローカルプロキシ経由で送信するリクエスト経路上で発生するため、切り分けを行う際はこの 2 つの区切りを区別してください。

第三に、これはリスクゼロのツールではありません。ローカルの .env とクライアント設定ファイルを読み取る必要があり、ローカルプロキシはリクエストをサードパーティのプロバイダに送信するため、シークレットは依然としてあなたのマシンと当該プロバイダの間を流れます。その経路を受け入れるかどうかは、組織がエージェント側にその存在を許しているかどうかによります。

第四に、リポジトリ内のインストール方法とコマンド説明はバージョンで変わるため、アップグレード前に公式リポジトリで必ず確認してください。