126개 MCP 도구를 구축했지만, 상담사를 위한 최적의 솔루션은 아닙니다.

Apidog이 API 테스트 및 API 라이프사이클 관리를 위한 명령줄 도구인 Apidog CLI를 개발한 과정을 공유하는 10부작 시리즈입니다. 순서대로 읽거나 관심 있는 게시물로 이동하여 읽어보세요:

MCP가 업계의 화두가 되었을 때, 우리는 126개의 생성된 도구를 갖춘 완전한 MCP 서버를 구축했습니다. 무엇이 잘못되었고, 왜 더 많은 도구가 더 나은 Agent 활성화를 의미하지 않는지에 대한 이야기입니다.

MCP 열풍

2025년 초, MCP (모델 컨텍스트 프로토콜)는 업계의 뜨거운 감자가 되었습니다.

Anthropic은 이 프로토콜을 홍보했습니다. Cursor, Claude Code, Antigravity, 다양한 Agent IDE, 그리고 수많은 SaaS 제품들이 빠르게 이를 따랐습니다. 이 프로토콜은 AI Agent가 외부 도구 및 데이터 소스에 연결할 수 있는 표준화된 방법을 약속했습니다.

그 기간 동안 API를 가진 거의 모든 제품은 동일한 질문을 받았습니다:

"MCP가 있습니까?"

Apidog에게 있어 이 선택은 특히 자연스러워 보였습니다.

왜 MCP가 해답처럼 보였나

Apidog 자체는 API 개발의 포괄적인 기능을 축적했습니다:

• API 문서화
• 스키마 정의
• 목 서버
• 테스트 케이스
• 테스트 시나리오
• 테스트 스위트
• 테스트 보고서
• 가져오기/내보내기 워크플로
• 브랜치 협업
• 그리고 더 많은 기능

만약 Agent가 새로운 소프트웨어 진입점, 즉 사용자가 제품과 상호작용하는 새로운 방식이 된다면, MCP를 통해 이러한 기능을 노출하는 것은 필수적인 과정처럼 보였습니다.

우리는 우리의 기능을 MCP 도구로 패키징할 수 있다면, Agent가 다음을 수행할 수 있을 것이라고 믿었습니다:

• API 문서 쿼리
• 테스트 케이스 생성
• 테스트 시나리오 실행
• 프로젝트 데이터 가져오기/내보내기
• 환경 및 변수 관리
• 브랜치 간 협업

논리는 간단했습니다: 더 많은 기능 노출 = 더 많은 Agent 활성화.

우리가 실제로 구축한 것

우리는 이것을 가볍게 여기지 않았습니다.

Apidog MCP는 몇 개의 수동으로 작성된 엔드포인트로 구성된 간단한 데모가 아니었습니다. 그것은 완전한 MCP 서버였습니다:

세션 시스템

MCP 클라이언트는 먼저 세션을 초기화합니다. 서버는 sessionId를 생성하고 Redis를 통해 세션 상태를 저장합니다. 이후의 요청은 sessionId를 사용하여 계속 접근합니다.

즉, 일회성 HTTP 호출이 아니라 프로토콜 수준의 세션 시스템이었습니다.

도구 카테고리

도구 계층 역시 몇 개의 고정된 엔드포인트로 수동으로 작성되지 않았습니다. 우리는 Apidog의 도구를 여러 카테고리로 나누었습니다:

마지막 카테고리: 126개의 생성된 도구.

각 생성된 도구는 다음을 가졌습니다:

• 고유 식별자
• 특정 API 경로
• HTTP 메서드 (GET, POST, PUT, DELETE 등)
• 필드 설명, 유형 및 열거형 값을 포함하는 완전한 입력 스키마
• 정의된 반환 구조

점진적 공개

도구 노출 압력을 줄이기 위해, 우리는 또한 동적 발견 계층을 구축했습니다:

Agent는 다음을 수행할 수 있었습니다:

1. 먼저 사용 가능한 엔드포인트 도구를 검색 (listOpenApiEndpoints)
2. 그 다음 특정 도구의 OpenAPI 세부 정보를 가져옴 (getOpenApiDetails)
3. 마지막으로 도구 ID로 실제 HTTP 호출을 실행 (executeOpenApi)

이것은 점진적 공개에 대한 우리의 시도였습니다. 우리는 모든 기본 엔드포인트를 직접적이고 명시적으로 노출하지 않았습니다. Agent가 먼저 검색하고, 세부 정보를 얻은 다음, 최종적으로 실행하기를 바랐습니다.

무작위 도구의 벽

하지만 실제 작업을 시작했을 때, 문제들이 빠르게 나타났습니다.

