自作 MCP サーバーが Claude Code で認識されない・動かない時のデバッグ手順 — MCP Inspector と stdout 汚染、3つのハマりどころ【2026】

2026年、AIエージェントを活用した開発副業やAIツール開発ビジネスが爆発的な盛り上がりを見せています。その中核を担うテクノロジーが、Anthropicが提唱する**MCP（Model Context Protocol）**です。

「特定の社内データベースをClaudeに検索させたい」「独自のAPIと連携した、自分だけのClaude専用ツールを作って高額でクライアントに提供したい」と考え、自作のMCPサーバーを開発する方が増えています。

しかし、いざ自作MCPサーバーを『Claude Code』や『Claude Desktop』に登録してみると、**「ツールとして認識されない」「Claudeが呼び出そうとした瞬間にエラーで沈黙する」**というトラブルに遭遇する初心者が後を絶ちません。

本記事では、自作MCPサーバー開発における最大の障壁を突破するための**「MCP Inspector」の使い方**、最も犯しやすい**「stdout（標準出力）汚染」の罠**、そして**3つの盲点（ハマりどころ）**について徹底的に解説します。これをマスターして、安定したAIエージェントビジネスへの一歩を踏み出しましょう！

---

MCP、Claude Code、そして「デバッグツール」の基礎知識

具体的なトラブルシューティングに入る前に、なぜこのような問題が起きるのか、その仕組みを正しく理解しておきましょう。

MCP（Model Context Protocol）とは？

MCPは、ClaudeなどのAIモデル（LLM）と、ローカルファイルや外部API、データベースなどの「外部ツール」を安全に接続するための標準規格です。開発者はMCPサーバーを立ち上げるだけで、Claudeに自由な超能力（ツール）を与えることができます。

なぜ動かない？最大の難敵「stdout（標準出力）汚染」

Claude CodeやClaude Desktopが自作MCPサーバーと通信する際、裏側では**「stdio（標準入出力）」を用いたJSON-RPC**という仕組みが使われています。親プロセスであるClaudeが標準入力（stdin）に命令を送り、子プロセスである自作MCPサーバーが標準出力（stdout）に結果を返します。

ここで初心者が最もやってしまいがちなミスが**「stdout（標準出力）汚染」**です。 例えば、プログラムの起動時に、 javascript console.log('MCP Server Started on port 3000!');

のような親切なログメッセージを出力したり、依存ライブラリが勝手にデバッグログを標準出力に吐き出したりしていると、その文字列がJSON-RPCの通信データと混ざってしまいます。結果として、Claude側は**「JSONとして解析できない不正なデータが届いた」**と認識し、エラーを出して即座に接続を切断してしまいます。これこそが「認識されない・動かない」の代表的な原因です。

最強のデバッグ相棒「MCP Inspector」

この問題を解決するために、Anthropicの公式開発チームから提供されているのが**「MCP Inspector（@modelcontextprotocol/inspector）」**です。これは、Claude本体を起動することなく、Webブラウザの直感的なUIから自作MCPサーバーの動作や通信ログを1ステップずつ追跡・テストできる強力なツールです。

---

自作MCPサーバーをデバッグして収益化するための4ステップ

では、具体的にトラブルを解決し、実用的なMCPサーバーを完成させて収益化に繋げるまでのステップを解説します。

ステップ1：MCP Inspectorによる「孤立稼働テスト」

まずはClaude Codeから一度切り離し、自作MCPサーバー単体で正常に会話（JSON-RPCの送受信）ができているかテストします。

ターミナルで以下のコマンドを実行してみましょう（Node.js環境を想定しています）。

bash npx @modelcontextprotocol/inspector node dist/index.js

※ node dist/index.js の部分には、ご自身のMCPサーバーの起動コマンドを入力します。

コマンドを実行するとローカルサーバーが立ち上がり、ブラウザでアクセス可能なURL（通常は http://localhost:3000 など）が表示されます。ブラウザを開くと専用のダッシュボードが表示され、以下の確認がノーコードで行えます。

• List Tools: サーバーが提供しているツールの定義が正しく読み込まれているか
• Call Tool: 実際にパラメータを入力してツールを実行し、期待通りのレスポンスが返るか

ここでエラーが出る場合は、Claude Code側の設定ではなく、純粋に自作サーバーのプログラム自体にバグがあります。

ステップ2：stdout汚染の完全排除（stderrへの退避）

もしMCP Inspectorすら起動しない、あるいは通信エラーになる場合、高確率でstdout汚染が発生しています。

自作サーバーのコード内で、デバッグ用に出力している console.log や print 文をすべてチェックしましょう。もしログを残したい場合は、必ず**標準エラー出力（stderr）**を使用するように書き換えます。

• Node.js (TypeScript/JavaScript) の場合: typescript // NG（標準出力に入り込み、JSON-RPCを破壊する） console.log("Fetching data from database...");

  // OK（標準エラー出力に出すため、Claudeの通信を邪魔しない） console.error("Fetching data from database...");

