Copilot SDK에서 MCP 서버 디버깅

참고

          코필로트 SDK가 현재 공개 미리 보기에 있습니다. 기능 및 가용성은 변경될 수 있습니다.

빠른 진단

Checklist

자세히 살펴보기 전에 다음 기본 사항을 확인합니다.

MCP 서버 실행 파일이 존재하며 실행 가능
명령 경로가 올바르다(의심할 경우 절대 경로 사용)
도구가 사용하도록 설정됨(tools: ["*"] 또는 특정 도구 이름)
서버가 MCP 프로토콜을 올바르게 구현하여 initialize에 응답함
방화벽 또는 바이러스 백신이 프로세스를 차단하지 않음(Windows)

MCP 디버그 로깅 사용

MCP 서버 구성에 환경 변수를 추가합니다.

TypeScript

mcpServers: {
  "my-server": {
    type: "local",
    command: "/path/to/server",
    args: [],
    env: {
      MCP_DEBUG: "1",
      DEBUG: "*",
      NODE_DEBUG: "mcp",  // For Node.js MCP servers
    },
  },
}

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 요청을 보냅니다.

Bash

# 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

# 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

          **예상 응답:**

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"your-server","version":"1.0"}}}

Windows PowerShell 예제는 리포지토리의 MCP 서버 디버깅 가이드 를 github/copilot-sdk 참조하세요.

테스트 도구 목록

초기화 후 도구 목록을 요청합니다.

Bash

echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | /path/to/your/mcp-server

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 서버를 대화형으로 디버그하는 테스트 스크립트를 만듭니다.

Bash

#!/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

#!/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

사용법:

Bash

./test-mcp.sh | /path/to/mcp-server

./test-mcp.sh | /path/to/mcp-server

일반적인 문제

서버가 시작되지 않음

          **증상:** 도구가 표시되지 않고 로그에 오류가 없습니다.

원인	해결 방법
잘못된 명령 경로	절대 경로 사용: `/usr/local/bin/server`
실행 권한이 없습니다.

          `chmod +x /path/to/server`을 실행합니다. |

수동으로 실행하여 디버그:

Bash

# Run exactly what the SDK would run
cd /expected/working/dir
/path/to/command arg1 arg2

# Run exactly what the SDK would run
cd /expected/working/dir
/path/to/command arg1 arg2

서버가 시작되지만 도구가 표시되지 않음

          **증상:** 서버 프로세스가 실행되지만 사용할 수 있는 도구는 없습니다.

1. 구성에서 사용하도록 설정되지 않은 도구:

TypeScript

mcpServers: {
  "server": {
    // ...
    tools: ["*"],  // Must be "*" or list of tool names
  },
}

mcpServers: {
  "server": {
    // ...
    tools: ["*"],  // Must be "*" or list of tool names
  },
}

       **서버는 도구를 노출하지 않습니다** . `tools/list` 요청을 사용하여 수동으로 테스트합니다. 서버에서 메서드를 구현하고 있는지 확인합니다 `tools/list` .

       **초기화 핸드셰이크가 실패합니다.** 서버가 올바르게 응답하고 `initialize` 처리 `notifications/initialized`해야 합니다.

도구가 나열되었지만 호출되지 않았습니다.

          **증상:** 도구는 디버그 로그에 표시되지만 모델은 이를 사용하지 않습니다.

1. 프롬프트에는 도구가 명확하게 필요하지 않습니다.

TypeScript

// 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"
});

// 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"
});

       **도구 설명 불분명:**

TypeScript

// 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." }

// 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." }

       **도구 스키마 문제:** 유효한 JSON 스키마인지 확인 `inputSchema` 합니다. 필수 필드는 배열에 `required` 나열되어야 합니다.

시간 제한 오류

          **증상:**`MCP tool call timed out` 오류.

시간 제한을 늘입니다.

TypeScript

mcpServers: {
  "slow-server": {
    // ...
    timeout: 300000,  // 5 minutes
  },
}

mcpServers: {
  "slow-server": {
    // ...
    timeout: 300000,  // 5 minutes
  },
}

진행률 로깅을 추가하여 병목 상태를 식별하고, 비동기 작업을 고려하고, I/O 차단을 확인하여 서버 성능을 최적화합니다.
장기 실행 도구의 경우 지원되는 경우 스트리밍 응답을 고려합니다.

JSON-RPC 오류

          **증상:** 구문 오류, 잘못된 요청 오류

일반적인 원인:

       **서버가 stdout에 잘못된 방식으로 씁니다.** 디버그 출력이 stderr 대신 stdout으로 이동하거나 빈 줄 또는 공백이 추가되는 것:

TypeScript

// Wrong—pollutes stdout
console.log("Debug info");

// Correct—use stderr for debug
console.error("Debug info");

// Wrong—pollutes stdout
console.log("Debug info");

