모델을 시스템에 연결하기 — 도구 호출과 MCP 서버 설계

8.1 함수 호출로 모델을 외부 시스템에 연결하기

Claude는 기본적으로 텍스트를 생성할 뿐, 사내 데이터를 조회하거나 외부 API를 호출하지는 못합니다. 도구 호출(tool use, 모델이 미리 정의된 함수를 지목해 실행을 요청하는 방식)은 이 간극을 메웁니다. 개발자가 도구의 이름·설명·입력 스키마(input schema, 인자의 형식을 JSON으로 규정한 명세)를 함께 전달하면, 모델은 사용자 요청을 읽고 어떤 도구를 어떤 인자로 부를지 판단해 구조화된 호출을 돌려줍니다. 실제 실행은 여러분의 코드가 맡고, 그 결과를 다시 모델에 전달해 최종 답변을 완성합니다. 요청과 응답이 여러 번 오가는 이 왕복 구조를 이해하는 것이 도구 연동의 출발점입니다.

8.2 좋은 도구 설명 작성과 오류 처리

모델이 도구를 언제·어떻게 쓸지는 대부분 도구 설명(description)의 품질이 좌우합니다. 설명에는 무엇을 하는 도구인지뿐 아니라, 언제 써야 하고 언제 쓰면 안 되는지, 각 인자가 무엇을 뜻하는지까지 구체적으로 담아야 합니다. 새로 온 담당자에게 업무를 인계하듯 쓰면 좋습니다. 오류 처리도 설계의 일부입니다. 인자가 잘못됐거나 외부 시스템이 응답하지 않을 때, 예외를 그대로 던지는 대신 무엇이 왜 실패했는지를 담은 결과를 모델에 돌려주면, 모델이 인자를 바로잡아 다시 시도하거나 사용자에게 상황을 설명할 수 있습니다. 도구는 클라이언트가 실행하는 것과 서버가 실행하는 것으로 나뉘며, 결제·삭제처럼 되돌리기 어려운 작업은 모델이 단독으로 실행하지 않고 담당자의 승인(approval)을 거치도록 설계합니다.

8.3 도구 세트 설계 — 몇 개를, 어떻게 나눌 것인가

도구는 많다고 좋은 것이 아닙니다. 비슷한 기능이 여러 도구로 흩어져 있으면 모델이 어느 것을 골라야 할지 헷갈리고, 잘못된 선택이 늘어납니다. 좋은 도구 세트는 각 도구의 역할이 겹치지 않고 경계가 뚜렷합니다. 하나의 도구가 너무 많은 일을 하도록 인자를 잔뜩 붙이기보다, 뚜렷한 목적 단위로 나누되 전체 개수는 모델이 감당할 만큼 절제하는 편이 낫습니다. 이름은 기능을 곧바로 드러내도록 짓고, 자주 함께 쓰이는 도구들은 인자 형식을 일관되게 맞추면 모델이 흐름을 예측하기 쉽습니다. 실전에서는 실제 대화 기록을 살펴 모델이 헷갈린 지점을 찾아 세트를 다듬는 과정을 반복합니다.

8.4 MCP 서버 개발 — 리소스·도구·프롬프트와 통신 방식

MCP(Model Context Protocol, 모델과 외부 도구·데이터를 잇는 표준 규약)는 도구 연동을 매번 새로 짜는 대신, 재사용 가능한 서버로 만들어 여러 클라이언트가 공유하게 합니다. MCP 서버는 세 가지를 제공할 수 있습니다. 도구(모델이 실행을 요청하는 동작), 리소스(모델이 읽어 들이는 자료), 프롬프트(반복 작업을 위해 미리 짜 둔 지시 틀)입니다. 클라이언트와 서버가 주고받는 방식은 크게 두 가지로, 같은 기기에서 표준 입출력(stdio)으로 붙이는 방식과 네트워크로 원격 서버에 붙이는 방식이 있습니다. 사내 위키 검색이나 로그 조회처럼 여러 팀이 공통으로 쓰는 기능을 한 번 MCP 서버로 만들어 두면, 여러 애플리케이션이 같은 서버를 붙여 재사용할 수 있습니다.

8.5 무엇으로 만들 것인가 — 기본 도구·커스텀 도구·스킬·MCP의 선택

같은 기능도 여러 방식으로 붙일 수 있고, 선택마다 나름의 득실이 있습니다. 기본 제공 도구(built-in tools, 웹 검색·코드 실행처럼 플랫폼이 미리 갖춘 도구)는 별도 구현 없이 바로 쓰지만 동작을 바꾸기는 어렵습니다. 커스텀 도구(custom tools)는 여러분의 시스템에 꼭 맞게 짜지만 직접 만들고 유지해야 합니다. 스킬(Skills, 특정 작업의 절차·자료를 묶어 모델에게 건네는 지침 꾸러미)은 코드 없이 반복 작업의 방법을 가르치는 데 강하고, MCP는 여러 애플리케이션이 같은 연동을 재사용해야 할 때 값이 큽니다. 한 번만 쓸 단순 조회라면 커스텀 도구로 충분하고, 조직 전체가 공유할 연동이라면 MCP로 만드는 편이 유리한 식으로, 재사용 범위와 유지 비용을 기준으로 고릅니다.

! 흔한 함정

• 도구 설명을 한 줄로만 적고 모델이 알아서 판단하리라 기대하는 것 — 설명이 부실하면 모델이 엉뚱한 도구를 고르거나 인자를 틀립니다. 설명에는 사용 조건과 금지 상황까지 담아야 합니다.
• 도구를 무조건 많이 붙이면 능력이 올라간다는 오해 — 역할이 겹치는 도구가 늘수록 선택 오류가 늘어 오히려 정확도가 떨어집니다. 경계가 뚜렷한 소수의 도구가 낫습니다.
• MCP를 모든 연동의 정답으로 여기는 것 — 한 서비스에서 한 번만 쓸 기능까지 MCP 서버로 만들면 유지 비용만 커집니다. 재사용 범위로 판단해야 합니다.
• 실패를 예외로 던져 흐름을 끊는 것 — 실패 사유를 결과로 돌려주지 않으면 모델이 스스로 회복하거나 사용자에게 상황을 설명할 기회를 잃습니다.