TL;DR

~/.claude/settings.json の mcpServers キーは Claude Code 2.1.x では読み込まれない
MCPサーバーの正しい登録先は ~/.claude.json（claude mcp add コマンドが書き込む）
スコープは user（全プロジェクト）/ local（現プロジェクトのみ）/ project（リポジトリにcommit）の3種類
登録後は claude mcp list で接続確認できる

環境

項目	バージョン / パス
OS	Windows 11 Pro
Claude Code VS Code 拡張機能	2.1.119
MCP サーバー	自作 stdio サーバー（Bun + SQLite）
グローバル設定ファイル	`~/.claude/settings.json`
MCP 登録ファイル	`~/.claude.json`

ハマりポイント

1. `settings.json` の `mcpServers` が無視される

公式ドキュメントや記事を参考に、~/.claude/settings.json に以下を追記しました。

{
  "mcpServers": {
    "your-mcp": {
      "command": "E:\\project\\ts-memory-mcp\\dist\\your-mcp.exe",
      "env": {
        "DB_PATH": "E:\\mcp\\ts-memory-mcp\\memory.db"
      }
    }
  }
}

しかしClaude Codeの拡張機能ペインの上部に赤いエラーが表示され、memory_search などのツールは一切呼び出せませんでした。

VS Codeの拡張機能ログ（Claude: Open MCP Log）を確認すると、以下のような状況でした。

[MCP] --mcp-config servers running fully async (MCP_CONNECTION_NONBLOCKING)
[MCP] claude.ai connectors running fully async (MCP_CONNECTION_NONBLOCKING)
MCP server "claude.ai Google Drive": ✓ Connected
⇧ your-mcp に関するログが一切ない

claude mcp list でも確認しました。

claude.ai Google Drive: https://... - ✓ Connected
⇧ your-mcp が表示されない

結論: settings.json の mcpServers キーはClaude Code 2.1.xでは stdioサーバーの登録先として機能しません。

2. Windows のパス区切り文字も無関係だった

「バックスラッシュが原因では？」と疑い、普通のスラッシュ（/）に変更してみましたが結果は変わりませんでした。問題はパス区切り文字ではなく、設定ファイル自体の場所でした。

3. バイナリ自体は正常動作していた

MCPプロトコルの疎通確認コマンドで、バイナリ単体は問題なく動いていました。

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  | DB_PATH="C:/Users/YourName/AppData/Local/your-mcp/memory.db" \
    "./dist/your-mcp.exe"
# → {"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},...}}

「設定の読み込み」と「バイナリの動作」を切り分けて診断することが重要でした。

実例

正しい登録コマンド

claude mcp add コマンドで登録します。保存先は ~/.claude.json（settings.json ではありません）。

スコープ一覧

スコープ	保存先	適用範囲
`user`	`~/.claude.json`（グローバルセクション）	全プロジェクト共通
`local`（デフォルト）	`~/.claude.json`（プロジェクトキー付き）	現プロジェクトのみ
`project`	リポジトリ直下の `.mcp.json`	チームで git 共有

user スコープ（全プロジェクト共通・個人用に推奨）

claude mcp add your-mcp /absolute/path/to/dist/your-mcp \
  --scope user \
  -e DB_PATH=/absolute/path/to/memory.db

Windowsの場合：

claude mcp add your-mcp "E:/project/ts-memory-mcp/dist/your-mcp.exe" \
  --scope user \
  -e "DB_PATH=C:/Users/YourName/AppData/Local/your-mcp/memory.db"

local スコープ（現プロジェクトのみ・デフォルト）

claude mcp add your-mcp /absolute/path/to/dist/your-mcp \
  -e DB_PATH=/absolute/path/to/memory.db
# --scope local は省略可

project スコープ（チームで共有する場合）

claude mcp add your-mcp /absolute/path/to/dist/your-mcp \
  --scope project \
  -e DB_PATH=/absolute/path/to/memory.db

リポジトリ直下に .mcp.json が生成され、git push でチームに共有できます。

接続確認

claude mcp list
# → your-mcp: /absolute/path/to/dist/your-mcp - ✓ Connected

登録済みサーバーの削除

# local スコープ（カレントディレクトリのプロジェクトから）
claude mcp remove your-mcp

# user スコープ
claude mcp remove your-mcp --scope user

まとめ

やること	うまくいった方法	ハマりやすい方法
MCP サーバーの登録	`claude mcp add --scope user`	`settings.json` の `mcpServers` を手書き
接続確認	`claude mcp list`	拡張機能を再起動して試行錯誤
バイナリ動作確認	`echo '...' \| ./binary 2>&1` で疎通テスト	エラーを見ずに設定を変え続ける
エラー特定	VS Code で `Claude: Open MCP Log` を確認	ログを見ずに推測

Claude Codeはバージョンアップとともに設定の読み込み先が変わることがあります。問題が起きたときは claude mcp list で登録状態を先に確認するのが現在では最短の診断手順です。

参考