간단한 사용자 요청을 고려해 봅시다:

"이 엔드포인트에 대한 테스트를 추가하고 검증을 실행하는 것을 도와줘."

구현 관점에서 보면, 이것은 합리적인 요청입니다. Apidog은 다음 기능을 가지고 있습니다:

• 엔드포인트 찾기
• 테스트 케이스 생성
• 테스트 시나리오 실행
• 보고서 생성

그러나 Agent의 관점에서는 이 간단한 요청이 실제로 일련의 연속적인 판단을 유발합니다:

Agent는 단순히 올바른 도구를 찾는 것만이 아닙니다. 사용자 문제를 해결하기 시작하기 전에 "어떤 도구를 사용할 것인가"라는 문제를 먼저 해결해야 합니다.

구현 관점에서 보면, 이러한 문제들은 모두 도구를 통해 해결할 수 있습니다. Agent 경험 관점에서 보면, 이것들은 무작위 도구의 벽을 형성합니다.

네 가지 구조적 문제

실제 테스트와 내부 피드백을 통해 우리는 MCP 접근 방식의 네 가지 구조적 문제를 파악했습니다.

문제 1: 도구 발견 비용이 빠르게 증가한다

Apidog은 단 몇 개의 엔드포인트로 설명할 수 있는 제품이 아닙니다.

도구가 십여 개에서 수십 개 또는 수백 개로 늘어나면, Agent는 사용자 문제를 해결하기 시작하기 전에 "어떤 도구를 사용할 것인가"라는 문제를 해결해야 합니다.

우리는 도구 description (AI Agent에 도구를 노출하는 데 사용되는 필드)에 워크플로를 작성하려고 시도했습니다. 예를 들어, 도구 설명은 명시적으로 다음과 같이 기술했습니다:

"엔드포인트 데이터를 쿼리하기 전에 먼저 다른 도구를 통해 프로젝트를 확인한 다음, 세 번째 도구를 통해 프로젝트 메타데이터를 가져와서 최종적으로 현재 도구를 호출해야 합니다."

이 방법은 소규모 도구 세트에서는 작동합니다. 그러나 거대한 도구의 벽에서는 description 자체가 모델의 주의를 놓고 경쟁합니다.

설명에 더 많은 지침을 작성할수록 더 많은 토큰이 소비되었고, Agent가 실제로 그것들을 읽고 따를 가능성은 줄어들었습니다.

문제 2: 비즈니스 스키마가 컨텍스트를 침범한다

각 MCP 도구는 단순히 도구 이름만이 아닙니다.

모든 도구 뒤에는 다음이 있습니다:

• description (도구가 하는 일)
• input schema (매개변수, 유형, 필수/선택 사항)
• 필드 설명 (중첩 구조, 제약 조건)
• 열거형 값 (허용되는 옵션)
• 반환 구조 (응답 형식, 오류 처리)

보수적으로 추정해 봅시다:

사용자의 질문은 50자에 불과할 수 있습니다. 그러나 모델은 단 하나의 MCP 서버를 위해 50,000개의 도구 설명 토큰을 먼저 도입해야 합니다.

이것은 이론이 아닙니다. 업계 데이터가 이를 뒷받침합니다.

Cursor의 공식 블로그 게시물 "동적 컨텍스트 발견"은 MCP 도구 설명, 터미널 세션 및 긴 대화를 온디맨드 로드 가능한 컨텍스트로 변환함으로써 런타임 토큰 소비를 46.9% 줄였다는 귀중한 참조 데이터를 제공했습니다.

Trae의 접근 방식은 더 직접적이었습니다: MCP 도구 수와 단일 도구 설명 길이를 제한했습니다:

• 도구 수 상한: 40개
• 단일 도구 설명 길이 제한: 8000자

실제로 초기 내부 테스트 중 많은 팀에서 Apidog MCP가 Trae에서 일부 도구를 호출할 수 없는 문제가 있다고 보고했습니다. Agent는 제한된 모델 컨텍스트로 인해 절충안을 찾아야 했고, 외부 도구는 가장 먼저 "잘려나갔습니다".

이러한 해결책들은 모두 동일한 사실을 가리킵니다:

도구 설명은 모델 컨텍스트에 무한히 들어갈 수 없습니다.

문제 3: 프로토콜 세션이 실행 체인을 더 무겁게 만든다

Apidog MCP 서버는 다음을 처리해야 합니다:

간단한 도구 호출의 경우, 이러한 비용은 허용 가능합니다. 많은 수의 호출과 빈번한 탐색을 수반하는 Agent 작업의 경우, 이러한 상태 관리 요구사항은 서버와 클라이언트 양쪽의 복잡성을 증가시킵니다.

