MCPサーバー統合の問題：プロトコル、transport、権限、schemaを切り分ける

障害をすばやく分類する

Inspectorを起動する前に、症状を1つと最後に確認できた地点を記録します。

• processがまったく起動しない。
• processは動作するが、clientがJSON-RPCを受信しない。
• transportは応答するが、versionまたはcapabilitiesが一致しない。
• serverが401または403を返す。
• tools/listは動作するが、必要なtoolが見つからない。
• toolは表示されるが、tools/callがargumentsを拒否する。
• callは成功するが、結果を検証できない。

メモにはAPI Key、bearer token、cookie、prompt全文、private fileの内容を残さないでください。相関確認には、時刻、server名、method、JSON-RPCのid、error code、機密情報を除いたmessageだけで十分です。

1. Protocol eraを確定する

client、server、利用中のSDKが対応するversionを確認します。Connectedという表示はtransportとdiscoveryの一部を確認するだけで、2026-07-28で合意した証拠にはなりません。

現行implementationでは、次の3点を確認します。

1. SDKまたはrelease notesが2026-07-28対応を明示している。
2. traceにserver/discover、またはSDKが定めた別のdiscovery pathがある。
3. requestにversion、client情報、capabilitiesを含む正しい_metaがある。

別のSDKから_metaの形を手作業でコピーしないでください。正確なwire formatはcompatible clientまたはofficial SDKが生成すべきです。serverがinitializeを待っている一方でclientがself-containedな2026-07-28 requestを送る場合、原因はprotocol eraの不一致であり、tool schemaのerrorではありません。

Legacy initialize：2025-11-25以前だけで使用

次は最小のlegacy requestです。「念のため」という理由でmodern 2026-07-28 flowに追加しないでください。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "mcp-diagnostic-client",
      "version": "1.0.0"
    }
  }
}

responseが成功すると、legacy clientはnotifications/initializedを送信します。このexchangeが途中で切れる場合、まずversionとcapabilities一覧を比較してください。まだtools/listへ進む段階ではありません。

2. TransportとMCP semanticsを分けて確認する

MCPはmethodsとdataを定義し、transportは起動、framing、配信、request cancellationを担います。stdioからHTTPへ変更しても、誤ったinputSchemaは直りません。

stdio

stdioでは、clientがserverをchild processとして起動します。messageはstdinとstdoutを通り、改行で区切られたUTF-8 JSON-RPC documentとして送受信されます。

次を確認します。

1. commandが存在し、同じuserで実行される。
2. argumentsが個別の要素として渡され、shell aliasesに依存していない。
3. working directoryに必要なfilesがあるか、pathsがabsoluteである。
4. 必要なvariablesをchild processが実際に参照できる。
5. stdoutにbanner、debug lines、stack traceがなく、logsがstderrへ出る。

誤ってstdoutへ出したconsole.log()が1つあるだけで、clientがJSON-RPC responseを見る前にframingが壊れます。

Streamable HTTP

Streamable HTTPでは、clientが1つのMCP endpointへPOST messageを送ります。responseは通常のJSONまたはrequest-scoped SSEです。正確なURL、HTTP method、Content-Type、TLS、redirect、proxy、authentication方式を確認してください。

Transport testはloopbackまたはisolated test environmentで実施します。許可なくpublic production endpointをscanしないでください。POSTがlogin pageのHTML、別hostへの301/302、reverse proxyのresponseを返すなら、まだMCPには到達していません。

3. 同じ実行環境で起動を再現する

stdioでは、MCP clientと同じdirectory、同じuserでserver commandを直接実行します。IDEからの起動で代用しないでください。PATH、cwd、runtime、permissionsが異なる可能性があります。

次を確認します。

node --version
pwd
node ./dist/server.js

pwd自体はsecretを表示しませんが、pathにuser名やprivate project名が含まれる場合は公開しないでください。server commandはstdinのJSON-RPCを待つか、stderrに明確なerrorを出して終了する必要があります。messageなしの即時exitは、entrypointの誤り、dependency不足、またはlogを出さずに処理されたstartup errorを示すことが一般的です。

2026年8月23日時点のofficial Inspector CLI documentationはNode.js 22.19.0以上を要求しています。これより古い場合は停止し、診断を続ける前にruntimeを切り替えてください。

4. Permissionsとauthenticationを分ける

response codeから次の確認対象を決めます。

• 401 Unauthorized：credentialがない、期限切れ、または拒否されている。
• 403 Forbidden：identityは認識されたが、必要なpermissionまたはscopeがない。
• 404：権限不足ではなく、endpointまたはrouteの誤りであることが多い。
• timeout：server、proxy、toolが時間内に完了していない。auth errorの証拠ではない。

