MCP 도구 노출 범위와 스키마 품질을 설계하는 방법

연결보다 어려워지는 것은 도구 선택이다

Claude Code의 MCP v2.1은 PostgreSQL이나 Redis 같은 내부 시스템을 몇 줄의 설정으로 연결하는 구성을 제시한다. MCP 서버가 제공하는 프롬프트는 슬래시 명령 형태로 발견될 수 있어, 개별 API마다 통합 코드를 작성하던 부담도 설정 수준으로 줄어든다.

이때 남는 문제는 연결 가능성이 아니다. 어떤 도구를 얼마나 드러낼지, 모델이 유사한 도구 가운데 올바른 대상을 고르게 하려면 어떤 설명과 스키마가 필요한지가 설계의 중심이 된다.

도구 목록이 커지면 모델은 잘못된 도구를 선택하기 쉬워지고, 도구 정의 자체도 컨텍스트를 차지한다. 특히 데이터베이스 연결에서는 반환 결과가 통제되지 않을 경우 단 한 번의 조회로 컨텍스트가 소진될 수 있다. 사용 가능한 서버를 모두 연결하는 방식은 정확도 하락과 비용 증가를 함께 부를 수 있다.

운영 체계는 서버별 최소 도구 집합, 설명과 스키마의 품질, 맥락별 노출, 결과 크기 제한, 호출 계측을 함께 다뤄야 한다.

서버 경계에서 권한과 도구를 나눈다

한 MCP 서버가 제공하는 도구는 업무 단위로 묶되 최소 집합으로 유지하는 편이 낫다. 기능을 지나치게 잘게 쪼개면 도구 수가 빠르게 늘어나고, 도구 선택은 더 어려워진다.

읽기와 쓰기 기능을 서로 다른 서버로 분리하는 구성도 검토할 수 있다. 이 경우 권한 분리와 노출 통제를 서버 단위에서 수행할 수 있다. 도구 이름에는 서버 접두어를 포함해 이름 충돌을 줄여야 한다. 이름 충돌은 모델의 오선택으로 바로 이어질 수 있다.

도구 설명은 기능만 적는 문서가 아니다. 무엇을 하는지와 함께 언제 사용하면 안 되는지도 포함해야 유사한 도구를 구분할 수 있다. 파라미터에는 형식, 범위, 예시를 명시한다. 스키마가 느슨하면 잘못된 인자로 호출한 뒤 오류 응답을 해석하는 왕복이 늘어난다.

설명 문구 역시 형상관리 대상이다. 문구의 작은 차이가 도구 선택 정확도를 크게 바꿀 수 있기 때문이다.

필요한 도구만 작업 맥락에 맞춰 꺼낸다

전체 도구를 항상 노출하기보다 작업 맥락에 맞는 부분 집합만 활성화할 수 있다. 노출 도구 수와 선택 정확도는 반비례 경향을 보이므로, 작업 유형별로 노출 규칙을 명시해 두는 편이 좋다. 규칙이 없으면 운영은 결국 전량 노출로 돌아가기 쉽다.

결과 크기도 인터페이스 계약에 포함해야 한다. 행 수와 바이트에 상한을 두고, 초과하면 요약 또는 절단 표시를 붙여 반환한다. 절단 사실을 조용히 감추면 모델은 전체 결과를 확인했다고 잘못 판단할 수 있다.

오류는 구조화해 반환하고 재시도 가능 여부를 표시한다. 자유 텍스트 오류는 모델의 무한 재시도를 유발할 수 있다. 권한 부족과 인자 오류는 대응 방식이 다르므로 같은 형태로 돌려주면 개선 지점을 찾기 어렵다.

⤢✕

호출 기록은 도구 설계의 피드백 루프다

도구별 호출 횟수, 성공률, 평균 결과 크기, 오선택으로 의심되는 사례를 수집해야 문제가 되는 도구를 식별할 수 있다. 호출 직후 사용자가 되돌리거나 다른 도구를 다시 호출했다면, 이를 오선택 신호로 집계할 수 있다.

대표 작업 시나리오에서 올바른 도구가 선택되는 비율을 측정하면 도구를 추가하기 전후의 변화를 비교할 수 있다. 오선택 사례는 유형별로 분류해 설명과 스키마 개선의 우선순위를 정한다.

서버와 클라이언트 사이의 버전 호환도 기록한다. 서버 버전과 클라이언트 요구 버전이 맞지 않으면 경고해야 하며, 도구 스키마 변경이 조용히 반영되면 실패 원인을 찾기 어렵다. 폐기 예정 도구에는 표시를 남기고 대체 도구를 안내한다. 스키마 변경 시에는 버전을 올리고 병행 지원 기간을 두며, 사용처를 추적한 뒤 도구를 제거한다.

표준 연계와 직접 통합이 만드는 운영 차이

