@proxycept/mcp — Proxycept MCPサーバーへのstdioブリッジ

薄いstdio↔HTTPブリッジです。Model Context Protocolサーバーをstdio上で動作させ、すべてのJSON-RPCメッセージをそのままProxycept MCPエンドポイント（デフォルトではhttps://proxycept.com/api/mcp）にAPIトークンをBearerヘッダーとして付けて転送します。

ほとんどの人はこのパッケージを必要としません。 Proxycept MCPサーバーはホスト型HTTPサーバーです。Claude DesktopやCursorはURLとAuthorizationヘッダーで接続でき、インストールは不要です。このパッケージはstdioのみを話すMCPクライアント向け、およびnpxがディレクトリ一覧で期待されるインストール方法であるために存在します。

インストール不要の方法、ツールカタログ、セキュリティモデルについては、proxycept.com/docs → 「Connect Claude or Cursor」、またはdocs/user-manual.md §14を参照してください。設定 → APIトークンには、そのデプロイ先を指定し、選択したトークンに名前を付けた同じ設定がコピー可能な状態で用意されています。トークンの値は作成時に一度だけ表示されるため、ブロックには置き換えるプレースホルダーが含まれています。

これではないもの

ツールリスト、ツールスキーマ、Proxycept固有のロジックは一切含まれていません。 tools/listはサーバーが応答し、このパッケージは応答しません。これは意図的です。サーバーがツールカタログの唯一の情報源であるため、サーバー側でツールが追加・変更されてもここでリリースする必要はなく、サポートすべきバージョンのずれもありません。もしツール名に特別な処理を追加したいためにこれを読んでいるのであれば、それは設計が間違っています。

必要条件

• Node.js 20以上（node --version）。

• Proxycept APIトークン（prx_live_…） — proxycept.com/settingsの設定 → APIトークン。

読み取り専用トークンを使用する

トークンは読み取り専用で作成してください。これがデフォルトであり、セキュリティの境界線です。提案ではありません。

Proxyceptの読み取りツールはキャプチャされたHTTPトラフィックを返します。これはあなたのアカウントが作成したものではないコンテンツです。悪意のある上流からの応答本文は、あたかも指示であるかのようにモデルに読み取られる可能性があります（「プロンプトインジェクション」）。明確に言うと：

read_write MCPトークンは、プロキシがキャプチャしたあらゆるものがあなたのProxycept設定に書き込めることを意味します。

他人のサーバーからの応答本文が、指示のように見えるように書かれていると、あなたのアカウントでモックルート、インターセプトパターン、停止したプロファイルになります。読み取り専用トークンは、そのチェーンをProxycept内で完了不能にします。注入された指示が呼び出すものが何もありません。

Proxyceptツールが返すものはすべて信頼できないデータとして扱い、指示として扱わないでください。特に、URLを取得したり、シェルを実行したり、ファイルを書き込んだりできる他のMCPサーバーが接続されている場合は注意してください。

本当に読み書きが必要な場合

あなたのセットアップを意図的に変更させるクライアントに対してのみ使用してください。その場合、以下のすべてを守ってください：

1. 別のトークンを作成する（トラフィックを読み取るために使用しているトークンをアップグレードしない）。

2. クライアントでProxyceptツール呼び出しに対して「常に許可」を有効にしない。

3. キャプチャされたトラフィックを読み取っている同じセッションで使用しない。それがまさに、注入された指示を実行可能にする組み合わせです。

読み書きトークンでもまだできないことが一つあります：キャプチャされたリクエストの再生。 replay_flowは実際のリクエストをキャプチャされた認証情報とともに第三者に再送信するため、Proxycept Webコンソール（設定 → AIクライアントを接続）で人間が承認する必要があります。AIクライアントは、どのようなトークンを持っていても、自身の再生を承認できません。

設定 — トークンは設定ファイルではなく環境変数に

MCPクライアントの設定はディスク上のプレーンテキストJSONであり、多くの場合クラウドストレージと同期されたディレクトリ内にあります。そこにprx_live_…トークンを貼り付けると、考えもしなかったバックアップに長期間有効な認証情報が残ります。環境変数を推奨します。

Claude Desktop（claude_desktop_config.json）、Cursor（~/.cursor/mcp.json）、およびその他のほとんどのクライアントは同じ形式を使用します：

{
  "mcpServers": {
    "proxycept": {
      "command": "npx",
      "args": ["-y", "@proxycept/mcp"],
      "env": {
        // Read from your shell environment; the secret itself stays out of this file.
        "PROXYCEPT_API_TOKEN": "${PROXYCEPT_API_TOKEN}"
      }
    }
  }
}

すべてのクライアントが設定内で${VAR}を展開するわけではありません。展開しない場合、次善の策は、クライアントが継承する場所（ログインシェルプロファイル、macOSのlaunchctl setenv、Linuxのsystemdユニット）で変数をエクスポートし、envブロックを完全に削除することです。ブリッジは継承された環境からPROXYCEPT_API_TOKENを読み取ります。リテラルトークンを設定ファイルに貼り付けることも機能しますが、最後の手段として使用してください。

コマンドラインの--tokenもサポートされていますが、推奨されません。引数はプロセスリストを介してマシン上のすべてのプロセスから見えるためです。

環境変数

すべての変数には対応するフラグがあります（--base-url、--url、--token、--timeout、--verbose）。

セルフホスト

PROXYCEPT_BASE_URL=https://proxy.internal.example PROXYCEPT_API_TOKEN=… npx -y @proxycept/mcp

