CCAR-F · CHAPTER 02 · D2 TOOL DESIGN & MCP INTEGRATION · 18%

에이전트가 할 수 있는 일의 경계 — 도구 설계와 MCP 연동

에이전트가 실제로 무엇을 할 수 있는지는 모델의 지능이 아니라 설계자가 붙여 준 도구가 결정합니다. 도구를 어떻게 정의하고, 실패를 어떻게 돌려주며, MCP로 어떤 서버를 연결하는지가 프로덕션 에이전트의 신뢰성을 좌우합니다. CCAR-F에서 이 도메인은 18% 비중으로, 개념 암기가 아니라 설계자의 실전 판단을 집중해서 검증합니다.

2.1 도구 설명이 곧 라우팅 신호다

에이전트가 어떤 도구를 부를지는 도구 설명(tool description, 각 도구에 붙는 자연어 사용 안내)을 읽고 판단합니다. 모델은 코드가 아니라 이 설명을 근거로 라우팅하므로, 두 도구의 설명이 겹치거나 모호하면 엉뚱한 도구를 부르는 오라우팅(misrouting)이 생깁니다. 좋은 설명은 입력 형식, 대표 질의 예시, 경계(무엇을 하지 않는지), 예외 상황을 함께 담습니다. 하나의 도구가 너무 많은 일을 겸하면 목적별로 쪼개고, 시스템 프롬프트의 표현이 도구 선택에 영향을 준다는 점까지 고려해 용어를 맞춥니다.

실무 예시

고객지원 에이전트를 설계하는 아키텍트가 '주문 조회'와 '배송 조회' 두 도구를 두었는데 설명이 모두 '고객 문의 처리'로 겹쳐 있으면, 배송 문의에 주문 조회가 호출되는 일이 잦습니다. 각 설명에 '결제와 주문 상태만', '운송장 위치와 도착 예정만'처럼 경계와 예시 질의를 명시하면 라우팅 정확도가 눈에 띄게 올라갑니다.

2.2 오류 응답도 설계 대상이다

도구 호출이 실패했을 때 무엇을 어떻게 돌려줄지도 설계의 일부입니다. MCP는 응답에 오류 표시(isError, 이 응답이 오류임을 알리는 플래그)를 붙여 오류를 종류별로 구분하도록 권합니다 — 잠시 뒤 다시 하면 되는 일시적(transient) 오류, 입력이 잘못된 검증(validation) 오류, 업무 규칙상 막힌 오류, 권한 부족 오류입니다. 재시도 가능 여부(isRetryable)와 운영자가 바로 이해할 설명을 함께 담으면 에이전트가 스스로 다음 행동을 고릅니다. 특히 '조회했으나 결과가 없음'과 '접근 자체가 실패함'은 전혀 다른 신호이므로 반드시 구분합니다.

실무 예시

멀티에이전트 리서치 도구 팀을 설계하는 테크리드라면, 검색 하위 에이전트(subagent, 특정 역할을 맡아 부분 작업을 처리하는 에이전트)가 일시적 오류를 만났을 때 곧바로 상위로 올리지 않고 정해진 횟수만큼 자체 복구를 시도한 뒤 실패하면 '재시도 불가'로 표시해 넘기게 합니다. 반대로 검색 결과가 0건인 것은 오류가 아니라 유효한 빈 결과이므로, 상위 에이전트가 '자료 없음'으로 정상 처리하도록 둡니다.

2.3 적은 도구, 역할에 맞춘 권한과 tool_choice

도구를 많이 붙일수록 에이전트가 유능해지는 것은 아닙니다. 선택지가 늘면 모델이 매번 더 헷갈려 선택 신뢰도가 떨어지므로, 역할마다 꼭 필요한 도구만 좁혀서 여는 편이 안전합니다. 또한 도구 선택 방식(tool_choice)을 상황에 맞게 지정할 수 있습니다 — 모델이 알아서 판단하는 auto, 반드시 도구 중 하나는 부르게 하는 any, 특정 도구 하나를 지정해 강제하는 방식입니다. 정해진 단계를 결정적으로 밟아야 하는 흐름에는 강제 지정이, 자유로운 대화에는 auto가 맞습니다.

실무 예시

코드리뷰 자동화를 설계하는 아키텍트가 한 에이전트에 조회·수정·배포 도구를 모두 열어 두면, 리뷰만 해야 할 단계에서 배포 도구가 잘못 호출될 위험이 있습니다. 리뷰 역할에는 읽기와 정적 분석 도구만 좁혀 열고, 반드시 요약 도구로 마무리해야 하는 마지막 단계에서는 그 도구를 강제로 지정해 흐름을 고정하는 식으로 권한과 선택 방식을 함께 설계합니다.

