直接回答
MCP entry が設定に存在しても server 起動・protocol negotiation の証明にはなりません。各レイヤーを順に確認します。
このガイドで解決できること
MCP executable、argument、environment、stdio、HTTP、protocol、認証、tool discovery の失敗を修正する。
症状と影響範囲を確認する
client が MCP server の起動、initialize、認証、tool 公開失敗を報告します。
手動 command は動いても client 下では cwd、PATH、environment、stdout、config scope の違いで失敗します。
- 設定を変更する前に、ステータスまたは例外、レスポンス本文、request ID、UTC 時刻、クライアント版、最終ホストを保存します。
- 最小リクエストと失敗するワークフローを比較し、全体障害、モデル固有、機能固有のどれかを切り分けます。
- 認証情報、完全なプロンプト、顧客データ、非公開ファイルをスクリーンショットやサポート資料に含めません。
主な原因と責任境界
エラーは一つのレイヤーから得た証拠であり、下流全体の故障を証明するものではありません。まず次の可能性を順に検証します。
- executable、argument、working directory、PATH、必須 environment variable が誤っている。
- stdio server が stdout へ log・banner を出し protocol message を壊す。
- HTTP server が到達不可、未認証、または URL・transport が誤っている。
- client と server が initialize negotiation または tool schema discovery に失敗する。
レイヤー別に最小診断を行う
可変要素が最も少ないリクエストから開始します。アカウント、API ホスト、対象モデルは維持し、任意機能だけを外します。
一度に一項目だけ変更し、元のステータス、ヘッダー、本文、所要時間を残します。これによりクライアントのシリアライズとゲートウェイ・上流の挙動を分離できます。
- 01境界を確定server 名、config scope、command・URL、argument、cwd、環境変数名を確認します。
- 02基準を作成stdio を機密除去して単独起動し、HTTP は DNS、TCP、TLS、認証に分けて試します。
- 03一項目を比較initialize negotiation と選択 protocol version を保存します。
- 04決定的な証拠を記録tools/list と必要 schema を確認し、read-only tool を一件実行します。
codex mcp list --json 2>/dev/null || true
codex doctor --summary 2>/dev/null || true
claude mcp list 2>/dev/null || true
# 再分别使用 codex mcp get <name> 或 claude mcp get <name>。
# stdio 服务只运行可信命令的 --help，不执行来源不明的安装管道。
確認した根本原因に修正を適用する
証拠で確定したレイヤーだけを最小限変更します。決定的な設定エラーを広範な再試行や検証無効化で隠さないでください。
- 01障害レイヤーを修正正式 scope で executable、argument、cwd、environment、URL、transport を修正します。
- 02必要な動作を復元stdio log は stderr へ送り stdout を protocol frame 専用にします。
- 03一時回避策を除去protocol version と認証を整合し、最小 tool permission だけを許可します。
1. client list/get 能读取最终配置
2. server process 或 HTTP endpoint 可达
3. initialize 与 tools/list 成功
4. 一个只读工具返回预期结构
5. 日志无 token、项目秘密和协议污染一度の成功ではなく修正結果を検証する
最小確認が成功したら元の経路を再実行し、通常のストリーミング、同時実行数、タイムアウト条件でも安定することを確認します。
- stdio stdout に protocol message 以外が出ない。
- client と server が互換 protocol version を合意する。
- 必要な tool 名と schema が tools/list に現れる。
- write・破壊的 capability より先に read-only tool が成功する。
セキュリティ境界とエスカレーション資料
認証、通信、権限、検証を弱めず、かつ機密情報を公開しない範囲で、再現とエスカレーションに必要な証拠を収集します。
- secret を commit 対象の MCP config に直接記載しない。
- 第三者 MCP server と tool output を untrusted input として扱う。
- read-only filesystem・network scope から開始する。
- version、機密除去した config、stderr、initialize、tool list で共有する。
公式情報と検証範囲
本ガイドはプロトコル仕様とクライアント公式文書を根拠にしています。エラー文、再試行ヘッダー、設定項目はサービスやバージョンで変わるため、参照元を確認し、ログとリクエスト例を秘匿してから共有してください。
技術検証方法を見る