MCPに接続できたのにツールが出ない？tools/list・権限・実行エラーの切り分け

先に結論：接続済みでも、三つの確認結果は別

MCP serverの接続表示は、プロセスやtransportがつながったことを示す材料です。serverが何を返したか、hostが何を公開したか、tool callが成功したかまでは一度に証明しません。次の三段階を、同じserver・host・承認済みの認証条件で記録してください。

serverまたはhostの一覧・件数を同じ条件で確認できない場合は「未観測／不明」と記録します。接続表示や片方の画面から、もう片方の一覧や件数を推定しないでください。

症状から次の確認先を選ぶ

MCP 2026-07-28仕様では、serverがtools.listChanged capabilityを宣言し、clientがtoolsListChangedを有効にしたsubscriptions/listen streamを開いている場合に、tools list変更通知が送られます。hostやSDKが通知を受け取って一覧cacheを更新するか、どの操作で再取得するかは実装とrevisionを確認してください。

Python SDKで自作serverを実装している場合に限る診断例として、意図したapp/server instanceにtoolを登録しているか、同じtool名を重複登録していないかを確認します。これはPython SDKの実装確認であり、他のSDKやhost全般に共通する原因とは限りません。

HTTP 200だけではMCPのtool一覧を取得できたとは限りません。HTMLの案内ページ、health endpoint、認証用の応答、正しいendpointのJSON-RPC応答は別です。stdioでも、標準出力はprotocol messageの経路です。通常ログをstdoutへ混ぜず、仕様に沿ってstderrへ分けます。stderrに出力があること自体はserver errorの証拠ではありません。

Codexの許可・拒否リストは、serverの返答と分ける

CodexのMCP設定では、`enabled_tools`は利用可能toolのallow list、`disabled_tools`はdeny listで、deny listがallow listの後に適用されます。そのためserverのtools/listに名前があっても、Codexが公開する一覧に残るとは限りません。これはCodex host固有の設定です。別のMCP clientで同じkey名や順序を仮定せず、plugin由来serverでは設定の所有場所も確認します。

• 対象host・server・profileで、設定が実際に読み込まれているかを確認する
• allow listに欲しいtoolがあるか、deny listに同じ名前が残っていないかを分けて見る
• 修正が必要でも、許可するのは目的に必要なread-only toolに限定し、全toolを一括許可しない
• serverの起動timeoutとtool実行timeoutを混同せず、実行段階に合う項目だけを確認する

protocol errorとtool execution errorを分ける

上表はMCP 2026-07-28仕様の分類で、unknown toolはJSON-RPC errorの例です。一方、参照したPython SDKのcall_toolはUnknown toolを例外ではなく結果として返し、Python側ではresult.is_errorを確認します。メッセージだけで判定せず、実際のJSON-RPC error、wire上のresult.isError、SDKやhostの属性を分けて観測し、このPythonの挙動を他のSDKやhostへ一般化しないでください。protocol errorも必ずしも一覧不一致ではありません。認証はidentity・scope・到達段階から確認し、権限全体を広げないでください。

仮定例：観測が違うと、直す場所も変わる

次の二つは診断の順番を示す仮定例で、実在するserverやログの報告ではありません。実際の件数やエラーを推定する材料には使わず、手元の同一条件で得た記録に置き換えてください。

再現条件を安全に残す記録カード

再調査では生のconfigや通信ログを貼らず、項目名・件数・分類だけを残します。認証値、header、内部endpoint、query、tool payload、個人を識別する情報は記録カードに含めません。

host / version:
server / SDK version:
protocol revision (as shown in safe logs):
transport: stdio / Streamable HTTP / other
auth role label (no account identifier):
last successful stage: connect / tools-list-all-pages / host-list / tool-call
server tool count (all pages; unknown if unavailable):
host exposed tool count (unknown if unavailable):
requested tool name:
sanitized error category:
changed setting names only:
approved read-only retest outcome:

解決と判断できる条件

同じ承認済みidentity・設定・host versionで、必要性を確認したread-only toolが最終host listに現れ、承認された小さなtest callから期待する結果を得られたことを確認します。接続成功、HTTP 200、tool名が一度表示されたことだけでは完了にしません。production writeを試したり、原因不明のまま再installしたり、securityやapprovalを広く無効にしたりする必要はありません。