目次
クイック診断
Checklist
詳細を確認する前に、次の基本事項を確認してください。
- MCP サーバー実行可能ファイルが存在し、実行可能である
- コマンド パスが正しい (不明な場合は絶対パスを使用する)
- ツールが有効になっている (
tools: ["*"]または特定のツール名) - サーバーが MCP プロトコルを正しく実装する (
initializeに応答) - ファイアウォール/ウイルス対策がプロセスをブロックしていない (Windows)
MCP デバッグ ログを有効にする
MCP サーバー構成に環境変数を追加します。
mcpServers: {
"my-server": {
type: "local",
command: "/path/to/server",
args: [],
env: {
MCP_DEBUG: "1",
DEBUG: "*",
NODE_DEBUG: "mcp", // For Node.js MCP servers
},
},
}
MCP サーバーを個別にテストする
最初に、必ず SDK の外部で MCP サーバーをテストします。
手動プロトコル テスト
stdin を使用して initialize 要求を送信します。
# Unix/macOS
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | /path/to/your/mcp-server
# Windows (PowerShell)
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | C:\path\to\your\mcp-server.exe
予想される応答:
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"your-server","version":"1.0"}}}
テスト ツールの一覧
初期化後、ツールの一覧を要求します。
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | /path/to/your/mcp-server
予想される応答:
{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"my_tool","description":"Does something","inputSchema":{...}}]}}
対話型テスト スクリプト
MCP サーバーを対話形式でデバッグするテスト スクリプトを作成します。
#!/bin/bash
# test-mcp.sh
SERVER="$1"
# Initialize
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
# Send initialized notification
echo '{"jsonrpc":"2.0","method":"notifications/initialized"}'
# List tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
# Keep stdin open
cat
使用法:
./test-mcp.sh | /path/to/mcp-server
一般的な問題
サーバーが起動しない
症状： ツールは表示されません。ログにエラーはありません。
原因と解決策:
| 原因 | ソリューション |
|---|---|
| コマンド パスが正しくありません | 絶対パスを使用します。 /usr/local/bin/server |
| 実行可能なアクセス許可がありません | |
chmod +x /path/to/server を実行します。 | |
| 不足している依存関係 | |
ldd (Linux) で確認するか、手動で実行する | |
| 作業ディレクトリの問題 | config で cwd を設定する |
手動で実行してデバッグする:
# Run exactly what the SDK would run
cd /expected/working/dir
/path/to/command arg1 arg2
サーバーは起動しますが、ツールは表示されません
症状： サーバー プロセスは実行されますが、使用できるツールはありません。
原因と解決策:
-
構成でツールが有効になっていない:
mcpServers: { "server": { // ... tools: ["*"], // Must be "*" or list of tool names }, } -
サーバーはツールを公開しません。
tools/list要求を手動でテストする- サーバーが
tools/listメソッドを実装しているか確認
-
初期化ハンドシェイクが失敗する:
- サーバーが
initializeに正しく応答する必要がある - サーバーが処理する必要がある
notifications/initialized
- サーバーが
一覧表示されているが呼び出されないツール
症状： ツールはデバッグ ログに表示されますが、モデルでは使用されません。
原因と解決策:
-
プロンプトにツールは必要ありません。
// Too vague await session.sendAndWait({ prompt: "What's the weather?" }); // Better - explicitly mentions capability await session.sendAndWait({ prompt: "Use the weather tool to get the current temperature in Seattle" }); -
ツールの説明が不明:
// Bad - model doesn't know when to use it { name: "do_thing", description: "Does a thing" } // Good - clear purpose { name: "get_weather", description: "Get current weather conditions for a city. Returns temperature, humidity, and conditions." } -
ツール スキーマの問題:
inputSchemaが有効な JSON スキーマであることを確認する- 必須フィールドは配列内
required必要があります
タイムアウトエラー
現象:MCP tool call timed out エラー。
ソリューション:
-
タイムアウトの増加:
mcpServers: { "slow-server": { // ... timeout: 300000, // 5 minutes }, } -
サーバーのパフォーマンスを最適化する:
- 進行状況ログを追加してボトルネックを特定する
- 非同期操作を検討する
- ブロッキングI/Oを確認する
-
実行時間の長いツールの場合は、サポートされている場合はストリーミング応答を検討してください。
JSON-RPC エラー
症状： 解析エラー、無効な要求エラー。
一般的な原因:
-
サーバーが stdout に誤って書き込む:
- stderr ではなく stdout への出力をデバッグする
- 余分な改行または空白
// Wrong - pollutes stdout console.log("Debug info"); // Correct - use stderr for debug console.error("Debug info"); -
エンコードの問題:
- UTF-8 エンコードを確認する
- BOM なし (バイトオーダー マーク)
-
メッセージ フレーミング:
- 各メッセージは完全な JSON オブジェクトである必要があります
- 改行区切り (1 行に 1 つのメッセージ)
プラットフォーム固有の問題
Windows
.NET コンソール アプリ/ツール
using GitHub.Copilot;
public static class McpDotnetConfigExample
{
public static void Main()
{
var servers = new Dictionary<string, McpServerConfig>
{
["my-dotnet-server"] = new McpStdioServerConfig
{
Command = @"C:\Tools\MyServer\MyServer.exe",
Args = new List<string>(),
WorkingDirectory = @"C:\Tools\MyServer",
Tools = new List<string> { "*" },
},
["my-dotnet-tool"] = new McpStdioServerConfig
{
Command = "dotnet",
Args = new List<string> { @"C:\Tools\MyTool\MyTool.dll" },
WorkingDirectory = @"C:\Tools\MyTool",
Tools = new List<string> { "*" },
}
};
}
}
// Correct configuration for .NET exe
["my-dotnet-server"] = new McpStdioServerConfig
{
Command = @"C:\Tools\MyServer\MyServer.exe", // Full path with .exe
Args = new List<string>(),
WorkingDirectory = @"C:\Tools\MyServer", // Set working directory
Tools = new List<string> { "*" },
}
// For dotnet tool (DLL)
["my-dotnet-tool"] = new McpStdioServerConfig
{
Command = "dotnet",
Args = new List<string> { @"C:\Tools\MyTool\MyTool.dll" },
WorkingDirectory = @"C:\Tools\MyTool",
Tools = new List<string> { "*" },
}
npx コマンド
using GitHub.Copilot;
public static class McpNpxConfigExample
{
public static void Main()
{
var servers = new Dictionary<string, McpServerConfig>
{
["filesystem"] = new McpStdioServerConfig
{
Command = "cmd",
Args = new List<string> { "/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\allowed\\path" },
Tools = new List<string> { "*" },
}
};
}
}
// Windows needs cmd /c for npx
["filesystem"] = new McpStdioServerConfig
{
Command = "cmd",
Args = new List<string> { "/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\allowed\\path" },
Tools = new List<string> { "*" },
}
パスに関する問題
- raw 文字列 (
@"C:\path") またはフォワード スラッシュ ("C:/path") を使用します - 可能な場合はパス内のスペースを避ける
- スペースが必要な場合は、適切な引用符を使用してください
ウイルス対策/ファイアウォール
Windows Defenderまたはその他の AV がブロックされる場合があります。
- 新しい実行可能ファイル
- stdin/stdout 経由で通信するプロセス
ソリューション： MCP サーバー実行可能ファイルの除外を追加します。
macOS
ゲートキーパーのブロック
# If the server is blocked
xattr -d com.apple.quarantine /path/to/mcp-server
Homebrewのパス
import { MCPStdioServerConfig } from "@github/copilot-sdk";
const mcpServers: Record<string, MCPStdioServerConfig> = {
"my-server": {
command: "/opt/homebrew/bin/node",
args: ["/path/to/server.js"],
tools: ["*"],
},
};
// GUI apps may not have /opt/homebrew in PATH
mcpServers: {
"my-server": {
command: "/opt/homebrew/bin/node", // Full path
args: ["/path/to/server.js"],
},
}
Linux
アクセス許可の問題
chmod +x /path/to/mcp-server
共有ライブラリがありません
# Check dependencies
ldd /path/to/mcp-server
# Install missing libraries
apt install libfoo # Debian/Ubuntu
yum install libfoo # RHEL/CentOS
高度なデバッグ
すべての MCP トラフィックをキャプチャする
すべての通信をログに記録するラッパー スクリプトを作成します。
#!/bin/bash
# mcp-debug-wrapper.sh
LOG="/tmp/mcp-debug-$(date +%s).log"
ACTUAL_SERVER="$1"
shift
echo "=== MCP Debug Session ===" >> "$LOG"
echo "Server: $ACTUAL_SERVER" >> "$LOG"
echo "Args: $@" >> "$LOG"
echo "=========================" >> "$LOG"
# Tee stdin/stdout to log file
tee -a "$LOG" | "$ACTUAL_SERVER" "$@" 2>> "$LOG" | tee -a "$LOG"
これを使用します。
mcpServers: {
"debug-server": {
command: "/path/to/mcp-debug-wrapper.sh",
args: ["/actual/server/path", "arg1", "arg2"],
},
}
MCP インスペクターを使用して検査する
公式の MCP インスペクター ツールを使用します。
npx @modelcontextprotocol/inspector /path/to/your/mcp-server
これにより、次の Web UI が提供されます。
- テスト要求を送信する
- 応答を表示する
- ツール スキーマを検査する
プロトコル バージョンの不一致
SDK で使用されているプロトコル バージョンがサーバーでサポートされているかどうかを確認します。
// In initialize response, check protocolVersion
{"result":{"protocolVersion":"2024-11-05",...}}
バージョンが一致しない場合は、MCP サーバー ライブラリを更新します。
デバッグ チェックリスト
問題を開いたり、ヘルプを求めたりする場合は、次の情報を収集します。
- SDK の言語とバージョン
- CLI バージョン (
copilot --version) - MCP サーバーの種類 (Node.js、Python、.NET、Go、Rust など)
- MCP サーバーの完全な構成 (シークレットの編集)
- 手動
initializeテストの結果 - 手動
tools/listテストの結果 - SDK からログをデバッグする
- いずれかのエラーメッセージ
こちらも参照ください
- Using MCP servers with the GitHub Copilot SDK - 構成とセットアップ
- デバッグ ガイド - SDK 全体のデバッグ
- MCP 仕様 - 公式プロトコル ドキュメント