MCP tool schemaが更新されない時はtools/listを直接確認する

2026-07-15

mcpjson-rpcai-agentdebuggingapi-testing

toolを追加した、引数名を変えた、inputSchemaを更新した。MCP serverは正常に再起動したのに、clientには古い定義が残る、または新しいtoolが存在しないと言われることがあります。

それだけではserver buildの失敗とは断定できません。MCP clientはtools/listでtoolを発見し、接続やconversationの間、その定義を保持する場合があります。何度も全体を再起動する前に、server responseを直接確認します。

接続障害とschema更新漏れを区別する

schema更新問題には、次の特徴があります。

同じserverの既存toolは呼べる
新しいtoolまたは変更した引数だけ見えない
server processにtransport errorがない
serverだけ再起動してもclient表示が変わらない

全toolが消えた場合は、先にClaude Code MCP Server Not Loading?の接続・設定確認を行います。

AI clientを通さずtools/listを呼ぶ

Streamable HTTP serverなら、MCP endpointへJSON-RPC requestを送ります。URLは自分のlocal test endpointへ置き換えてください。

curl -s -X POST http://127.0.0.1:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

serverによっては、tools/listより前にMCP initialization handshakeとsession headerが必要です。その場合はsession checkを外さず、MCP Inspectorまたは小さなSDK clientを使います。

response内では次を確認します。

name
description
inputSchema.properties
inputSchema.required
宣言している場合はoutputSchema

この直接responseがserver側の事実です。ここが古いなら、wrong executable、stale build、wrong endpoint、tool registration漏れを疑います。

変更したtoolをtools/callで直接呼ぶ

正しいlist responseは、登録成功しか証明しません。新しい引数形でtoolも呼びます。

curl -s -X POST http://127.0.0.1:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"read_status","arguments":{"detail":"summary"}}}'

可能なら副作用のないread-only toolで確認します。schemaが正しくても、handlerが旧fieldを読んだり、不正なresultを返したりすることがあります。

古いlayerを判定する

結果を次の規則で判断します。

tools/listが古い: PID、executable path、build時刻、endpoint、registration codeを確認する
tools/listは新しいがtools/callが失敗: handlerまたはresult validationを直す
直接callは両方成功し、AI clientだけ古い: clientを再接続または再起動する
serverがlistChangedを宣言: notifications/tools/list_changedの送信とclient対応を確認する

全clientがchange notificationへ同じように反応するとは限りません。最後は再接続でも確認します。

更新経路を最後まで検証する

両側の証拠を残します。

Direct tools/list: new argument present
Direct tools/call: result returned
Client reconnect: new argument visible
Client tool call: result returned

これで、client cacheを直すために正常なserver codeを変更する誤りと、serverが新schemaを返す前にclient再起動だけ繰り返す誤りを防げます。

参考

まとめ

MCP tool変更が見えない時は、まずtools/list、次にtools/callを直接実行します。直接responseが正しければclientを更新し、正しくなければ実行中server artifactとhandlerを調べます。