// Correct—use stderr for debug
console.error("Debug info");

       **인코딩 문제:** BOM(바이트 순서 표시)이 없는 UTF-8 인코딩을 확인합니다.

       **메시지 프레이밍:** 각 메시지는 줄 바꿈으로 구분된 완전한 JSON 개체여야 합니다(줄당 하나의 메시지).

플랫폼별 문제

윈도우즈

Windows에서 바이러스 백신 또는 방화벽 소프트웨어는 stdin/stdout을 통해 통신하는 새 실행 파일 또는 프로세스를 차단할 수 있습니다. 필요한 경우 MCP 서버 실행 파일에 대한 제외를 추가합니다.

.NET 콘솔 앱 및 NPX 명령에 대한 Windows 관련 구성 예제는 리포지토리의 MCP 서버 디버깅 가이드를github/copilot-sdk 참조하세요.

          **경로 문제:**

원시 문자열(@"C:\path") 또는 슬래시("C:/path")를 사용합니다.
가능하면 경로의 공백을 방지합니다.
공백이 필요한 경우 올바른 따옴표를 사용하십시오.

macOS

       **게이트키퍼 차단:** 서버가 차단된 경우:

Bash

xattr -d com.apple.quarantine /path/to/mcp-server

xattr -d com.apple.quarantine /path/to/mcp-server

       **Homebrew 경로:** GUI 앱은 PATH에 없을 `/opt/homebrew` 수 있습니다. 전체 경로를 사용합니다.

TypeScript

mcpServers: {
  "my-server": {
    command: "/opt/homebrew/bin/node",  // Full path
    args: ["/path/to/server.js"],
  },
}

mcpServers: {
  "my-server": {
    command: "/opt/homebrew/bin/node",  // Full path
    args: ["/path/to/server.js"],
  },
}

리눅스

       **권한 문제:**

Bash

chmod +x /path/to/mcp-server

chmod +x /path/to/mcp-server

       **누락된 공유 라이브러리:**

Bash

# Check dependencies
ldd /path/to/mcp-server

# Install missing libraries
apt install libfoo  # Debian/Ubuntu
yum install libfoo  # RHEL/CentOS

# Check dependencies
ldd /path/to/mcp-server

# Install missing libraries
apt install libfoo  # Debian/Ubuntu
yum install libfoo  # RHEL/CentOS

고급 디버깅

모든 MCP 트래픽 캡처

모든 통신을 기록하는 래퍼 스크립트를 만듭니다.

Bash

#!/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"

#!/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"

사용하세요.

TypeScript

mcpServers: {
  "debug-server": {
    command: "/path/to/mcp-debug-wrapper.sh",
    args: ["/actual/server/path", "arg1", "arg2"],
  },
}

mcpServers: {
  "debug-server": {
    command: "/path/to/mcp-debug-wrapper.sh",
    args: ["/actual/server/path", "arg1", "arg2"],
  },
}

MCP 검사기로 검사

공식 MCP 검사기 도구를 사용합니다.

Bash

npx @modelcontextprotocol/inspector /path/to/your/mcp-server

npx @modelcontextprotocol/inspector /path/to/your/mcp-server

이렇게 하면 테스트 요청을 보내고, 응답을 보고, 도구 스키마를 검사하는 웹 UI가 제공됩니다.

프로토콜 버전 불일치

서버에서 SDK에서 사용하는 프로토콜 버전을 지원하는지 확인합니다.

// In initialize response, check protocolVersion
{"result":{"protocolVersion":"2024-11-05",...}}

버전이 일치하지 않는 경우 MCP 서버 라이브러리를 업데이트합니다.

디버깅 검사 목록

문제를 열거나 GitHub 문제에 대한 도움을 요청하는 경우 다음을 수집합니다.

SDK 언어 및 버전
CLI 버전(copilot --version)
MCP 서버 유형(Node.js, Python, .NET, Go 등)
전체 MCP 서버 구성(비밀 수정)
수동 initialize 테스트 결과
수동 tools/list 테스트 결과
SDK에서 로그 디버그
모든 오류 메시지

Copilot SDK에서 MCP 서버 디버깅

누가 이 기능을 사용할 수 있나요?

이 기사에서

빠른 진단

Checklist

MCP 디버그 로깅 사용

MCP 서버를 독립적으로 테스트

수동 프로토콜 테스트

테스트 도구 목록

대화형 테스트 스크립트

일반적인 문제

서버가 시작되지 않음

서버가 시작되지만 도구가 표시되지 않음

도구가 나열되었지만 호출되지 않았습니다.

시간 제한 오류

JSON-RPC 오류

플랫폼별 문제

윈도우즈

macOS

리눅스

고급 디버깅

모든 MCP 트래픽 캡처

MCP 검사기로 검사

프로토콜 버전 불일치

디버깅 검사 목록