MCP 카탈로그 도구 설계: 수십 개의 엔드포인트에서 대규모 작업 세트로

요약: 이 엔지니어링 노트는 UnifAPI가 왜 대규모 작업 카탈로그를 세 개의 MCP 도구를 통해 노출하는지, 그리고 왜 Skills가 그 카탈로그 위에 있는 사용자 대면 레이어인지 설명합니다.

UnifAPI의 첫 MCP 카탈로그는 73개의 엔드포인트를 노출했습니다. 현재 카탈로그는 실시간 공개 데이터 API 전반의 대규모 작업 세트를 list_operations, get_operation, call_api라는 세 개의 MCP 도구를 통해 노출합니다. 이를 잘 해내는 일은 보이는 것보다 어렵습니다. 모델은 여전히 올바른 작업을 발견하고, 스키마를 검사하고, 깔끔하게 호출해야 합니다. 다음은 작업이 수십 개씩 라이브로 올라가기 전까지는 드러나지 않는 네이밍, 설명, 파라미터 스키마, 그리고 실패 모드에 대해 우리가 배운 것입니다.

대규모 작업 세트가 제품을 바꾸는 이유

작업이 510개일 때 MCP는 "그냥 작동합니다" — 모델이 카탈로그를 검색하고, 하나를 고르고, 호출합니다. 2030개가 되면 작업 네이밍이 중요해지기 시작하고, 모델이 가끔 비슷하지만 잘못된 경로를 고르는 모습이 보입니다. 50개를 넘어가면 카탈로그 자체가 하중을 지탱하는 요소가 됩니다.

작업 수는 계속 늘어나겠지만, 제품 측면의 교훈은 이미 분명합니다. 작업 수가 늘수록 Skills가 더 중요해집니다. Skills는 카탈로그 탐색을 작업 결과 뒤로 감추기 때문입니다.

작업 네이밍: 사람이 아니라 에이전트가 읽기 좋게

우리의 작업 레이블은 하나의 패턴을 따릅니다. 플랫폼, 동사, 명사. TikTok search videos, Reddit get post, LinkedIn search people. 장황하지만 모호하지 않습니다. 모델은 이름이 코드 식별자가 아니라 문장 조각처럼 읽히기 때문에 올바른 작업을 고릅니다.

초기에 더 짧은 규칙을 시도했고 — tiktok.search, reddit.post — 비슷한 짝에서 모델이 잘못 고르는 모습을 봤습니다(사용자가 "search"라고 했을 때 TikTok의 "search"와 Reddit의 "search"). 작업 제목의 플랫폼 접두어는 모델이 따로 추론하지 않아도 모호함을 없애 줍니다.

설명이 곧 프롬프트입니다

각 작업 설명은 한두 문장입니다. 모델은 발견과 검사 단계에서 이를 봅니다. 토큰값을 하는 두 가지 패턴이 있습니다. 첫 12단어 안에 동사-목적어 요약을 앞세우고, 끝에 use-when 힌트를 붙이는 것입니다.

좋은 예: "Search TikTok for videos matching a keyword or hashtag. Use when the user wants short-video discovery on a topic." 나쁜 예: "This endpoint allows you to query the TikTok platform and retrieve a paginated list of videos that match a search term, optionally filtered by various parameters including ..." 두 번째 것이 기술적으로는 더 완전하지만, 대규모 카탈로그에서는 잘못된 트레이드오프입니다.

파라미터 스키마: 평평하게 유지하라

call_api는 평평한 객체를 받습니다. path, method, query, body. 필수 필드를 먼저, 선택 필드를 뒤에 둡니다. 이유는 단순합니다. 중첩된 JSON 스키마는 모델의 도구 호출 생성기를 혼란스럽게 합니다. 우리는 Claude가 파라미터를 올바르게 이해해 놓고도, 스키마가 가지치기처럼 보였다는 이유로 잘못된 중첩 수준에 출력하는 모습을 지켜봤습니다.

작업이 진짜로 다형 입력(키워드로 검색 OR 해시태그로 검색)을 필요로 할 때는, get_operation이 구체적인 호출 예제를 보여줘야 합니다. 구체적인 예제는 매번 가지치기형 스키마를 이깁니다.

우리가 잘못한 것

이름을 붙일 만한 실수가 세 가지 있습니다. 첫째, 우리는 Twitter와 Reddit의 각 검색 작업이 거의 동일한 설명을 갖도록 두었고, 사용자가 명시적으로 한쪽을 요청했는데도 모델이 다른 쪽을 고르기 시작했습니다. 각 설명의 첫 문장에서 플랫폼을 명시적으로 부르게 하여 해결했습니다.

둘째, 한동안 출처 오류 메시지를 그대로 통과시켰습니다. 그중 일부는 모델이 이해하지 못하는 플랫폼별 개념을 참조하고, 에이전트는 우리 envelope가 감추고 있던 문제를 고치려고 루프에 빠지곤 했습니다. unauthorized, validation_error, invalid_id, not_found, rate_limited, upstream_unavailable 같은 닫힌 어휘로 오류를 정규화하여 해결했습니다.

셋째, 몇몇 작업에서 페이지네이션을 충분히 문서화하지 않았고, 모델은 매 루프마다 커서를 진행시키는 대신 커서 0부터 다시 호출하곤 했습니다. 페이지네이션 계약을 스펙뿐 아니라 검사된 작업 데이터 자체에 명확히 적어서 해결했습니다.

남은 질문들

언제 카탈로그를 분할해야 할까요? 대규모 작업 세트는 오늘날 하나의 MCP 서버 뒤에 들어가지만, 카탈로그는 결국 카테고리 필터나 카테고리별 서버가 필요해질 수 있습니다. 그래야 모델이 필요한 것만 로드하니까요.

아직 정답은 모릅니다. 오늘 UnifAPI 작업을 많이 소비하는 에이전트를 출시하고 있다면, 당신 쪽에서 작업 선택 지연이 어떻게 보이는지 듣고 싶습니다 — hello@unifapi.com으로 알려주세요.

다음에 읽을 글

통합 응답 봉투 - 도구 발견을 응답 계약과 짝지어 줍니다.

UnifAPI MCP 연결하기 - 운영자 대면 설정 경로를 보여줍니다.

개발자 리소스 - 기계가 읽을 수 있는 스펙과 문서를 모아 둡니다.