Rhumb이 645개 API를 지원하는 다중 제공자 MCP 서버를 구축하면서 API 이름 충돌, 인증 방식 다양성, 페이로드 형식 불일치, 불명확한 에러 메시지, 레이트 제한 정보 부재, 샌드박스 신뢰성, 버전 관리 미흡이라는 7가지 숨겨진 설계 문제 발견

Context

기존 단일 API 기반 MCP 서버 튜토리얼은 SDK 설치 후 도구 정의와 응답 반환으로 완성되지만, 실제로 645개 이상의 API를 86개 카테고리에서 선택하고 인증한 후 호출하는 상황에서는 통하지 않는다. 에이전트가 야간에 자동으로 처리해야 할 실제 운영 환경의 복잡성이 튜토리얼에 반영되지 않아 있다.

Technical Solution

• API 식별자 정규화: Brave의 brave-search-api와 brave-search 같은 이름 충돌을 해결하기 위해 표준 slug 시스템과 alias 해석 레이어 도입
• 인증 방식 추상화: Bearer 토큰(45%), Custom 헤더(25%), Basic Auth(15%), OAuth2(10%), 쿼리 매개변수(5%) 등 5가지 인증 패턴을 사전에 매핑하고 에이전트가 올바른 방식을 선택하도록 구성
• 페이로드 변환 계층: 에이전트가 생성한 JSON을 multipart form data로 변환하고, 쿼리 매개변수 이름(query vs q vs search_query), 배열 포맷(쉼표 분리 vs 브래킷 vs JSON), 날짜 형식(ISO 8601 vs Unix timestamp) 등을 API별로 매핑
• 에러 응답 방어적 파싱: 구조화된 에러 응답이 없는 API(대다수)를 위해 비정형 텍스트 메시지를 파싱하고, 실제 원인(잘못된 API 키 형식)을 구별하도록 구현
• 레이트 제한 추적: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After 헤더 부재 시 API별 독립적인 백오프 전략을 유지하며, GitHub의 기본 제한(5,000/시간)과 2차 제한(문서 작성 엔드포인트) 같은 미공개 제한도 감지
• API 버전 관리: Stripe의 헤더 기반 명시적 버전 고정과 달리 대부분 API의 미버전 엔드포인트에서 email_address → emailAddress 같은 breaking change를 감시하기 위해 프로덕션 기반 테스트 시행
• 샌드박스 회피: CAPTCHA 인증이 필요한 PayPal 샌드박스나 동작이 프로덕션과 다른 샌드박스 대신 제한된 프로덕션 계정으로 테스트

Key Takeaway

MCP 프로토콜이 전송 계층을 제공하지만 실제 API 통합의 20개 차원(오류 처리, 스키마 안정성, 인증 복잡성, 가입 마찰, 문서 품질 등)에 대한 해결책은 각 서버에서 직접 설계해야 한다. API 이름 충돌, 인증 다양성, 페이로드 형식 불일치를 1차 문제로 취급하고 방어적으로 설계하지 않으면 규모 있는 에이전트 시스템은 실패한다.