Smoke testのためにpermissionsを無効化しないでください。最小scopeのtest identityを別に作り、external effectがないread-only toolを選びます。clientでは人がcallを拒否できる状態を維持します。Tool annotationsはuntrusted dataであり、policyの代わりにはなりません。

Logsにはauth decision（allowed/denied）、scope名、correlation IDを残します。credential自体、Authorization header、cookieは削除またはmaskしてください。

5. CapabilityとinputSchemaを検証する

serverはtools/listを提供する前にtools capabilityをdeclareする必要があります。各toolにはunique nameと、inputSchema内のvalidなJSON Schema objectが必要です。tools/callのargumentsはそのschemaに一致しなければなりません。

最小のread-only tool declarationは次のとおりです。

{
  "name": "echo",
  "description": "受け取ったテキストを変更せずに返します",
  "inputSchema": {
    "type": "object",
    "properties": {
      "text": {
        "type": "string"
      }
    },
    "required": ["text"],
    "additionalProperties": false
  }
}

よくあるerrorは単純です。rootのtype: objectがない、required fieldがpropertiesにない、clientがstringではなくnumberを送る、argument名の大文字小文字が違う、serverが同名のtoolsを2つadvertiseしている、といったものです。

Versionとtransportが一致したら、次のJSON-RPC payloadでmethodを確認します。

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

続いてtoolを1つだけ呼び出します。

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "echo",
    "arguments": {
      "text": "MCP_OK_2026"
    }
  }
}

これらはmethod payloadの例であり、connection bootstrap全体ではありません。2026-07-28 flowではcompatible clientが必要なrequest metadataを_metaへ追加します。Legacy flowでは先にinitializeを実行します。許可なく、このJSONをproduction endpointへ手動送信しないでください。

6. MCP Inspector CLIで安全なtestを実行する

最初に、信頼できるlockfileからInspectorをpinned project dependencyとしてinstallします。次の--no-installは診断中に任意のcurrent versionをdownloadしません。

Local stdio serverのtoolsを一覧表示します。

npx --no-install @modelcontextprotocol/inspector --cli node ./dist/server.js --method tools/list

echoを1回呼び出します。

npx --no-install @modelcontextprotocol/inspector --cli node ./dist/server.js \
  --method tools/call \
  --tool-name echo \
  --tool-arg text=MCP_OK_2026

Loopback上のtest Streamable HTTP endpointの場合は次のとおりです。

npx --no-install @modelcontextprotocol/inspector --cli \
  http://127.0.0.1:3000/mcp \
  --transport http \
  --method tools/list

Tokenをshell history、URL、articleに入れないでください。Endpointがauthを必要とする場合は、local environmentでInspectorの正式な方法によりcredentialを設定します。それができなければtestを停止し、server ownerにtest identityを依頼してください。上のcommandsには意図的にreal Keyを含めていません。

症状 → 確認 → 最小修正

成功判定基準

次の5条件をすべて満たしたときだけ、integrationは最小の受け入れテストに合格します。

1. Logsまたはtelemetryに、期待するnegotiated protocol versionが記録されている。
2. Transportがframingを壊していない。stdioには余計なstdoutがなく、HTTPはMCP endpointから応答する。
3. tools/listがvalidなinputSchemaを持つ期待どおりのtoolを1つ返す。
4. tools/callが実際にtext=MCP_OK_2026で呼ばれ、MCP_OK_2026を変更せず返す。
5. Testでpermissionsを無効にせず、credentialsを公開せず、external side effectを起こしていない。

Model responseにMCP_OK_2026が見えるだけでは不十分です。対応するJSON-RPC idを持つ記録済みtool call、またはInspectorの記録とsanitized server logが必要です。

Stop conditions

次の場合は診断を停止し、次のレイヤーへ進まないでください。

• いずれかの側が対応するprotocol eraが不明である。
• Inspectorが未確認のunpinned package versionをinstallしようとする。
• testにproduction credential、authの無効化、scopeの拡大が必要である。
• 利用可能な唯一のtoolがdatabaseへ書き込み、message送信、file変更、command実行のいずれかを行う。
• HTTP endpointがthird party所有で、testの許可を確認できない。
• logsにKey、token、cookie、personal data、private resourceの内容が出た。
• tools/listが不安定、または繰り返し実行で異なるschemaを返す。
• validなJSON-RPC responseが出る前にserverがcrashする。

この場合は、sanitized symptom、client/server/SDK versions、transport、correlation ID、最小限のerror断片を保存します。不要な権限やsecretを配布せずに、正しいレイヤーのownerへ問題を引き渡すには十分です。

参照資料

• MCP 2026-07-28: versioning
• MCP 2026-07-28: transports
• MCP 2026-07-28: tools
• MCP Inspector

Specification version、transport、最小Node.js versionは2026年8月23日に確認しました。Client、server、SDK、Inspectorのupdate後に診断を繰り返す場合は、最新のofficial documentationをもう一度確認してください。