2.4 MCP 서버 연결과 접속 자격 관리

MCP 서버는 두 층위로 연결합니다 — 팀이 공유하는 프로젝트 설정(.mcp.json, 저장소에 함께 두어 협업자 모두가 같은 서버를 쓰는 설정)과 개인 설정(~/.claude.json)입니다. 접속 자격 같은 민감한 값은 파일에 직접 적지 않고 환경 변수 확장(environment variable expansion, 설정에는 변수 이름만 두고 실제 값은 실행 환경에서 채우는 방식)으로 주입합니다. 실행 시 등록된 서버가 한꺼번에 탐색되므로, 필요 이상 많이 붙이면 앞 절에서 말한 도구 과잉 문제로 이어집니다. 도구를 부르지 않고 참고하는 MCP 자원(resource, 참고 자료 목록)을 활용하면 탐색용 호출도 줄일 수 있습니다.

실무 예시

사내 문서 검색을 붙이는 설계자라면, 이미 검증된 공개 MCP 서버로 충분한 기능은 그것을 쓰고 사내 규칙이 얽힌 부분만 직접 만드는 편이 유지 비용이 적습니다. 접속 키는 .mcp.json에 값을 적지 않고 환경 변수 이름만 두어 저장소에 자격이 노출되지 않게 하고, 자주 참고하는 스키마 문서는 자원 목록으로 제공해 매번 탐색 도구를 부르지 않고 바로 읽게 만듭니다.

2.5 기본 제공 도구의 쓰임과 선택 기준

Claude Code 같은 환경은 파일과 셸을 다루는 기본 도구를 제공합니다 — 파일을 읽는 Read, 새로 만드는 Write, 부분을 고치는 Edit, 명령을 실행하는 Bash, 내용을 찾는 Grep, 경로를 찾는 Glob입니다. 설계자는 각 도구의 역할을 구분해 골라야 합니다. 예를 들어 Edit는 바꿀 구간이 파일 안에서 유일하게 일치해야 동작하므로, 같은 문장이 여러 번 나와 특정이 안 될 때는 Read로 전체를 확인한 뒤 Write로 다시 쓰는 방식으로 우회합니다. 큰 코드베이스는 한 번에 파악하려 들지 말고 Grep과 Glob으로 좁혀 가며 조금씩 이해하도록 설계합니다.

실무 예시

레거시 코드베이스를 다루는 에이전트를 설계하는 테크리드라면, 먼저 Glob으로 관련 파일 후보를 좁히고 Grep으로 함수 정의를 찾은 다음 필요한 파일만 Read하도록 흐름을 짭니다. 설정 파일에서 반복되는 키 하나만 바꿔야 하는데 같은 값이 여러 줄에 있어 Edit가 구간을 특정하지 못하면, 파일을 통째로 Read해 위치를 확인한 뒤 Write로 정확히 고쳐 넣습니다.

! 흔한 함정

도구를 많이 붙일수록 에이전트가 더 유능해진다고 여기는 것 — 실제로는 선택지가 늘수록 라우팅 신뢰도가 떨어지므로, 역할별로 좁히는 편이 낫습니다.
실패를 오류 메시지 하나로 뭉뚱그리는 것 — 다시 하면 되는 일시적 오류와 입력이 틀린 오류, 권한 문제를 구분하지 않으면 에이전트가 엉뚱한 복구를 시도합니다.
'결과 없음'을 오류로 처리하는 것 — 접근 실패와 유효한 빈 결과를 섞으면 정상 상황을 오류로 오인해 불필요한 재시도나 중단이 생깁니다.
접속 자격을 설정 파일에 값째로 적어 저장소에 노출하는 것 — 환경 변수 이름만 두고 실제 값은 실행 환경에서 주입해야 합니다.

HANDS-ON 이 도메인은 byteforce learn의 3-mcp 코스와 곧바로 이어집니다 — MCP 서버를 직접 연결하고 도구와 자원을 정의해 본 뒤 이 챕터의 설계 판단을 읽으면 개념이 훨씬 단단하게 자리 잡습니다. learn으로 →

Q 확인 퀴즈

CH 02 · 01/5

한 고객지원 에이전트를 설계하는 아키텍트가 '주문 조회'와 '배송 조회' 두 도구를 두었습니다. 두 도구의 설명이 모두 '고객 문의를 처리합니다'로 되어 있어, 배송 문의에 자꾸 주문 조회 도구가 호출됩니다.

이 오라우팅(misrouting, 엉뚱한 도구가 호출되는 현상)을 줄이는 가장 적절한 조치는 무엇입니까?