• Python の場合: python

  NG

  print("Server initialized.")

  OK

  import sys print("Server initialized.", file=sys.stderr)

これだけで、起動時エラーの8割以上は解消されます。

ステップ3：3つの「裏ハマりどころ」をチェックする

これでもまだClaude Codeがサーバーを認識しない場合、以下の「3つの盲点」に引っかかっていないか確認してください。

ハマりどころ①：環境変数（PATH）が引き継がれていない

Claude DesktopやClaude Codeは、独自のシェル環境で動くことがあります。そのため、ローカルのターミナルでは node や python コマンドが通るのに、Claudeからはパスが通っておらず起動に失敗しているケースが非常に多いです。 設定ファイル（例：claude_desktop_config.json）内に記載するコマンドパスや実行パスは、省略せずに絶対パスで記述するようにしましょう。

• NG設定例: "command": "node"
• OK設定例: "command": "/usr/local/bin/node"（Windowsの場合は C:\\Program Files\\nodejs\\node.exe のように指定）

ハマりどころ②：ESM（ES Modules）と CommonJS の競合

Node.js環境でMCPサーバーを作成する場合、TypeScriptのビルド設定や package.json の "type": "module" 設定の不整合により、バックグラウンドで「Require is not defined」などの例外エラーが発生し、音もなくプロセスが終了しているケースがあります。これもビルド後のJSファイルを直接 node path/to/index.js で実行してエラーが出ないか要確認です。

ハマりどころ③：パーミッションとカレントディレクトリの問題

MCPサーバーがローカルファイルやスクリプトを実行するタイプの場合、Claude Codeが実行される親プロセスと、自作MCPサーバーが動作するカレントディレクトリ（作業フォルダ）に乖離が生じ、相対パスで指定した設定ファイルが「File Not Found」で読み込めなくなっていることがあります。パスはすべて絶対パスに変換して解決するロジックをコード内に仕込んでおきましょう。

ステップ4：完成したMCPサーバーをマネタイズする

バグが完全に取れた信頼性の高いMCPサーバーは、現在高値で取引されるポテンシャルを秘めています。主なマネタイズ方法は以下の3つです。

1. 受託開発・個別カスタマイズ： 「自社の社内システム（Kintone、Notion、独自の基幹システムなど）とClaude Codeを繋いで開発スピードを10倍にしたい」という企業に対し、特注のMCPサーバーの構築を数万〜数十万円で請け負います。
2. SaaS形式でのAPI接続ツールの提供： 有料の外部API（最新のニッチな市場データ検索ツールなど）のプロキシとなるMCPサーバーを開発し、サブスクリプション型（月額制）のツールとしてAI開発者に提供します。
3. GitHubでのオープンソース公開 ＆ スポンサーシップ： 多くのユーザーが欲しがる「超便利ツール」を公開して認知度を高め、自身のポートフォリオとして活用。そこから技術顧問や高単価な開発案件を獲得します。

---

自作MCPサーバー開発のメリットとデメリット

AI副業として自作MCPサーバーに取り組むべきか判断するためのポイントを整理しました。

メリット

• 競合がまだ極めて少ない：2026年現在、MCPの仕組みを深く理解し、企業の個別ニーズに合わせて開発・デバッグまで完遂できるエンジニアは市場に圧倒的に不足しています。
• 開発の手間が少ない：UI（画面設計）を作る必要が一切ありません。AIモデルが解釈できるAPI（JSON）だけを作ればよいため、バックエンドのロジック開発のみに集中できます。
• クライアントの満足度が高い：使い慣れたClaudeの画面からそのまま業務システムを操作できるようになるため、驚くほど劇的な業務効率化を体験してもらえます。

デメリット

• プロトコルの仕様変更リスク：MCPは現在も急速にアップデートが続いている規格です。仕様変更のキャッチアップとメンテナンスが定期的に発生します。
• デバッグの難易度：UIがない分、不具合が起きた際に「どこでエラーが出ているか」が初心者には見えにくく、本記事で紹介したような正しいデバッグ手法（Inspector、stderrの活用）を知らないと途方に暮れることになります。

---

まとめ：デバッグ技術を武器にAIエージェント市場をリードしよう

自作のMCPサーバーが動かない原因のほとんどは、**「stdoutの汚染」か「パス・環境変数の不整合」**のどちらかに集約されます。

動かずに頭を抱えて時間を無駄にする前に、まずは 「MCP Inspector」 を立ち上げ、ログを stderr（標準エラー出力） に流す。この2つを徹底するだけで、開発効率は劇的に向上します。

この強力なデバッグスキルを身につければ、今後のAI時代において「AIに仕事を与える側のエンジニア」として、高単価な案件を次々に受注していくことが可能になります。ぜひご自身のMCPサーバーを完成させ、新しいAIビジネスの可能性を切り拓いてください！