対象読者
- Claude Code（CLIまたはVS Code拡張機能）で自作のMCPサーバーを使いたい人
-
~/.claude/settings.jsonにmcpServersを書いたのに接続できなくて困っている人 - MCPサーバーのスコープ（全プロジェクト共通 / プロジェクト単位）を使い分けたい人
- 本記事の検証内容は執筆時点（2026年4月）のものです。Claude Codeはアップデートが活発なため、最新バージョンでは挙動が異なる場合があります
- 本記事の執筆には生成AIを使用しています
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 で登録状態を先に確認するのが現在では最短の診断手順です。