Apidog MCP를 구현할 때, 팀은 다양한 Agent 클라이언트(Cursor, Claude Code, Antigravity, Trae 등)의 문제 해결 및 적응에 상당한 에너지를 소모했습니다. 그러나 프로토콜 호환성 문제는 계속되었고, 공식 MCP 프로토콜은 새로운 버전으로 계속 패치되었습니다.

모든 당사자가 큰 어려움을 겪었습니다.

문제 4: 원자적 도구는 제품 의미론을 자연스럽게 표현할 수 없다

Apidog의 테스트 시나리오에서 단순히 steps 배열 표현식만 있는 것이 아닙니다.

테스트 시나리오는 다음을 포함합니다:

이것들을 여러 MCP 도구로 나눈 후에도, Agent는 여전히 테스트 오케스트레이션 작업을 스스로 수행해야 합니다.

도구가 원자적일수록 모델은 제품의 내부 의미론을 더 많이 이해해야 합니다:

• 왜 가져오기(import)에 다시 읽기(read-back)가 필요한가?
• 왜 내부 케이스는 다른 업데이트 마커를 가지는가?
• 왜 어설션은 특정 비교 연산자를 요구하는가?
• 왜 변수 추출에는 타입 제약 조건이 있는가?

이것은 명백히 모델의 능력 범위를 넘어섭니다.

이는 Apidog 팀이 내부 제품 의미론을 위해 기술 공학적 조정을 선제적으로 수행하도록 강제했습니다. 원자적 엔드포인트는 단일 MCP 도구 계층 디스패치에 적응하기 위해 수동적으로 변환 계층을 추가했습니다.

엔지니어링 난제와 사후 유지보수 비용은 의심할 여지 없이 힘들었습니다.

근본 원인

이 네 가지 문제의 근본 원인은 동일합니다:

MCP는 도구 연결에 더 적합하지만, 복잡한 R&D 작업에는 도구 연결 이상의 것이 필요합니다. 즉, 실행 가능한 엔지니어링 프로세스가 필요합니다.

잘 정의된 십여 개의 작업을 가진 간단한 제품의 경우, MCP는 잘 작동합니다. Agent는 올바른 도구를 합리적으로 추측하고, 이를 호출하여 결과를 얻을 수 있습니다.

수십 개의 모듈, 수백 개의 작업, 중첩된 구조, 숨겨진 워크플로 및 제품별 의미론을 가진 Apidog과 같은 제품의 경우, MCP만으로는 Agent가 탐색하기 어려운 무작위 도구의 벽을 만듭니다.

우리가 배운 것

전환점

이러한 깨달음은 우리로 하여금 다른 질문을 던지게 했습니다:

만약 MCP가 Agent 활성화의 해답이 아니라면, 무엇이 해답일까?

우리는 MCP의 가치를 버리지 않았습니다. 이는 생태계에 중요한 표준화된 연결을 제공합니다. 하지만 우리는 다음을 할 수 있는 것이 필요했습니다:

• 단순한 도구가 아닌 워크플로 표현
• 순서를 통해 Agent 안내
• 작성 전 유효성 검사
• 엔지니어링 품질 게이트 강제
• 복잡성을 시스템으로 흡수

우리가 도달한 답은: CLI + SKILL이었습니다.

다음 게시물인 왜 우리는 완전히 새로운 Apidog CLI를 개발했는가에서, 우리는 복잡성이 모델 컨텍스트에서 엔지니어링 시스템으로 이동한 아키텍처적 변화와 이것이 Agent 활성화에 모든 것을 어떻게 변화시키는지 탐구할 것입니다.

핵심 요점

• MCP는 "Agent가 도구에 어떻게 연결되는가"에 대한 업계의 해답이 되었습니다.
• 우리는 더 많은 도구가 더 나은 활성화를 의미한다고 생각하여 126개의 MCP 도구를 구축했습니다.
• 실제 작업에서 네 가지 구조적 문제가 드러났습니다: 발견 비용, 컨텍스트 침범, 세션 오버헤드, 제품 의미론.
• 근본 원인: MCP는 도구를 연결하지만, 복잡한 작업에는 실행 가능한 프로세스가 필요합니다.
• 도구 설명이 컨텍스트를 소비할 때, 더 많은 도구는 이점이 아니라 비용입니다.

Apidog을 다운로드하여 단일 작업 공간에서 API를 설계, 목업, 테스트하고 문서화하세요. 명령줄 API 테스트, CI 자동화 및 AI Agent 워크플로를 위한 Apidog CLI에 대해 자세히 알아보세요.