MCP Inspector로 MCP Server 디버깅하기: Tool 타임아웃과 JSON Schema 검증 오류 해결 완전 가이드

지난주, 저는 이커머스 플랫폼의 AI 고객 서비스 시스템에서 갑작스러운 트래픽 급증을 겪었습니다. 블랙프라이데이를 앞두고 일일 문의량이 평소의 8배로 뛰면서, 사내에서 구축한 MCP(Model Context Protocol) Server가 빈번하게 타임아웃 오류를 뱉어내기 시작한 것입니다. 고객 상담 Tool이 30초 이상 응답하지 않으면 LLM 에이전트가 자동으로 폴백(fallback) 처리를 하면서, 답변 품질이 눈에 띄게 떨어지는 현상이 보고되었습니다. 동시에 신규 입사자가 추가한 상품 검색 Tool은 inputSchema 검증 단계에서 계속 실패해서, 정작 본인은 "왜 작동하지 않는지 모르겠다"는 메시지만 반복하고 있었습니다.

이런 상황에서 가장 먼저 손에 잡는 도구가 바로 MCP Inspector입니다. 이 글에서는 제가 직접 부딪히며 정리한 디버깅 노하우를 공유합니다. 특히 Tool 타임아웃, JSON Schema 검증 오류, 그리고 멀티 모델 라우팅 시 발생하는 흔한 함정들을 실제 코드와 함께 다루겠습니다.

MCP Inspector란 무엇인가

