{"title":"MCP(Model Context Protocol) 베스트 프랙티스: AI 에이전트를 위한 UI 설계","url":"https://hugo-blog-static-site.haxlys.workers.dev/software/mcp-best-practices/","section":"software","date":"2026-01-23T12:10:00+09:00","lastmod":"2026-01-23T12:10:00+09:00","description":"MCP는 REST API의 연장선이 아니라 AI 에이전트를 위한 사용자 인터페이스(UI)로 설계되어야 한다는 관점에서 6가지 베스트 프랙티스를 정리한 글.","summary":"MCP(Model Context Protocol) 서버를 설계할 때는 인프라가 아니라 \u0026ldquo;AI 에이전트를 위한 UI\u0026rdquo; 를 만든다는 관점이 핵심입니다.\n출처: MCP Best Practices\n이 글의 핵심은 \u0026ldquo;MCP(Model Context Protocol)는 REST API의 연장선이 아니라, AI 에이전트를 위한 사용자 인터페이스(UI)로 설계되어야 한다\u0026rdquo; 는 것입니다.\n1. MCP란 무엇인가? 정의: LLM과 외부 도구, 데이터 소스, 서비스를 연결하는 표준 프로토콜. 핵심 요소: 도구(Tools, 실행 기능), 리소스(Resources, 읽기 전용 데이터), 프롬프트(Prompts, 사전 정의된 워크플로우). 오해: MCP는 단순한 REST API 래퍼가 아닙니다. 개발자가 아닌 \u0026lsquo;AI 에이전트\u0026rsquo;가 사용자임을 인식해야 합니다. 2. MCP 서버 구축을 위한 6가지 베스트 프랙티스 ① 운영(Operations)이 아닌 결과(Outcomes) 중심 설계 문제: REST API처럼 여러 개의 작은 엔드포인트(예: 사용자 찾기 → 주문 목록 → 주문 상태)를 노출하면 에이전트가 여러 번 호출해야 하므로 비효율적입니다. 해결: 에이전트가 한 번에 목적을 달성할 수 있는 고수준 도구(예: track_latest_order)를 제공하세요. 오케스트레이션은 LLM 내부가 아닌 서버 코드에서 처리해야 합니다. ② 인자 구조의 단순화 (Flatten Your Arguments) 문제: 복잡한 중첩 딕셔너리나 객체는 에이전트의 환각(Hallucination)을 유발합니다. 해결: 인자를 최상위 수준의 프리미티브 타입(String, Int 등)으로 평탄화하고, Literal이나 Enum을 사용하여 선택지를 명확히 제한하세요. ③ 설명(Docstrings)은 곧 지침이다 문제: 설명을 비워두거나 모호하게 적는 것. 해결: 도구의 설명과 에러 메시지 자체가 에이전트에게는 \u0026lsquo;프롬프트\u0026rsquo;입니다. 언제 도구를 사용할지, 인자 형식은 어떠해야 하는지, 에러 발생 시 어떻게 수정해야 할지를 상세히 적으세요. ④ 무자비한 큐레이션 (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 서버를 구축할 때는 인프라를 만드는 것이 아니라 \u0026ldquo;AI 에이전트를 위한 UI를 설계한다\u0026rdquo; 는 마음가짐이 필요합니다. 에이전트가 복잡한 단계를 거치지 않고 최소한의 호출로 정확한 결과를 얻을 수 있도록 최적화하는 것이 성공적인 MCP 서버의 핵심입니다.\n","content":"MCP(Model Context Protocol) 서버를 설계할 때는 인프라가 아니라 \u0026ldquo;AI 에이전트를 위한 UI\u0026rdquo; 를 만든다는 관점이 핵심입니다.\n출처: MCP Best Practices\n이 글의 핵심은 \u0026ldquo;MCP(Model Context Protocol)는 REST API의 연장선이 아니라, AI 에이전트를 위한 사용자 인터페이스(UI)로 설계되어야 한다\u0026rdquo; 는 것입니다.\n1. MCP란 무엇인가? 정의: LLM과 외부 도구, 데이터 소스, 서비스를 연결하는 표준 프로토콜. 핵심 요소: 도구(Tools, 실행 기능), 리소스(Resources, 읽기 전용 데이터), 프롬프트(Prompts, 사전 정의된 워크플로우). 오해: MCP는 단순한 REST API 래퍼가 아닙니다. 개발자가 아닌 \u0026lsquo;AI 에이전트\u0026rsquo;가 사용자임을 인식해야 합니다. 2. MCP 서버 구축을 위한 6가지 베스트 프랙티스 ① 운영(Operations)이 아닌 결과(Outcomes) 중심 설계 문제: REST API처럼 여러 개의 작은 엔드포인트(예: 사용자 찾기 → 주문 목록 → 주문 상태)를 노출하면 에이전트가 여러 번 호출해야 하므로 비효율적입니다. 해결: 에이전트가 한 번에 목적을 달성할 수 있는 고수준 도구(예: track_latest_order)를 제공하세요. 오케스트레이션은 LLM 내부가 아닌 서버 코드에서 처리해야 합니다. ② 인자 구조의 단순화 (Flatten Your Arguments) 문제: 복잡한 중첩 딕셔너리나 객체는 에이전트의 환각(Hallucination)을 유발합니다. 해결: 인자를 최상위 수준의 프리미티브 타입(String, Int 등)으로 평탄화하고, Literal이나 Enum을 사용하여 선택지를 명확히 제한하세요. ③ 설명(Docstrings)은 곧 지침이다 문제: 설명을 비워두거나 모호하게 적는 것. 해결: 도구의 설명과 에러 메시지 자체가 에이전트에게는 \u0026lsquo;프롬프트\u0026rsquo;입니다. 언제 도구를 사용할지, 인자 형식은 어떠해야 하는지, 에러 발생 시 어떻게 수정해야 할지를 상세히 적으세요. ④ 무자비한 큐레이션 (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 서버를 구축할 때는 인프라를 만드는 것이 아니라 \u0026ldquo;AI 에이전트를 위한 UI를 설계한다\u0026rdquo; 는 마음가짐이 필요합니다. 에이전트가 복잡한 단계를 거치지 않고 최소한의 호출로 정확한 결과를 얻을 수 있도록 최적화하는 것이 성공적인 MCP 서버의 핵심입니다.\n","wordCount":324,"tags":["MCP","AI","에이전트","Model Context Protocol","베스트 프랙티스"],"categories":["software","ai"],"frameworks":["Outcomes-over-operations","Agent-first-design"],"mental_models":["UI-for-AI","Minimal-calls"],"philosophy_type":"decision-making","schema_type":"TechArticle","actionable":true,"priority":"high","key_points":["MCP(Model Context Protocol) 베스트 프랙티스: AI 에이전트를 위한 UI 설계의 핵심 문제의식은 \"MCP는 REST API의 연장선이 아니라 AI 에이전트를 위한 사용자 인터페이스(UI)로 설계되어야 한다는 관점에서 6가지 베스트 프랙티스를 정리한 글.\"다","MCP, AI, 에이전트 관점에서 기존 글들과 연결해 읽을 수 있다","발행 전 원문 근거, 내부 링크, 결론의 실행 가능성을 함께 점검해야 한다"],"related":["posts/rl-environments-for-llm-agents","software/agent-psychosis","software/agent-skills-rules-commands"]}