MCP 도구 설계 가이드: 자동 생성의 한계와 운영 환경 최적화

작성자: Charlie Zhang

게시일: 2025년 10월 11일

이 블로그 시리즈에서는 유용한 도구로 구성된 모델 컨텍스트 프로토콜(Model Context Protocol, MCP) 서버를 구축하는 방법을 살펴봤습니다. 처음부터 새로 만드는 대신 기존 프로토콜 버퍼(Protocol Buffers, Protobuf)와 Google의 gRPC 트랜스코딩을 활용하고, 맞춤형 protoc 플러그인으로 MCP 서버 생성을 자동화했습니다. 이를 통해 gRPC 서비스, OpenAPI 사양, REST API, MCP 서버를 모두 동일한 소스에서 생성할 수 있었습니다.

이번 4부에서는 자동 생성된 MCP 도구를 실제 AI 에이전트와 함께 테스트하며 확인한 한계와 설계 원칙을 설명합니다. 도구 수, 입력 구조, 응답 크기, LLM 모델 선택을 중심으로 자동 생성이 적합한 경우와 운영 환경에서 맞춤 설계가 필요한 경우를 비교합니다.

MCP 서버 구축 블로그 시리즈

이 블로그 시리즈는 다음 4개 기사로 구성되어 있습니다.

• 1부: gRPC 트랜스코딩을 사용하여 Protobuf에서 REST API 생성하기
• 2부: Protoc 플러그인을 사용하여 MCP 서버 생성 자동화하기
• 3부: Proto 주석으로 AI 상호작용 향상시키기
• 4부: (본 기사) 실제로 MCP 도구를 실행하면서 얻은 통찰력

MCP 도구 설계에서 확인한 핵심 내용

자동 생성된 MCP 도구를 테스트하는 과정에서 몇 가지 중요한 한계를 확인했습니다. 이 글에서 다루는 핵심 내용은 다음과 같습니다.

• 자동 생성된 MCP 도구의 결정적인 한계
• 도구 수가 중요한 이유와 20개 미만으로 유지해야 하는 이유
• 응답 크기가 AI 워크플로에 미치는 영향
• 자동 생성이 적합한 경우와 맞춤 설계가 필요한 경우

자동 생성된 MCP 도구의 주요 문제점

문제 1: 도구가 너무 많으면 선택 오류가 발생합니다

모든 API 엔드포인트를 MCP 도구로 변환하면 AI가 과도하게 많은 선택지에 직면합니다. 한 서비스는 20개 이상의 도구를 생성했고, 이로 인해 다음과 같은 문제가 발생했습니다.

• 잘못된 도구 선택: AI가 이름은 비슷하지만 목적이 다른 도구를 선택합니다.
• 재시도 루프: 잘못된 도구 변형을 반복적으로 시도합니다.
• 열악한 도구 체이닝: 여러 단계로 구성된 워크플로가 실패합니다.
• 저하된 사용자 경험: 과도한 확인 질문이 발생합니다.

해결책: AI 에이전트당 도구 수를 20개 미만으로 유지하고 목적이 명확한 도구 그룹을 구성합니다.

# 20개의 도구 대신, 집중된 그룹 생성:
bookstore_core = ["get_book", "create_book", "search_books"]  # 3개 도구
user_management = ["get_user", "create_user", "authenticate_user"]  # 3개 도구
order_processing = ["create_order", "get_order_status", "process_payment"]  # 3개 도구
# ...

문제 2: ID 기반 입력은 자연어 요청과 맞지 않습니다

전통적인 API는 프로그래밍 방식의 접근을 위해 ID를 사용합니다.

// 전통적 방식 (개발자 친화적)
message GetBookRequest {
 string book_id = 1;  // "550e8400-e29b-41d4-a716-446655440000"
}

하지만 AI 에이전트는 자연어를 처리합니다. 사용자는 “ID 550e8400…”을 사용하여 책을 가져오라고 말하기보다 “Learning Python 책을 가져와”라고 요청합니다.

해결책: 다음과 같이 자연어를 입력으로 받을 수 있도록 설계해야 합니다.

// AI 친화적 방식 (사용자 친화적)
message SearchBookRequest {
 string title = 1;
 string author = 2;  // 선택적 필터
}

문제 3: 복잡하게 중첩된 입력 매개변수는 오류를 높입니다