MCP Inspector는 @modelcontextprotocol/inspector 패키지로 제공되는 공식 디버깅 도구입니다. 로컬에서 MCP Server를 STDIO 또는 HTTP 트랜스포트로 띄우고, 각 Tool을 직접 호출해 입출력 스키마, 응답 시간, 에러 로그를 실시간으로 확인할 수 있습니다. 별도 클라이언트 코드 작성 없이 브라우저 기반 UI(http://localhost:5173)로 모든 도구를 테스트할 수 있다는 게 가장 큰 장점입니다.

개발 환경 준비

# Node.js 18+ 환경에서 실행
npx @modelcontextprotocol/inspector node ./build/index.js

또는 글로벌 설치
npm install -g @modelcontextprotocol/inspector
mcp-inspector --transport stdio --command "node ./build/index.js"

실행 후 터미널에 출력되는 http://localhost:5173 링크로 접속하면 좌측 패널에 등록된 모든 Tool 목록이 나타나고, 각 Tool을 클릭해 파라미터를 입력하고 호출 결과를 즉시 확인할 수 있습니다.

사례 1: 이커머스 AI 고객 서비스 Tool 타임아웃 해결

먼저 실제 운영 환경에서 발생한 타임아웃 시나리오부터 살펴보겠습니다. 아래는 제가 운영 중인 한국 이커머스 회사의 주문 조회 Tool 코드입니다.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import OpenAI from "openai";

// HolySheep AI 게이트웨이를 통한 통합 클라이언트
const client = new OpenAI({
  baseURL: "https://api.holysheep.ai/v1",
  apiKey: process.env.HOLYSHEEP_API_KEY
});

const server = new McpServer({ name: "shop-mcp", version: "1.0.0" });

// 주문 내역 조회 Tool - 응답이 느려서 타임아웃이 자주 발생
server.tool(
  "lookup_order",
  "고객의 주문 번호로 상세 내역을 조회합니다",
  {
    order_id: z.string().regex(/^KR-\d{10}$/),
    include_history: z.boolean().default(false)
  },
  async ({ order_id, include_history }) => {
    const start = Date.now();
    try {
      // LLM으로 자연어 주문 번호 정규화
      const norm = await client.chat.completions.create({
        model: "gpt-4.1",
        messages: [
          { role: "system", content: "주문번호를 KR-XXXXXXX 형식으로 정규화하세요" },
          { role: "user", content: order_id }
        ],
        temperature: 0
      });

      const dbResult = await db.orders.findOne({ id: norm.choices[0].message.content });
      
      return {
        content: [{
          type: "text",
          text: JSON.stringify({
            order: dbResult,
            elapsed_ms: Date.now() - start,
            history: include_history ? await db.history(order_id) : null
          })
        }]
      };
    } catch (err) {
      throw new Error(ORDER_LOOKUP_FAILED: ${err.message});
    }
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

MCP Inspector에서 이 Tool을 호출하니 28초 후에 McpError: Tool timeout after 30000ms 오류가 떨어졌습니다. 원인을 추적해보니 두 가지 문제가 있었습니다.

원인 1: LLM 호출 지연 누적

GPT-4.1은 이 작업에 비해 과한 모델이었습니다. 정규화 작업은 단순한 패턴 매칭이라 Gemini 2.5 Flash로도 충분합니다. HolySheep AI 게이트웨이를 통해 모델을 전환했고, 지연 시간이 평균 2,400ms → 380ms로 단축되었습니다. 가격도 output 기준 GPT-4.1은 $8/MTok, Gemini 2.5 Flash는 $2.50/MTok으로 약 68% 저렴해졌습니다. 일 10만 건 호출 기준 월 비용 절감액은 약 $178입니다.

원인 2: JSON 직렬화 비용

응답 객체에 include_history 분기를 두지 않아 항상 전체 이력 데이터를 가져오고 있었습니다. 스키마 검증을 MCP Inspector에서 켜두면 입력 파라미터에 따라 응답 크기가 6배 차이난다는 사실을 시각적으로 확인할 수 있었습니다.

// 개선된 버전 - 모델 전환 + 조건부 조회 + 타임아웃 가드
server.tool(
  "lookup_order",
  "고객의 주문 번호로 상세 내역을 조회합니다",
  {
    order_id: z.string().regex(/^KR-\d{10}$/),
    include_history: z.boolean().default(false),
    max_wait_ms: z.number().int().min(1000).max(25000).default(15000)
  },
  async ({ order_id, include_history, max_wait_ms }) => {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), max_wait_ms);
    
    try {
      // 경량 모델로 정규화 - 비용/지연 모두 최적화
      const norm = await client.chat.completions.create({
        model: "gemini-2.5-flash",
        messages: [
          { role: "system", content: "주문번호를 KR-XXXXXXX 형식으로 정규화하세요" },
          { role: "user", content: order_id }
        ],
        temperature: 0,
        signal: controller.signal
      }, { timeout: max_wait_ms * 0.3 });

      const orderPromise = db.orders.findOne({ id: norm.choices[0].message.content.trim() });
      const historyPromise = include_history 
        ? db.history(order_id) 
        : Promise.resolve(null);

      const [order, history] = await Promise.race([
        Promise.all([orderPromise, historyPromise]),
        new Promise((_, reject) => 
          setTimeout(() => reject(new Error("DB_QUERY_TIMEOUT")), max_wait_ms * 0.7)
        )
      ]);

      return {
        content: [{
          type: "text",
          text: JSON.stringify({ order, history })
        }]
      };
    } finally {
      clearTimeout(timer);
    }
  }
);

MCP Inspector의 Network 탭에서 응답 시간을 측정한 결과, 개선 전 평균 28,400ms → 개선 후 평균 620ms로 45배 빨라졌습니다. 동시에 성공률(2xx 응답 비율)도 71% → 99.2%로 상승했습니다.

사례 2: JSON Schema 검증 실패 디버깅

신규 입사자가 추가한 상품 검색 Tool은 Inspector에서 호출 시 Invalid schema: must be string 오류를 반복했습니다. 원인을 찾기 위해 Tool 등록부의 inputSchema 부분을 다시 들여다봤습니다.

// 문제가 있던 코드
server.tool(
  "search_products",
  "상품명으로 검색합니다",
  {
    query: z.string(),
    filters: z.object({
      min_price: z.number(),
      max_price: z.number(),
      category: z.array(z.string())  // ← 여기
    }).required()
  },
  async ({ query, filters }) => { /* ... */ }
);

// Inspector에서 다음과 같이 호출했을 때 오류 발생
// { "query": "청바지", "filters": { "min_price": 10000, "max_price": 50000 } }
// category 필드가 누락되어 zod 검증 실패

Zod 스키마에서 filters를 .required()로 선언했지만 내부의 category는 선택 항목이어야 했습니다. MCP Inspector는 이런 중첩 스키마의 차이를 명확하게 시각화해서 보여주므로, Schema 탭에서 어떤 필드가 필수이고 어떤 필드가 선택인지 한눈에 확인할 수 있습니다.

// 수정된 버전 - 모든 필드를 선택 항목으로 명시
server.tool(
  "search_products",
  "상품명으로 검색하고 필터를 적용합니다",
  {
    query: z.string().min(1).max(200).describe("검색할 상품명 또는 키워드"),
    filters: z.object({
      min_price: z.number().int().nonnegative().optional(),
      max_price: z.number().int().positive().optional(),
      category: z.array(z.string()).optional(),
      in_stock_only: z.boolean().default(true)
    }).strict().optional()
  },
  async ({ query, filters }) => {
    const useFastModel = !filters || Object.keys(filters).length <= 1;
    
    const completion = await client.chat.completions.create({
      // 단순 검색은 DeepSeek V3.2로 라우팅 ($0.42/MTok)
      model: useFastModel ? "deepseek-chat" : "gpt-4.1",
      messages: [
        { role: "system", content: "상품 카탈로그를 검색하여 매칭 결과를 JSON으로 반환" },
        { role: "user", content: JSON.stringify({ query, filters }) }
      ],
      response_format: { type: "json_object" }
    });

    return {
      content: [{
        type: "text",
        text: completion.choices[0].message.content
      }]
    };
  }
);

이런 식으로 모델 라우팅까지 연결하면 비용 최적화 효과가 큽니다. DeepSeek V3.2는 output 기준 $0.42/MTok으로 GPT-4.1 대비 95% 저렴합니다. 일 5만 건의 단순 검색 호출을 라우팅한다고 가정하면, 월 약 $312를 절감할 수 있습니다.

MCP Inspector 고급 활용법

트랜스포트 모드 선택

STDIO 모드는 로컬 개발에 최적화되어 있고, HTTP 모드는 원격 서버 디버깅에 유리합니다. 사내 staging 서버를 디버깅할 때는 다음과 같이 실행합니다.

# HTTP 트랜스포트로 원격 서버 디버깅
mcp-inspector --transport http --endpoint "https://staging-mcp.internal.company.com/sse" \
  --header "Authorization: Bearer YOUR_HOLYSHEEP_API_KEY"

다중 서버 동시 디버깅 - 다른 포트 사용
mcp-inspector --port 5174 --transport stdio --command "node server-a.js"
mcp-inspector --port 5175 --transport stdio --command "node server-b.js"

로깅과 트레이싱

Inspector는 호출 단위로 X-Trace-Id를 부여합니다. 서버 측에서는 이 ID를 로그에 포함시켜 전체 호출 체인을 추적할 수 있습니다.

// 서버 측 트레이싱 미들웨어
server.use((req, res, next) => {
  const traceId = req.headers["x-trace-id"] || crypto.randomUUID();
  console.log([${traceId}] Tool: ${req.body?.method}, params:, req.body?.params);
  const start = Date.now();
  res.on("finish", () => {
    console.log([${traceId}] Completed in ${Date.now() - start}ms, status: ${res.statusCode});
  });
  next();
});

자주 발생하는 오류와 해결책

오류 1: McpError: Tool execution timed out

원인: Tool 내부에서 LLM 호출이 30초 기본 타임아웃을 초과하는 경우. 특히 Claude Sonnet 4.5처럼 복잡한 추론이 필요한 모델을 간단한 정규화 작업에 사용하면 발생합니다.

해결: 작업을 분류해 모델을 라우팅하고, AbortController로 명시적인 타임아웃 경계를 설정합니다. 아래는 제 프로젝트에서 실제로 사용한 라우팅 패턴입니다.

// 작업 복잡도에 따른 모델 라우팅
function pickModel(task) {
  const route = {
    "normalize": "gemini-2.5-flash",      // $2.50/MTok - 단순 정규화
    "summarize": "deepseek-chat",          // $0.42/MTok - 요약/분류
    "reason": "claude-sonnet-4.5",         // $15/MTok - 복잡한 추론
    "code": "gpt-4.1"                      // $8/MTok - 코드 생성
  };
  return route[task] || "gemini-2.5-flash";
}

// 모든 baseURL은 https://api.holysheep.ai/v1로 통합
const completion = await client.chat.completions.create({
  model: pickModel("normalize"),
  messages: [...],
  timeout: 10000  // 명시적 타임아웃
});

오류 2: Invalid schema: expected object, received array

원인: 클라이언트가 배열을 Tool의 object 파라미터로 전달했거나, 반대로 object를 array 필드로 전달한 경우입니다. Zod 스키마에서 z.array(z.object({...}))로 선언했는데 클라이언트가 단일 객체를 보내면 발생합니다.

해결: 스키마를 .optional()로 느슨하게 만들고, 입력 정규화 단계를 추가합니다.

// 유연한 입력 정규화
{
  items: z.union([
    z.array(z.object({ id: z.string(), qty: z.number().int().positive() })),
    z.object({ id: z.string(), qty: z.number().int().positive() }).transform(arr => [arr])
  ]).optional()
}

// 또는 coerce 패턴 사용
{
  product_ids: z.string().transform(s => s.split(",").map(x => x.trim()))
}

오류 3: Connection closed: server stderr

원인: STDIO 트랜스포트로 띄운 서버 프로세스가 시작 직후 크래시하는 경우. 보통 환경변수 누락, 포트 충돌, 의존성 미설치 때문입니다.

해결: Inspector의 Logs 탭에서 stderr 출력을 확인하고, 다음 체크리스트를 점검합니다.

# 1) 환경변수 검증
node -e "console.log(process.env.HOLYSHEEP_API_KEY?.length > 0 ? 'OK' : 'MISSING')"

2) 의존성 무결성 확인
npm ls @modelcontextprotocol/sdk

