연재: AI에게 일자리를 빼앗길 불안으로부터 시작하는 하네스 작성 입문

제18회: MCP 서버의 단위 테스트(Unit Test)·결합 테스트(Integration Test) 관점 만들기

제1~17회: ✅ 공개 완료 ｜ 해당 기사: 📖 ｜ 다음 회차: 제19회

지난 회차(제17회)에서는 AI 에이전트/하네스 개발을 위한 QA 관점표를 작성했습니다. 이번에는 그 관점을 MCP 서버의 구체적인 테스트 케이스로 구체화합니다.

"MCP 서버 테스트는 무엇을 작성해야 하나요?"라는 질문에 테스트 케이스 표와 pytest 코드 예시로 답하겠습니다.

MCP 서버의 테스트에는 일반적인 Web API 테스트와는 다른 어려움이 있습니다.

이러한 차이점을 바탕으로 단위 테스트와 결합 테스트의 관점을 정리합니다.

단위 테스트에서는 각 도구(핸들러)를 개별적으로 테스트합니다. 외부 의존성은 모크(Mock)로 대체합니다.

정상계: 유효한 입력으로 기대한 대로의 출력이 반환되는가 -
이상계: 부적절한 입력으로 적절한 에러가 반환되는가 -
경계값: 빈 문자열, 최대 길이, 특수 문자에 대한 동작 -
타입 검증: 부적절한 타입의 인자에 대한 동작 -
필수 파라미터: 필수 파라미터 누락 시의 동작 -

import pytest
from unittest.mock import AsyncMock, patch
class TestSearchTool:
...

결합 테스트에서는 도구 간의 연계나 외부 서비스와의 접속을 테스트합니다.

도구 연계: 여러 도구의 순차적 호출이 올바르게 동작하는가 -
세션 관리: 세션 상태가 올바르게 유지되는가 -
에러 전파: 상위 도구의 에러가 하위로 적절히 전달되는가 -
타임아웃: 외부 서비스 타임아웃 시의 동작 -
동시 접속: 여러 요청의 병렬 처리 -

import pytest
class TestToolIntegration:
"""도구 간 연계의 결합 테스트"""
...

MCP 서버의 테스트 케이스를 일람표로 정리했습니다.

테스트 파일 구성은 다음과 같이 하면 관리하기 쉬워집니다.

tests/
├── conftest.py # 공통 피스처(Fixture)
├── unit/
...

pytest의 피스처(Fixture)를 사용하여 테스트의 셋업을 공통화합니다.

# conftest.py
import pytest
@pytest.fixture
...

테스트 설계는 SE(시스템 엔지니어)가 가장 잘하는 영역 중 하나입니다.

테스트 관점 도출 → MCP 도구별 테스트 관점에 응용 -
이상계를 먼저 생각하는 습관 → AI 특유의 에러 패턴 테스트에 활용 -
테스트 데이터 설계 → 피스처를 통한 테스트 데이터 관리에 응용 -
CI/CD 파이프라인 설계 → 자동 테스트 실행 통합에 활용 -

모든 테스트를 한 번에 작성할 필요는 없습니다. 다음 순서로 진행하는 것을 추천합니다.

먼저 정상계 1건: 각 도구의 기본 동작 확인 -
다음으로 이상계: 부적절한 입력·에러 핸들링 테스트 -
마지막으로 결합 테스트: 도구 연계 동작 확인 -

• MCP 서버의 테스트는 단위 테스트(5가지 관점)와 결합 테스트(5가지 관점)로 나누어 생각할 것
• 단위 테스트에서는 모크를 활용하고, 결합 테스트에서는 도구 간 연계를 검증할 것
• pytest의 피스처를 통해 테스트 셋업을 공통화할 것
• 우선 정상계 1건부터 시작하는 것이 현실적임
• SE의 테스트 설계 경험을 그대로 활용할 수 있음

제19회 "기밀 정보를 LLM에 전달하지 않는 하네스 설계"에서는 보안 관점에서 하네스가 다루는 기밀 정보의 리스크를 정리합니다. API 키, 개인 정보, 사내 코드 등의 데이터 종류별로 리스크 레벨과 대책을 정리하고, 마스킹·액세스 제어 설계를 수행합니다.

📖 연재 목록: 제117회 ✅ 공개 완료 ｜ 제18회 (본 기사) ｜ 제19회 속권 예정