設定をあれこれ変える前に、この順で潰します。ほとんどはここで終わります。
| 順 | やること | 分かること |
|---|---|---|
| 1 | node server.mjs を手で実行する | そもそも起動するか。エラーが出れば内容が見える |
| 2 | JSON を流し込んで応答を見る | プロトコルとして成立しているか |
| 3 | 観測用サーバーに差し替える | ホストからどこまで届いているか |
| 4 | claude mcp list を見る | 登録できているか、承認されているか |
node docs/samples/06-memo/server.mjs何も表示されずに固まれば正常です。入力を待っています。Ctrl+C で抜けてください。エラーが出るなら、それがそのまま原因です。
@(
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"手","version":"1.0"}}}'
'{"jsonrpc":"2.0","method":"notifications/initialized"}'
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
) -join "`n" | node docs/samples/06-memo/server.mjstools/list の応答にツールが並べば、サーバー側は正常です。ここまで通れば、残りはホスト側の話になります。
samples/02-minimal/probe.mjs を登録すると、ホストが送ってきたものが全部ファイルに残ります。詳しくは 04 章。
| 症状 | 原因 | 直し方 |
|---|---|---|
| プロセスが起動しない | パスの基準がずれている | いったん絶対パスにして確かめる。通ったら相対に戻す |
| 起動直後に落ちる | npm install がされていない |
手で node server.mjs を実行してエラーを見る |
| Cannot find module | node_modules の位置が違う |
サーバーの置き場から上に辿れる所に node_modules があるか確かめる |
| 繋がるがツールが出ない | console.log が混ざっている |
console.error に直す。02 章 |
| Pending approval と出る | プロジェクトの .mcp.json が未承認 |
ホストを起動し直して承認する |
| 設定を変えても効かない | 設定を読むのは起動時だけ | ホストを起動し直す |
| HTTP に繋がらない | 常駐を起こし忘れている | ブラウザで http://localhost:3333/mcp を開いて反応を見る |
最も多いのは console.log です。自分で書いていなくても、読み込んだライブラリが出していることがあります。手で起動して、stdout に JSON 以外が出ていないか目で確かめてください。
| 症状 | 原因 | 直し方 |
|---|---|---|
| ツールは見えるが呼ばれない | description が足りない |
「いつ使うか」を書く。名前だけでは判断されない |
| 別のツールが呼ばれる | 説明が似ている | 違いを明記する。「〜のときは使わない」と書いてもよい |
| 引数が思ったものと違う | describe が無い |
各引数に説明を付ける。範囲や既定値も効く |
| 呼ばれるが断られる | ホスト側の承認の設定 | サーバーの問題ではない。ホストの設定を見る（04 章） |
| Resource が読まれない | ホストが自動で読まない作りになっている | モデルに必ず見せたいなら Tools にする（05 章） |
| テンプレートが一覧に出ない | resources/list には出ない仕様 |
resources/templates/list を見る |
| 前 | 後 |
|---|---|
| メモ検索 | 記録してあるメモから、語を含むものを探す。過去の経緯を確かめたいときに使う |
| 実行 | 決めておいたコマンド（test / version）を名前で指定して実行する |
| query | 探す語。本文と札の両方から探す |
| 症状 | 原因 | 直し方 |
|---|---|---|
| 応答の順番が入れ替わる | 並行して処理されている | 異常ではない。id で対応が取れていれば問題ない |
| プロセスが終わらない | タイマーが残っている | transport.onclose で後片付けする（09 章） |
| タスクにしたのに普通に呼ばれる | ホストが対応していない | 正しい動き。optional なら両対応になる（09 章） |
| Server does not support task creation | capabilities.tasks の書き忘れ |
McpServer の 2 つめの引数に書く（09 章） |
| 進捗が届かない | progressToken が来ていない |
ホスト次第。無いときは送らない作りにする（08 章） |
| elicitation が cancel になる | 画面に出せる相手がいない | 対話していない実行では正常。断られる前提で書く |
| 日本語が化ける | 出力の文字コード | BOM を付けない UTF-8 で書き出す（A3） |
| 会話が出力で埋まる | 結果を全部返している | 件数と末尾だけ返す（11 章） |
node --test tests/ は複数のファイルを同時に走らせます。待ち受けポートを使うテストがあると取り合いになります。直列にすると通ります。
node --test --test-concurrency=1 tests/対象を渡し忘れないでください。node --test に場所を渡さないと、カレントディレクトリの配下を再帰的に探して、テストでないファイルまで実行します。スクリプトから呼ぶときは絶対パスを渡し、空でないことを確かめてから実行してください。
| メッセージ | 意味と対処 |
|---|---|
Method not found（-32601） |
そのメソッドを実装していない。対応していない機能を呼ばれただけのこともある |
Invalid params（-32602） |
引数が合っていない。存在しないツール名やタスク ID のときも出る |
Internal error（-32603） |
サーバーの中で例外が出た。stderr にスタックが出ていないか見る |
Server does not support task creation |
capabilities.tasks を名乗っていない（09 章） |
MCP tool call requires approval, but approval policy is never |
Codex の承認の設定。サーバーは正常 |
Unable to find type [Windows.UI.Notifications...] |
pwsh 7 では WinRT の型が使えない。powershell（5.1）で呼ぶ（08 章） |
406 Not Acceptable |
HTTP の Accept に text/event-stream が無い（07 章） |
fetch failed |
常駐が起きていない。ポート番号も確かめる |
Cannot find module |
パスの区切りか node_modules の位置。/ で書くと Windows でも通る |
| 見るもの | 置き場 |
|---|---|
| 仕様 | modelcontextprotocol.io の 2025-11-25。日付を確かめて読む |
| SDK の型定義 | node_modules/@modelcontextprotocol/sdk/dist/esm/**/*.d.ts |
| SDK の実例 | node_modules/@modelcontextprotocol/sdk/dist/esm/examples/ |
| 実際に流れているもの | 観測用サーバーのログ（04 章） |
仕様のページは日付で分かれています。検索で出てきたページが 2026-07-28 だと、手元のホストが喋る 2025-11-25 とは別物です。URL の日付を必ず見てください。