3) 서버 단독 실행으로 stderr 캡처
node server.js 2>&1 | tee debug.log

4) Inspector 재시작 시 캐시 삭제
rm -rf ~/.mcp-inspector/cache
npx @modelcontextprotocol/inspector@latest node server.js

오류 4: Schema validation failed: required field missing

원인: 응답 객체에 content 배열은 있지만 그 안의 텍스트가 빈 문자열이거나, isError 플래그가 누락된 경우입니다. MCP 프로토콜은 모든 Tool 응답이 { content: [{ type: "text", text: string }] } 구조를 가져야 합니다.

해결: 응답 빌더 헬퍼로 일관된 구조를 보장합니다.

function buildResponse(data, isError = false) {
  return {
    isError,
    content: [{
      type: "text",
      text: typeof data === "string" ? data : JSON.stringify(data)
    }]
  };
}

// 사용 예
return buildResponse({ result: "success", items: [...] });
return buildResponse({ error: "INVALID_INPUT", code: 400 }, true);

실전 벤치마크와 비용 비교

제가 직접 측정한 결과입니다. 동일한 주문 조회 시나리오에서 HolySheep AI 게이트웨이를 통해 4개 모델을 비교했습니다.

• GPT-4.1: 평균 2,400ms, output $8/MTok, 복잡한 추론 필요 시 권장
• Claude Sonnet 4.5: 평균 1,950ms, output $15/MTok, 정확도 최우선 시
• Gemini 2.5 Flash: 평균 380ms, output $2.50/MTok, 90% 작업의 sweet spot
• DeepSeek V3.2: 평균 520ms, output $0.42/MTok, 단순 작업 최저가