전통적인 API는 유연성을 위해 중첩 구조를 사용합니다. 하지만 AI 에이전트는 다음과 같은 이유로 이러한 구조를 이해하는 데 어려움을 겪습니다.

• 필드 간 관계를 이해하기 어려움
• 복잡한 객체를 구성할 때 실수가 발생함

피해야 할 설계:

message CreateOrderRequest {
 OrderDetails order = 1;
 PaymentInfo payment = 2;
 repeated PromotionCode promotions = 4;
 OrderOptions options = 5;
}

더 나은 설계(평탄화):

message CreateSimpleOrder {
 string customer_name = 1;
 string item_name = 2;
 int32 quantity = 3;
 string shipping_address = 4;
}

문제 4: 대규모 응답 페이로드가 컨텍스트 창을 소모합니다

전통적인 API는 포괄적인 중첩 데이터를 반환합니다. 자동 생성된 도구는 응답을 사용자 정의할 수 없으므로 컨텍스트 창 오버플로를 유발할 수 있습니다.

예를 들어, get_location 도구가 인프라, 규정 준수, 네트워크 데이터를 포함한 전체 정보를 반환하면 AI의 컨텍스트 창 대부분을 소모하는 대규모 JSON이 생성될 수 있습니다.

해결책: 포괄적인 API를 MCP 도구로 직접 노출하지 말고 내부적으로 사용하면서 작업 중심의 도구를 노출합니다.

# MCP 도구가 아님 - 내부 도우미
async def _get_location_internal(location_id: str) -> Location:
   # ... (모든 데이터를 가져옴)

# MCP 도구 - 집중된 작업
async def validate_deployment_location(location_name: str) -> ValidationResult:
   """위치가 배포 요구 사항을 충족하는지 확인합니다."""
   location = await _get_location_internal(location_name)
   
   # 내부적으로 처리 및 검증 수행
   # ...
   
   # 필수적인 정보만 반환
   return ValidationResult(
       location_name=location.name,
       is_valid=checks.passed,
       summary=f"Location {location.name} is {'ready' if checks.passed else 'not ready'}"
   )

자동 생성과 맞춤 MCP 도구 설계 비교

LLM 모델 선택이 MCP 도구 설계에 미치는 영향

LLM 모델의 선택은 도구 설계 전략에 상당한 영향을 미칩니다.

강력한 LLM 모델을 사용할 때

강력한 모델은 다음과 같은 이유로 단순하고 간결한 설명만으로도 작업할 수 있습니다.

• 최소한의 정보로 컨텍스트와 의도를 추론하는 데 탁월합니다.
• 도구 간의 암묵적인 관계를 이해합니다.
• 모호성과 예외 상황을 원활하게 처리합니다.

async def create_database_cluster():
   """새 데이터베이스 클러스터를 생성합니다. 필요 항목: 이름, 리전, 인스턴스 유형."""

이러한 모델은 최소한의 안내만으로도 도구를 지능적으로 연결할 수 있습니다.

성능이 낮은 LLM 모델을 사용할 때

소규모 또는 성능이 낮은 모델은 제한된 추론 능력을 보완하기 위해 상세하고 명시적인 설명이 필요합니다.

async def create_database_cluster():
   """자동 구성으로 새 데이터베이스 클러스터를 생성합니다.
   
   이 도구는 다음을 포함한 완전한 클러스터 설정을 처리합니다:
   - 규정 준수 요구 사항 기반 리전 선택
   - 워크로드 힌트 기반 자동 인스턴스 크기 조정
   - 네트워크 구성 및 보안 그룹
   
   사용 시점: 사용자가 모든 세부 정보를 지정하지 않고 데이터베이스를 생성하고자 할 때 사용합니다. AI가 컨텍스트에서 적절한 설정을 추론합니다.
   
   사용하지 말아야 할 시점: 모든 설정을 수동으로 제어해야 하는 경우 create_database_cluster_advanced를 대신 사용하십시오.
   
   피해야 할 일반적인 실수:
   - 사용자가 사용자 지정 네트워크 설정을 지정하는 경우 사용하지 마십시오.
   - 특정 규정 준수가 필요한 운영 클러스터에 사용하지 마십시오.
   """

따라서 약한 모델보다 강력한 LLM 모델로 시작하는 것을 권장합니다. 그 이유는 다음과 같습니다.

