MCP 서버 테스트 방법: Inspector, Postman, curl

MCP 서버를 테스트하려면 서버 테스트와 디버깅을 위한 프로토콜의 레퍼런스 도구인 MCP Inspector로 연결하세요. npx @modelcontextprotocol/inspector를 실행하고, 서버를 지정하고(로컬 서버는 실행 명령어, 원격 서버는 http 트랜스포트와 URL), 로그인하거나 인증 헤더를 넣은 뒤, 도구 목록을 불러와 읽기만 하는 도구 하나를 호출합니다. 도구 목록이 돌아오고 읽기 전용 호출이 성공하면 트랜스포트, 로그인, 서버가 모두 정상입니다.

Inspector 단계는 Inspector 문서(개요, CLI, 설정, 프로토콜 시대, 인가)에서, Postman 단계는 Postman의 MCP 요청 가이드에서, 와이어 포맷은 MCP 명세에서 가져왔으며, 모두 2026-09-28에 확인했습니다. 예시로 든 Sume 호스팅 MCP 서버 내용은 MCP 빠른 시작, MCP 도구와 게이트, 현재 서버 코드에서 가져왔습니다.

MCP Inspector로 서버를 어떻게 테스트하나요?

Inspector는 Node 22.19.0 이상이 필요하며, 설치 없이 npx로 실행됩니다. 패키지 하나로 클라이언트 세 가지를 쓸 수 있습니다. 웹 UI(기본값이며, 브라우저에서 열 URL을 출력), 스크립트로 쓸 수 있는 CLI, 터미널 UI입니다.

• 로컬 서버: npx @modelcontextprotocol/inspector node path/to/server/index.js처럼 서버 실행 명령어를 넘깁니다.
• 원격 서버: 엔드포인트를 담은 --server-url과 --transport http를 넘깁니다. 다른 트랜스포트 선택지는 stdio와 sse입니다.
• 인증: --header "Name: Value"를 추가하거나(여러 번 쓸 수 있음), Inspector가 OAuth를 실행하게 합니다. 서버가 401로 응답하면 Inspector는 protected-resource 메타데이터를 읽고, 브라우저에서 로그인 페이지를 열고, 코드를 토큰으로 교환한 뒤 다시 시도합니다.
• 호출: 도구를 고르고, 입력 스키마로 만든 폼을 채운 뒤 결과를 읽습니다. Protocol 탭에는 가공하지 않은 JSON-RPC 요청과 응답이 표시됩니다.

명령줄에서 MCP 서버를 테스트할 수 있나요?

네. Inspector CLI는 실행할 때마다 연결하고, --method로 지정한 메서드 하나를 호출하고, 결과를 출력한 뒤 종료하므로 CI에 잘 맞습니다. --format json은 JSON 객체 하나를 출력합니다. 비정상 종료 코드는 무엇이 실패했는지 알려 줍니다. 3은 서버에 인증이 필요하다는 뜻이고, 4는 서버에 연결할 수 없다는 뜻이며, 5는 도구 호출이 오류를 반환했거나 도구를 찾지 못했다는 뜻입니다. 다음은 API 키로 Sume 서버를 테스트하는 예시입니다.

npx @modelcontextprotocol/inspector --cli https://mcp.sume.com/mcp \
  --transport http \
  --header "Authorization: Bearer $SUME_API_KEY" \
  --method tools/list --format json

npx @modelcontextprotocol/inspector --cli https://mcp.sume.com/mcp \
  --transport http \
  --header "Authorization: Bearer $SUME_API_KEY" \
  --method tools/call --tool-name mcp_health --tool-args-json '{}'

어떤 프로토콜 시대를 골라야 하나요?

MCP 2026-07-28 개정판은 initialize 핸드셰이크를 없앴으므로, Inspector는 시대(era)를 서버별 설정으로 둡니다. 기본값인 legacy는 일반 initialize를 보냅니다. auto는 먼저 새 방식인 server/discover를 시도하고, 안 되면 initialize로 폴백합니다. modern은 폴백 없이 2026-07-28에 고정하므로, 이전 서버는 분명하게 실패합니다. 실제 클라이언트가 쓰는 시대로 테스트하세요.

현재 코드에서 Sume 서버는 핸드셰이크 개정판인 2025-03-26, 2025-06-18, 2025-11-25만 협상하고, 그 밖의 MCP-Protocol-Version 헤더에는 400으로 응답하므로 legacy로 두세요.

Postman에서 MCP 서버는 어떻게 테스트하나요?

MCP 요청을 만들고, streamable HTTP 서버라면 HTTP를 고른 뒤 URL을 입력합니다. 로컬 서버라면 STDIO를 고르고 명령어를 입력합니다. 서버에 인증이 필요하면 Authorization 탭을 열어 Auth Type을 고르고 인증 정보를 넣습니다. Load Capabilities를 클릭하고, Tools 탭을 열어 도구를 고르고 인수를 정한 뒤 Run을 클릭합니다. 응답은 Response 탭에 나타납니다.

curl로 MCP 서버를 테스트할 수 있나요?

네, 프로토콜 메시지를 직접 작성하면 됩니다. Streamable HTTP에서는 모든 메시지가 Accept 헤더에 application/json과 text/event-stream을 모두 담은 POST이며, 2025-11-25 개정판에서는 첫 메시지가 반드시 initialize여야 합니다. 응답에는 프로토콜 버전과 서버가 선언한 기능(capabilities)이 나옵니다. Sume 서버는 현재 tools만 나열합니다.

curl -sS https://mcp.sume.com/mcp \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl-check","version":"1.0.0"}}}'

Sume MCP 서버에서는 무엇을 확인해야 하나요?

Sume 빠른 시작 문서의 읽기 전용 호출부터 시작하세요. mcp_health는 엔드포인트, 인증 출처, 안전 설정을 확인하고, tools_list는 세션에서 보이는 모든 도구를 나열하며, tools_schema는 name으로 도구 하나의 계약을 반환하고, account_me는 워크스페이스를 확인합니다. OAuth에서는 authenticated.auth_source가 mcp_oauth여야 합니다. 유료 도구는 dry_run=true로만 테스트하세요. 이 옵션은 Job을 제출하지 않고 접수와 비용을 미리 보여 줍니다. API 키는 채팅에 붙여 넣지 마세요.

MCP 도구와 게이트에 따르면 tools_list에 쓰기·유료 도구가 없다면 Write 없이 연결한 OAuth 세션입니다. 해결 방법은 Sume MCP insufficient_scope 해결에서, 로그인은 Sume MCP OAuth 플로에서 다룹니다. Sume 기초 페이지는 호스팅 MCP가 여전히 동작하지만 현재 주 경로는 아니라고 설명합니다. 테스트 중에 볼 수 있는 다른 응답은 다음과 같습니다.