← ./articles-ja

Claude CodeでMCPサーバーが出ない時に見る設定・再起動・ツール名

claude-codemcpconfigurationdebuggingstdio

Claude CodeでMCPサーバーが出ないと、すぐにサーバー実装を疑いたくなります。

しかし実際には、設定ファイルの場所、再起動忘れ、相対パス、ツール名の見方が原因のことがあります。

この記事では、ローカルstdio MCPサーバーが見えない時の確認順をまとめます。

1. 設定のscopeを確認する

MCPサーバーはCLIで登録することも、JSON設定で登録することもあります。

claude mcp add my-server -- node /absolute/path/to/server.js

または次のような設定です。

{
  "mcpServers": {
    "knowledge": {
      "command": "node",
      "args": ["C:/path/to/mcp-server/dist/index.js"]
    }
  }
}

ここで大事なのは、Claude Codeが実際に読んでいる設定場所を確認することです。Claude Desktop、Claude Code、project-local、user-levelの設定が常に同じとは限りません。

設定を書いたのに何も変わらない場合、まず「読まれる場所に書いたか」を疑います。

2. 絶対パスを使う

stdioサーバーの command や args には、できるだけ絶対パスを使います。

{
  "mcpServers": {
    "knowledge": {
      "command": "node",
      "args": ["C:/path/to/mcp-server/dist/index.js"],
      "env": {
        "CONTENT_DIR": "C:/path/to/content"
      }
    }
  }
}

相対パスは、起動時のworking directoryによって解決先が変わります。手元のshellでは動いても、Claude Codeから起動すると見つからないことがあります。

3. 設定変更後は再起動する

MCP設定は常にhot reloadされるとは限りません。

サーバーを追加した、commandを変えた、argsを変えた、envを変えた。このような場合は、Claude Code側を再起動してから確認します。

stdio MCPでは、クライアントがサーバープロセスを起動します。古いプロセスのままなら、新しい設定は反映されません。

4. サーバー名ではなくツール名を見る

MCPツールは、次のような名前で見えることがあります。

mcp__knowledge__list_articles
mcp__knowledge__get_article

サーバー名が knowledge なら、呼び出し可能なツール名にそのnamespaceが入ります。サーバー表示名だけでなく、mcp__ から始まるツール名も確認します。

5. Claude Codeの外で起動する

実装の問題か設定の問題かを分けるため、サーバーを単体で起動します。

node /absolute/path/to/mcp-server/dist/index.js

stdioサーバーはJSON-RPC入力を待つため、何も起きないように見えることがあります。これは正常です。起動ログはstdoutではなくstderrに出します。

より確実には、MCP SDK clientやInspectorから listTools を呼びます。

6. stdoutにログを出さない

stdio transportではstdoutがプロトコル通信路です。診断ログに console.log() を使うのは避け、stderrへ出します。

process.stderr.write("MCP server running\n");

詳しくは MCP stdioサーバーのログはstderrへ: stdoutを汚さない設計 で解説しています。

まとめ

Claude CodeでMCPサーバーが出ない時は、実装を直す前に次を確認します。

  • 設定場所が正しいか
  • 絶対パスを使っているか
  • 設定変更後に再起動したか
  • mcp__ 付きのツール名を見ているか
  • サーバー単体で起動できるか
  • ログをstderrへ出しているか

これで設定問題と実装問題を切り分けやすくなります。

参考