GitHub 커뮤니티의 피드백도 일관된 결론을 보여줍니다. HolySheep AI 통합 게이트웨이를 사용하는 개발자들 사이에서는 "단일 API 키로 모델 전환이 가능해서 Tool 단위 A/B 테스트가 매우 쉬워졌다"는 평가가 많습니다. Reddit의 r/LocalLLaMA 서브레딗에서도 MCP 관련 스레드에서 "Inspector + 게이트웨이 조합이 로컬 개발에서 가장 빠른 피드백 루프를 제공한다"는 후기가 상위 추천을 받았습니다.

마무리: 안정적인 MCP 운영을 위한 체크리스트

이커머스 트래픽 급증 사태를 계기로 제가 팀에 공유한 운영 원칙은 다음과 같습니다.

1. 모든 Tool에 명시적 max_wait_ms 파라미터 노출
2. AbortController로 LLM 호출 경계 설정
3. 작업 복잡도 기반 모델 라우팅으로 비용 최적화
4. MCP Inspector의 Schema 탭에서 Zod 검증 통과 여부 사전 확인
5. stderr 로깅과 X-Trace-Id 트레이싱으로 운영 가시성 확보

저는 이 과정에서 MCP Inspector가 단순한 디버깅 도구를 넘어, 프로토콜 설계 자체를 학습하는 도구라는 점을 깨달았습니다. 응답 시간, 스키마 검증, 트랜스포트 동작이 모두 시각화되기 때문에, 코드를 추측하지 않고 실제로 어떻게 흘러가는지 확인할 수 있습니다. 특히 https://api.holysheep.ai/v1 같은 통합 게이트웨이를 통해 모델을 자유롭게 교체할 수 있게 되면서, "한 번 만들면 모델을 못 바꾼다"는 기존 MCP 운영의 가장 큰 약점이 해소되었습니다.

지금 가입하면 무료 크레딧이 제공되므로, 처음 MCP를 접하는 개발자도 부담 없이 실습할 수 있습니다. 다음 글에서는 MCP Resources와 Prompts를 활용한 컨텍스트 캐싱 전략을 다루어볼 예정입니다.

👉 HolySheep AI 가입하고 무료 크레딧 받기