MCP公式ドキュメント 日本語版
  1. チュートリアル
MCP公式ドキュメント 日本語版
  • 始める
    • 導入
    • サンプルサーバー
    • クライアントの例
    • クイックスタート
      • サーバー開発者向け
      • クライアント開発者向け
      • Claude デスクトップ ユーザー向け
  • チュートリアル
    • LLMs を使用した MCP の構築
    • デバッグ
    • Inspector
  • コンセプト
    • リソース
    • コアアーキテクチャ
    • プロンプト
    • ツール
    • サンプリング
    • ルーツ
    • トランスポート
  • 発達
    • 最新情報
    • ロードマップ
    • 貢献
  1. チュートリアル

デバッグ

モデルコンテキストプロトコル（MCP）統合のデバッグに関する包括的なガイド
MCP サーバーを開発する場合や、アプリケーションと統合する場合は、効果的なデバッグが不可欠です。このガイドでは、MCP エコシステムで利用できるデバッグ ツールとアプローチについて説明します。
このガイドは macOS 向けです。他のプラットフォーム向けのガイドも近日公開予定です。

デバッグツールの概要#

MCP は、さまざまなレベルでデバッグするためのツールをいくつか提供します。
1.
**MCP Inspector **
インタラクティブなデバッグインターフェース
直接サーバーテスト
詳細についてはインスペクターガイドを参照してください
2.
Claude Desktop 開発者ツール
統合テスト
ログ収集
Chrome DevTools 統合
3.
サーバーログ
カスタムログ実装
エラー追跡
パフォーマンス監視

Claude Desktop でのデバッグ#

サーバーの状態を確認しています#

Claude.app インターフェースは、基本的なサーバー ステータス情報を提供します。
1.
img アイコンをクリックすると表示されます:
接続されたサーバー
利用可能なプロンプトとリソース
2.
img アイコンをクリックすると表示されます:
モデルに利用できるツール

ログの表示#

Claude Desktop からの詳細な MCP ログを確認します。
ログには次の内容が記録されます。
サーバー接続イベント
設定の問題
ランタイムエラー
メッセージ交換

Chrome DevToolsの使用#

クライアント側のエラーを調査するには、Claude Desktop 内の Chrome 開発者ツールにアクセスします。
1.
allowDevToolsを true に設定してdeveloper_settings.jsonファイルを作成します。
1.
DevToolsを開く: Command-Option-Shift-i
注: 2 つの DevTools ウィンドウが表示されます。
メインコンテンツウィンドウ
アプリのタイトルバーウィンドウ
コンソール パネルを使用して、クライアント側のエラーを検査します。
ネットワーク パネルを使用して次の項目を検査します。
メッセージペイロード
接続タイミング

よくある問題#

作業ディレクトリ#

Claude Desktop で MCP サーバーを使用する場合:
claude_desktop_config.json経由で起動されたサーバーの作業ディレクトリは、Claude Desktop がどこからでも起動できるため、未定義になる場合があります (macOS の/など)。
信頼性の高い操作を保証するために、構成ファイルと.envファイルでは常に絶対パスを使用してください。
コマンドライン経由で直接サーバーをテストする場合、作業ディレクトリはコマンドを実行する場所になります。
たとえば、 claude_desktop_config.jsonでは、次のように使用します。
{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/data"]
}
./dataのような相対パスの代わりに

環境変数#

MCP サーバーは、 USER 、 HOME 、 PATHなどの環境変数のサブセットのみを自動的に継承します。
デフォルトの変数を上書きしたり、独自の変数を指定するには、 claude_desktop_config.jsonでenvキーを指定します。
{
  "myserver": {
    "command": "mcp-server-myapp",
    "env": {
      "MYAPP_API_KEY": "some_key",
    }
  }
}

サーバーの初期化#

一般的な初期化の問題:
1.
Path Issues パスの問題
サーバーの実行可能パスが正しくありません
必要なファイルが見つかりません
権限の問題
commandに絶対パスを使用してみてください
2.
構成エラー
無効なJSON構文
必須フィールドがありません
型の不一致
3.
** 環境問題**
環境変数が見つかりません
変数値が正しくありません
権限制限

接続の問題#

サーバーが接続に失敗した場合:
1.
Claude Desktopのログを確認する
2.
サーバープロセスが実行中であることを確認する
3.
Inspectorを使用したスタンドアロンのテスト
4.
プロトコルの互換性を確認する

ログ記録の実装#

サーバー側のログ記録#

ローカル stdioトランスポートを使用するサーバーを構築すると、stderr (標準エラー) に記録されるすべてのメッセージは、ホスト アプリケーション (Claude Desktop など) によって自動的にキャプチャされます。
ローカル MCP サーバーは、プロトコルの動作を妨げるため、stdout (標準出力) にメッセージを記録しないでください。
すべてのトランスポートでは、ログ メッセージ通知を送信することでクライアントにログ記録を提供することもできます。
Python
TypeScript
記録する重要なイベント:
期化手順
リソースアクセス
ツールの実行
エラー条件
パフォーマンス指標

クライアント側のログ記録#

クライアント アプリケーションの場合:
1.
デバッグログを有効にする
2.
ネットワークトラフィックを監視する
3.
メッセージ交換を追跡する
4.
エラー状態を記録する

デバッグワークフロー#

開発サイクル#

1.
初期開発
基本的なテストにはInspectorを使用する
コア機能を実装する
ログポイントを追加する
2.
統合テスト
Claude Desktopでテスト
ログを監視する
エラー処理を確認する

変更のテスト#

変更を効率的にテストするには:
設定の変更: Claude Desktopを再起動
サーバーコードの変更: Command-R で再読み込みします
クイックイテレーション: 開発中にインスペクタを使用する

ベストプラクティス#

ログ戦略#

1.
構造化ログ
一貫したフォーマットを使用する
コンテキストを含める
タイムスタンプを追加する
リクエストIDを追跡する
2.
エラー処理
スタックトレースをログに記録する
エラーコンテキストを含める
エラーパターンを追跡する
回復を監視する
3.
パフォーマンス追跡
ログ操作のタイミング
リソースの使用状況を監視する
メッセージのサイズを追跡する
レイテンシを測定する

セキュリティに関する考慮事項#

デバッグ時:
1.
機密データ
ログをサニタイズする
資格情報を保護する
個人情報を隠す
2.
アクセス制御
権限を確認する
認証を確認する
アクセスパターンを監視する

ヘルプの取得#

問題が発生した場合:
1.
最初のステップ
サーバーログを確認する
インスペクターでテストする
構成を確認する
環境を確認する
2.
サポートチャネル
GitHub の問題
GitHub ディスカッション
3.
情報提供
ログ抜粋
設定ファイル
再現手順
環境の詳細
更新日時 2025-03-11 10:04:50
前へ
LLMs を使用した MCP の構築
次へ
Inspector
Built with