1. 조기 최적화 방지: 약한 모델로 도구 문제를 디버깅하면 더 나은 모델에서는 존재하지 않을 문제에 시간을 낭비할 수 있습니다.
2. 더 나은 오류 복구: 강력한 모델은 예외 상황을 처리하고 과도한 도움 없이 오류에서 복구합니다.
3. 더 빠른 반복: 설명이 단순할수록 작성하고 유지 관리할 문서가 줄어들어 반복 속도가 빨라집니다.
4. 운영 품질: 대부분의 운영 환경 배포는 강력한 모델의 이점을 얻습니다.

MCP 도구가 강력한 모델에서 안정적으로 작동하면 다음 방법으로 더 작은 모델을 선택적으로 지원할 수 있습니다.

• 상세한 설명과 예시 추가
• 에이전트 워크플로를 더 단순하고 순차적인 단계로 분할

하이브리드 접근 방식: 자동 생성과 맞춤 설계 결합

자동 생성으로 개념을 신속하게 검증한 다음, 운영 환경을 위해 맞춤형 MCP 도구를 만듭니다.

1단계: 자동 생성으로 프로토타이핑

기존 API를 MCP 도구로 자동 변환하는 가이드를 따릅니다. 이 방식은 신속한 반복, PoC, 내부 도구 개발에 유용합니다.

2단계: 운영 환경을 위한 맞춤형 Proto 정의 설계

운영 환경으로 전환할 때는 MCP 도구를 처음부터 만듭니다. API 엔드포인트가 아닌 사용자 작업을 중심으로 설계하고, 자연어 입력과 평탄한 구조, 목적에 집중된 응답을 사용합니다. “이 API가 무엇을 하는가?”보다 “사용자가 무엇을 달성하려 하는가?”에 초점을 맞추세요.

이 하이브리드 접근 방식은 초기 개발 속도를 확보하면서 필요할 때 운영 품질로 전환할 수 있게 합니다.

결론: 운영 환경에서는 사용자 작업 중심으로 설계하세요

이 네 편의 시리즈에서는 AI 에이전트를 위한 자동화된 API 생성의 강점과 한계를 살펴봤습니다. 핵심은 언제 자동화를 사용하고 언제 맞춤형 설계에 투자할지를 판단하는 것입니다.

메일: salesinquiry@enterprisedb.com

MCP 도구 설계 FAQ

자동 생성된 MCP 도구는 언제 적합한가요?

자동 생성은 신속한 프로토타이핑, 개념 증명(PoC), 내부 도구 개발에 적합합니다. 단순한 CRUD 작업과 평탄한 요청·응답 구조, 소규모 응답 페이로드를 사용하는 환경에서 특히 유용합니다.

운영 환경에서 맞춤형 MCP 도구가 필요한 이유는 무엇인가요?

운영 환경에서는 사용자의 자연어 요청과 실제 작업을 중심으로 도구를 설계해야 합니다. 복잡한 API 엔드포인트를 그대로 노출하기보다 입력 구조를 평탄화하고 필요한 결과만 반환하도록 맞춤 설계하면 도구 선택 오류와 컨텍스트 오버플로 위험을 줄일 수 있습니다.

AI 에이전트당 MCP 도구는 몇 개가 적절한가요?

이 글에서는 AI 에이전트당 도구 수를 20개 미만으로 유지할 것을 권장합니다. 도구가 너무 많으면 잘못된 도구 선택, 반복적인 재시도, 도구 체이닝 실패, 과도한 확인 질문이 발생할 수 있습니다.

MCP 도구 입력은 왜 ID보다 자연어 중심으로 설계해야 하나요?

사용자는 일반적으로 내부 ID보다 책 제목이나 위치 이름처럼 이해하기 쉬운 표현으로 요청합니다. 따라서 자연어 입력을 받을 수 있도록 설계하면 AI 에이전트가 사용자의 의도를 실제 도구 호출과 연결하기 쉬워집니다.

MCP 도구의 응답 크기는 왜 중요한가요?

포괄적인 중첩 데이터를 그대로 반환하면 대규모 JSON이 생성되어 AI의 컨텍스트 창을 과도하게 사용할 수 있습니다. 전체 API 응답을 노출하기보다 특정 작업에 필요한 정보만 반환하는 도구를 설계하는 것이 좋습니다.