MCP(Model Context Protocol) 서버를 설계할 때는 인프라가 아니라 “AI 에이전트를 위한 UI” 를 만든다는 관점이 핵심입니다.

출처: MCP Best Practices

이 글의 핵심은 “MCP(Model Context Protocol)는 REST API의 연장선이 아니라, AI 에이전트를 위한 사용자 인터페이스(UI)로 설계되어야 한다” 는 것입니다.

1. MCP란 무엇인가?

  • 정의: LLM과 외부 도구, 데이터 소스, 서비스를 연결하는 표준 프로토콜.
  • 핵심 요소: 도구(Tools, 실행 기능), 리소스(Resources, 읽기 전용 데이터), 프롬프트(Prompts, 사전 정의된 워크플로우).
  • 오해: MCP는 단순한 REST API 래퍼가 아닙니다. 개발자가 아닌 ‘AI 에이전트’가 사용자임을 인식해야 합니다.

2. MCP 서버 구축을 위한 6가지 베스트 프랙티스

① 운영(Operations)이 아닌 결과(Outcomes) 중심 설계

  • 문제: REST API처럼 여러 개의 작은 엔드포인트(예: 사용자 찾기 → 주문 목록 → 주문 상태)를 노출하면 에이전트가 여러 번 호출해야 하므로 비효율적입니다.
  • 해결: 에이전트가 한 번에 목적을 달성할 수 있는 고수준 도구(예: track_latest_order)를 제공하세요. 오케스트레이션은 LLM 내부가 아닌 서버 코드에서 처리해야 합니다.

② 인자 구조의 단순화 (Flatten Your Arguments)

  • 문제: 복잡한 중첩 딕셔너리나 객체는 에이전트의 환각(Hallucination)을 유발합니다.
  • 해결: 인자를 최상위 수준의 프리미티브 타입(String, Int 등)으로 평탄화하고, Literal이나 Enum을 사용하여 선택지를 명확히 제한하세요.

③ 설명(Docstrings)은 곧 지침이다

  • 문제: 설명을 비워두거나 모호하게 적는 것.
  • 해결: 도구의 설명과 에러 메시지 자체가 에이전트에게는 ‘프롬프트’입니다. 언제 도구를 사용할지, 인자 형식은 어떠해야 하는지, 에러 발생 시 어떻게 수정해야 할지를 상세히 적으세요.

④ 무자비한 큐레이션 (Curate Ruthlessly)

  • 문제: API의 모든 기능을 노출하여 컨텍스트 창을 낭비하는 것.
  • 해결: 서버당 도구를 5~15개로 제한하세요. 사용하지 않는 도구는 삭제하고, 용도에 따라 서버를 분리(예: 관리자용/사용자용)하여 에이전트가 필요한 도구를 빨리 찾게 하세요.

⑤ 검색이 용이한 이름 지정 (Name for Discovery)

  • 문제: create_issue 같이 너무 일반적인 이름은 다른 서비스와 충돌할 수 있습니다.
  • 해결: {서비스}_{동사}_{리소스} 형식을 권장합니다. (예: slack_send_message, jira_create_issue)

⑥ 대량 결과의 페이지네이션 (Paginate Large Results)

  • 문제: 수백 개의 레코드를 한꺼번에 반환하면 컨텍스트 창이 폭발합니다.
  • 해결: limit 파라미터를 제공하고, has_more, next_offset 같은 메타데이터를 포함하여 에이전트가 필요한 만큼만 데이터를 가져오게 하세요.

결론

MCP 서버를 구축할 때는 인프라를 만드는 것이 아니라 “AI 에이전트를 위한 UI를 설계한다” 는 마음가짐이 필요합니다. 에이전트가 복잡한 단계를 거치지 않고 최소한의 호출로 정확한 결과를 얻을 수 있도록 최적화하는 것이 성공적인 MCP 서버의 핵심입니다.