プレーンテキストのhttp://はループバック以外では拒否されるため、トークンが平文のホップを越えることはありません。このパッケージはTLS検証を無効にするフラグを提供せず、今後も提供しません。

Node自体にはNODE_TLS_REJECT_UNAUTHORIZED=0というフラグがあり、プロセス全体の証明書検証をオフにしますが、ブリッジは非ループバックエンドポイントに対してこれが設定されている場合、起動を拒否します。サイレントに継承するのではなく、エラーを出します。このエラーに遭遇した場合は、変数を設定解除してください（シェルプロファイルとMCPクライアントのenvブロックを確認）。ほとんどの場合、他のデバッグの残骸であり、設定されたままではトークンが経路上の誰でも読める接続を介して送信されることになります。

セットアップを確認する

PROXYCEPT_API_TOKEN=prx_live_… npx -y @proxycept/mcp --check

実際のMCPハンドシェイクと実際のtools/listを実行し、サーバーが言ったことを表示します：

endpoint: https://proxycept.com/api/mcp
server:   proxycept 1.0.0 (MCP 2025-06-18)
tools:    20 — list_workspaces, list_profiles, …
ok

ツール数はサーバーから取得され、このパッケージからではないため、ここでリリースしなくても変わります。書き込みツールはすべてのクライアントにリストされますが、トークンがread_writeでない限りAPIレイヤーで拒否されます（以下参照）。

終了コード：0 正常 · 1 サーバーに到達できないか認証できない · 2 設定が不正。

問題が発生した場合

セキュリティ特性

• トークンはAuthorization: Bearer …として設定されたオリジンにのみ送信され、他の場所には送信されません。異なるオリジンへのリダイレクトは拒否され、フォローされません。認証情報は設定したホスト以外には渡されません。同一オリジンの307/308はフォローされます（最大3ホップ）。オリジンとメソッドの両方を保持することは、認証情報の再送信が誰が受け取るかを変えないことを意味し、リバースプロキシはこれらを発行するためです。301/302/303は拒否されます。POSTをGETとして再送信するとリクエストが静かに失われるためです。（ホスト型サーバーはリダイレクトしません。）

• トークンは決してログに記録されず、クライアントに返されることもありません。 stderrに書き込まれるすべての行、およびこのブリッジがstdoutに合成するすべてのエラーメッセージは、設定されたシークレット、prx_…トークンの形をしたもの、Bearer …文字列を削除するリダクターを通過します。これには--verboseモードや、サーバーが4xx/5xxの本文でエコーバックする認証情報も含まれます。最後のケースが重要なのは、stdoutがMCPクライアントであるため、モデルのコンテキストとクライアントのログに残るからです。スタックトレースは決して出力されません。それぞれについてテストがあります。

• プロトコルストリームは決して書き換えられません。 リダクションはこのブリッジが構築するメッセージに適用され、サーバー自身のJSON-RPCペイロードには適用されません。それらを改変すると、デバッグしているトラフィックが破損します。キャプチャされたトラフィックのリダクションはサーバーの仕事です（読み取りパスでマスキング拒否リストを適用します）。

• ディスクには何も書き込まれません。 キャッシュ、設定ファイル、認証情報ストアはありません。

• stdoutはプロトコルメッセージのみを運び、すべての診断情報はstderrに送られます。

• ランタイム依存関係はゼロです。このパッケージのnpm ls --omit=devは空です。唯一のサプライチェーンはNode自身です。

開発

cd clients/mcp
npm ci
npm test          # builds, then runs the suite against a fake JSON-RPC server
npm run typecheck

npm run check-package   # asserts the tarball ships every module, the bin, README and LICENSE

レイアウト：src/config.ts（設定の解決＋検証）、src/redact.ts（リダクション＋唯一のロガー）、src/http.ts（メッセージごとに1回のPOST；SSE、リダイレクトポリシー、HTTP→JSON-RPCエラーマッピング）、src/bridge.ts（汎用転送ループ）、src/stdio.ts（改行区切りJSONフレーミング）、src/cli.ts（引数、--check、配線）。

偽のサーバーに対して検証済み

スイートはtest/helpers.jsの偽のJSON-RPC HTTPサーバーに対して実行されます：そのままの転送（このパッケージが知らないメソッドも含む）、ヘッダー形状、Mcp-Session-Idとプロトコルバージョンのエコー、SSEストリーミング、202通知、HTTP→MCPエラーマッピング、バッチ処理、リダイレクトポリシー、セッション期限切れ、チャンク境界をまたぐNDJSONフレーミング、およびすべての出力からのトークンの不在。

実際のProxyceptに対して検証済み

--checkは、MCPサーバーが有効な実際のControl API（V4-T66）に対してエンドツーエンドで実行されています：実際のinitialize機能ネゴシエーション、実際のtools/list（20ツール）、読み取り専用のprx_live_トークンを使用。残りの未知数は本番環境固有のものです。ホスト型デプロイがMcp-Session-Idを発行するかどうか、長いツール呼び出しがJSONとSSEのどちらで返されるか、401/403/429本文の正確な文言などです。ブリッジは汎用的であるため、これらが異なってもコードの変更は必要ありません。https://proxycept.comに対するライブパスはPUBLISHING.mdのステップ5です。

公開（メンテナー向け）

リリースは意図的に手動で行われます。つまり、公開処理を行うCIジョブは意図的に存在しません。そのため、侵害されたワークフロートークンによって、顧客の認証情報を扱うパッケージが配信されることはありません。完全なランブック（組織の作成、事前チェック、正確な npm publish --access public の流れ、検証、非推奨化の手順）は、このディレクトリ内の PUBLISHING.md にあります。これは公開されるtarballには含まれません。