# デバッグ

モデルコンテキストプロトコル（MCP）統合のデバッグに関する包括的なガイド

MCP サーバーを開発する場合や、アプリケーションと統合する場合は、効果的なデバッグが不可欠です。このガイドでは、MCP エコシステムで利用できるデバッグ ツールとアプローチについて説明します。



このガイドは macOS 向けです。他のプラットフォーム向けのガイドも近日公開予定です。

## [デバッグツールの概要](https://modelcontextprotocol.io/docs/tools/debugging#debugging-tools-overview)

MCP は、さまざまなレベルでデバッグするためのツールをいくつか提供します。

1. **MCP Inspector **
   - インタラクティブなデバッグインターフェース
   - 直接サーバーテスト
   - 詳細については[インスペクターガイド](https://modelcontextprotocol.io/docs/tools/inspector)を参照してください
2. **Claude Desktop 開発者ツール**
   - 統合テスト
   -  ログ収集
   - Chrome DevTools 統合
3. **サーバーログ**
   - カスタムログ実装
   - エラー追跡
   - パフォーマンス監視

## [Claude Desktop でのデバッグ](https://modelcontextprotocol.io/docs/tools/debugging#debugging-in-claude-desktop)

### [サーバーの状態を確認しています](https://modelcontextprotocol.io/docs/tools/debugging#checking-server-status)

Claude.app インターフェースは、基本的なサーバー ステータス情報を提供します。

1. ![img](https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-plug-icon.svg) アイコンをクリックすると表示されます:
   - 接続されたサーバー
   - 利用可能なプロンプトとリソース
2. ![img](https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-hammer-icon.svg) アイコンをクリックすると表示されます:
   - モデルに利用できるツール

### [ログの表示](https://modelcontextprotocol.io/docs/tools/debugging#viewing-logs)

Claude Desktop からの詳細な MCP ログを確認します。

```bash
# Follow logs in real-time
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
```

ログには次の内容が記録されます。

- サーバー接続イベント
- 設定の問題
- ランタイムエラー
- メッセージ交換

### [Chrome DevToolsの使用](https://modelcontextprotocol.io/docs/tools/debugging#using-chrome-devtools)

クライアント側のエラーを調査するには、Claude Desktop 内の Chrome 開発者ツールにアクセスします。

1. `allowDevTools`を true に設定して`developer_settings.json`ファイルを作成します。

```bash
echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json
```

1. DevToolsを開く: `Command-Option-Shift-i`

注: 2 つの DevTools ウィンドウが表示されます。

- メインコンテンツウィンドウ
- アプリのタイトルバーウィンドウ

コンソール パネルを使用して、クライアント側のエラーを検査します。

ネットワーク パネルを使用して次の項目を検査します。

- メッセージペイロード
- 接続タイミング

## [よくある問題](https://modelcontextprotocol.io/docs/tools/debugging#common-issues)

### [作業ディレクトリ](https://modelcontextprotocol.io/docs/tools/debugging#working-directory)

Claude Desktop で MCP サーバーを使用する場合:

- `claude_desktop_config.json`経由で起動されたサーバーの作業ディレクトリは、Claude Desktop がどこからでも起動できるため、未定義になる場合があります (macOS の`/`など)。
- 信頼性の高い操作を保証するために、構成ファイルと`.env`ファイルでは常に絶対パスを使用してください。
- コマンドライン経由で直接サーバーをテストする場合、作業ディレクトリはコマンドを実行する場所になります。

たとえば、 `claude_desktop_config.json`では、次のように使用します。

```json
{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/data"]
}
```

`./data`のような相対パスの代わりに

### [環境変数](https://modelcontextprotocol.io/docs/tools/debugging#environment-variables)

MCP サーバーは、 `USER` 、 `HOME` 、 `PATH`などの環境変数のサブセットのみを自動的に継承します。

デフォルトの変数を上書きしたり、独自の変数を指定するには、 `claude_desktop_config.json`で`env`キーを指定します。

```json
{
  "myserver": {
    "command": "mcp-server-myapp",
    "env": {
      "MYAPP_API_KEY": "some_key",
    }
  }
}
```

### [サーバーの初期化](https://modelcontextprotocol.io/docs/tools/debugging#server-initialization)

一般的な初期化の問題:

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

### [接続の問題](https://modelcontextprotocol.io/docs/tools/debugging#connection-problems)

サーバーが接続に失敗した場合:

1. Claude Desktopのログを確認する
2. サーバープロセスが実行中であることを確認する
3. [Inspector](https://modelcontextprotocol.io/docs/tools/inspector)を使用したスタンドアロンのテスト
4. プロトコルの互換性を確認する

## [ログ記録の実装](https://modelcontextprotocol.io/docs/tools/debugging#implementing-logging)

### [サーバー側のログ記録](https://modelcontextprotocol.io/docs/tools/debugging#server-side-logging)

ローカル stdio[トランスポート](https://modelcontextprotocol.io/docs/concepts/transports)を使用するサーバーを構築すると、stderr (標準エラー) に記録されるすべてのメッセージは、ホスト アプリケーション (Claude Desktop など) によって自動的にキャプチャされます。



ローカル MCP サーバーは、プロトコルの動作を妨げるため、stdout (標準出力) にメッセージを記録しないでください。

すべての[トランスポート](https://modelcontextprotocol.io/docs/concepts/transports)では、ログ メッセージ通知を送信することでクライアントにログ記録を提供することもできます。

Python

```python
server.request_context.session.send_log_message(
  level="info",
  data="Server started successfully",
)
```

TypeScript

```typescript
server.sendLoggingMessage({
  level: "info",
  data: "Server started successfully",
});
```

記録する重要なイベント:

- 期化手順
- リソースアクセス
- ツールの実行
- エラー条件
- パフォーマンス指標

### [クライアント側のログ記録](https://modelcontextprotocol.io/docs/tools/debugging#client-side-logging)

クライアント アプリケーションの場合:

1. デバッグログを有効にする
2. ネットワークトラフィックを監視する
3. メッセージ交換を追跡する
4. エラー状態を記録する

## [デバッグワークフロー](https://modelcontextprotocol.io/docs/tools/debugging#debugging-workflow)

### [開発サイクル](https://modelcontextprotocol.io/docs/tools/debugging#development-cycle)

1. 初期開発
   - 基本的なテストには[Inspector](https://modelcontextprotocol.io/docs/tools/inspector)を使用する
   - コア機能を実装する
   - ログポイントを追加する
2. 統合テスト
   -  Claude Desktopでテスト
   - ログを監視する
   - エラー処理を確認する

### [変更のテスト](https://modelcontextprotocol.io/docs/tools/debugging#testing-changes)

変更を効率的にテストするには:

- **設定の変更**: Claude Desktopを再起動
- **サーバーコードの変更**: Command-R で再読み込みします
- **クイックイテレーション**: 開発中に[インスペクタ](https://modelcontextprotocol.io/docs/tools/inspector)を使用する

## [ベストプラクティス](https://modelcontextprotocol.io/docs/tools/debugging#best-practices) 

### [ログ戦略](https://modelcontextprotocol.io/docs/tools/debugging#logging-strategy)

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

### [セキュリティに関する考慮事項](https://modelcontextprotocol.io/docs/tools/debugging#security-considerations)

デバッグ時:

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

## [ヘルプの取得](https://modelcontextprotocol.io/docs/tools/debugging#getting-help) 

問題が発生した場合:

1. **最初のステップ**
   - サーバーログを確認する
   - [インスペクター](https://modelcontextprotocol.io/docs/tools/inspector)でテストする
   - 構成を確認する
   - 環境を確認する
2. **サポートチャネル**
   - GitHub の問題
   - GitHub ディスカッション
3. **情報提供**
   - ログ抜粋
   -  設定ファイル
   - 再現手順
   - 環境の詳細