구분	표준 MCP 연계	개별 API 직접 통합
구현 부담	설정 수준	통합 코드 작성
클라이언트 이식성	높음	낮음
세밀한 제어	서버 구현에 종속	자유
도구 수 관리	별도 통제 필요	자연히 제한
버전 관리	서버·클라이언트 이중	단일
감사 용이성	표준 로그 활용	자체 구현

MCP는 한 번 구축한 서버를 여러 클라이언트에서 재사용하고, 설정과 표준 로그·발견 메커니즘을 활용할 수 있다. 반면 세밀한 호출 제어는 서버 구현 범위에 묶이며, 도구 수 증가를 별도로 통제하지 않으면 선택 정확도가 낮아진다.

직접 통합은 호출 흐름을 완전히 제어하고 필요한 기능만 만들기 때문에 도구 폭증이 구조적으로 발생하지 않는다. 하지만 클라이언트마다 통합 코드를 다시 작성해야 하며 이식성도 없다. 다수 도구와 다수 클라이언트를 다루는 환경에서는 MCP의 재사용 이득이 크고, 단일 애플리케이션에 특화된 고빈도 경로에서는 직접 통합이 여전히 유리하다.

전량 노출은 구현이 단순하고 사용 가능한 도구를 한눈에 파악할 수 있으며 예상하지 못한 조합을 활용할 수 있다. 대신 도구 정의가 컨텍스트를 잠식하고 유사 도구 간 오선택이 늘어난다. 선별 노출은 컨텍스트 효율과 선택 정확도를 개선하지만, 노출 규칙을 유지해야 하며 규칙이 잘못되면 필요한 도구가 없어 작업이 막힌다. 도구 수가 수십 개를 넘어가면 선별 노출의 이득이 규칙 유지 비용을 넘어서므로 인벤토리 규모를 기준으로 전환 시점을 정할 수 있다.

다수의 소형 서버는 권한을 서버 단위로 분리하고 장애 확산을 막으며 소유 조직을 나누기 쉽다. 프로세스와 설정이 늘고 서버 간 일관성을 유지하기 어려운 점은 부담이다. 단일 대형 서버는 운영과 명명·설명 일관성 유지가 단순하지만, 권한이 한곳에 모여 최소 권한 원칙이 무너지고 장애 영향 범위도 넓어진다. 데이터 민감도가 다른 시스템에서는 소형 서버 분리가 권한 통제의 기본 수단이므로 운영 부담은 자동화로 흡수하고 분리는 유지하는 방향이 안전하다.

연결 편의성에 거버넌스를 붙인다

사내 MCP 서버는 어떤 서버가 어떤 도구를 제공하며 누가 소유하는지 인벤토리로 관리해야 한다. 연결이 쉬워질수록 그림자 연결도 늘어나기 때문이다. 서버가 접근하는 데이터 범위와 권한 수준도 함께 기록한다.

도구는 기본적으로 비노출로 두고 필요한 대상만 명시적으로 허용하는 방식이 적합하다. 허용 목록 방식은 차단 목록보다 안전하다. 노출 승인 시에는 사용 목적과 예상 호출 빈도를 기록하고, 사용되지 않는 도구는 주기적으로 회수한다.

도구 설명은 코드 리뷰 대상에 포함한다. 특히 유사 도구를 설명만으로 구분할 수 있는지 리뷰어가 확인해야 한다. 데이터베이스 직접 연결처럼 권한이 강한 서버에는 별도 승인 경로를 두고, 도구 호출 로그는 감사 대상으로 보존한다. 어떤 도구가 어떤 데이터에 접근했는지 설명할 수 있어야 한다.

표준화는 조합 가능성을 높이지만, 표준을 채택했다는 사실이 불필요한 연결 확대의 근거가 될 수는 없다. 표준은 비용을 낮추는 수단이며, 도입 이후의 핵심 작업은 인터페이스 품질 관리로 옮겨간다.

도구 설명과 스키마는 사람이 아니라 모델이 소비하는 인터페이스 문서다. 명세 품질이 동작 품질과 강하게 결합한다는 점에서 API 문서보다 더 직접적인 영향을 준다. 오류 응답의 규격화와 재시도 가능 여부 표시는 인터페이스 계약의 일부이며, 무한 재시도를 막는 장치가 된다. 결과 크기 제한과 절단 표시는 소비 측 자원이 유한한 통합 환경의 백프레셔 설계에 해당한다.

연결 표준화 이후의 경쟁 축

MCP 연결 표준화가 진전될수록 경쟁은 연결 가능성보다 도구 설계 품질과 선택 정확도로 이동하는 흐름을 보인다. 필요 시점의 도구 노출은 클라이언트 기본 기능으로 편입되고, 노출 규칙 관리는 운영 항목으로 정착하는 방향이다.

도구 호출 로그의 감사 요건이 강화되면서 데이터 접근 추적은 MCP 서버의 필수 기능으로 요구되는 흐름이다. 사내 MCP 서버 인벤토리와 승인 절차 역시 그림자 연결을 통제하는 표준 거버넌스 수단으로 자리 잡는 방향이다.