2026. 04. 22. · CK · 본문 보강 2026. 09. 08.

MCP 도구를 설계할 때: 검색·권한·실패 처리를 먼저 정한다

읽기 전 요약

MCP는 도구를 연결하는 규약이며 도구 선택, 권한 승인, 실패 복구까지 자동으로 해결하지는 않는다. 블로그 자동화를 설계하는 관점에서 읽기 전용 도구의 입력·출력과 검사 사례를 제안한다. 점진적 도구 검색과 코드 기반 호출은 사용하는 플랫폼의 지원을 확인해야 하며, MCP를 연결했다는 이유만으로 적용됐다고 가정하지 않는다.

블로그를 자동화하려면 글 읽기, 초안 검수, 배포 상태 확인 같은 작업을 도구로 연결할 수 있다. MCP를 붙이면 에이전트가 같은 인터페이스로 접근할 길이 생긴다. 그 다음에는 개발자가 정할 일이 남는다. 어떤 글을 읽게 할지, 결과에 무엇을 포함할지, 배포 버튼을 누를 권한은 누가 승인할지다.

기존 원고는 특정 발표의 다운로드 수와 미래 기능을 소개했다. 원본 영상과 발언 시점을 확인하지 못한 수치는 이번 수정에서 사용하지 않는다. 아래 설명은 공개 MCP 사양과 Anthropic의 도구 사용 문서에 근거한다. 블로그용 도구는 현재 운영 기능이라고 주장하는 내용이 아닌 설계 예시다.

프로토콜의 도구 발견과 모델의 도구 검색을 나눠 본다

MCP Tools 사양에는 서버가 도구 목록을 제공하고 클라이언트가 도구를 호출하는 인터페이스가 있다. 도구는 이름, 설명, 입력 스키마 등을 제공한다. 목록을 조회할 수 있다는 사실만으로 모델이 필요한 도구만 골라 문맥에 넣거나 모든 설명을 읽는 비용을 자동으로 줄이는 것은 아니다. MCP Tools 사양

도구가 많은 환경에서 필요한 정의를 나중에 불러오는 전략은 유용한 선택지다. Anthropic은 Tool Search Tool과 지연 로딩을 설명하며, 코드 실행 안에서 도구를 조합하는 Programmatic Tool Calling도 소개한다. 이는 해당 플랫폼의 기능과 설정을 확인할 내용이다. MCP 서버를 하나 만들었다는 이유로 이런 실행 방식이 어느 클라이언트에서나 적용된다고 설명해서는 안 된다. Anthropic 도구 사용 안내

작은 블로그에 읽기 도구 세 개만 있다면 별도의 검색 단계가 오히려 작업을 늘릴 수 있다. 목록 전체를 노출하는 방식부터 측정하고, 비슷한 도구가 많아 선택 오류가 생길 때 검색을 추가하는 순서가 낫겠다. 도구가 많다는 사실보다 실제 잘못 고른 횟수와 입력 문맥 크기를 보겠다.

도구 검색을 넣을 때도 실패 경로가 필요하다. 검색 결과가 없으면 사용자가 요청한 작업을 할 수 없다고 알려야 한다. 없는 도구 이름을 만들어 호출하거나 이름이 비슷한 쓰기 도구를 대신 실행하면 안 된다. 설명문에는 대상 데이터와 부작용을 구별할 정보를 남긴다.

읽기 전용 블로그 도구는 질문에서 거꾸로 설계한다

내가 먼저 시험할 질문은 “최근 공개한 글은 무엇인가”, “이 글의 본문과 출처는 무엇인가”, “최근 배포가 성공했는가”다. 이 질문들을 처리하려면 임의 셸 실행이나 전체 DB 조회 권한까지 줄 필요는 없다. 블로그 운영자가 승인한 범위에서 공개 상태를 읽는 도구부터 만들겠다.

예시 도구입력반환할 정보반환하지 않을 정보
list_public_posts날짜 범위, 페이지 크기제목, slug, 공개일, 다음 페이지 표시초안·개인 기록
get_public_post허용된 slug본문, 요약, 출처, 내용 버전환경 변수·내부 메모
get_deployment_status허용된 배포 식별자상태, 검사 시점, 공개 URL토큰·비공개 빌드 로그

이 표는 이 글에서 제안하는 인터페이스다. 실제 MCP 표준 도구 이름이나 이미 구현한 API가 아니다. 입력에서 임의 파일 경로를 받기보다 공개 글의 slug를 받으면 읽을 범위를 제한하기 쉽다. 그래도 서버에서는 slug 검증과 공개 여부 검사를 수행해야 한다. 모델이 올바른 인자를 보낼 것이라는 기대는 접근 통제가 아니다.

목록 결과에는 페이지 크기 상한을 둔다. “전체 글을 보여줘”라는 요청에 모든 본문을 한 번에 반환하면 필요하지 않은 텍스트까지 문맥에 쌓인다. 목록으로 대상을 찾고 필요한 글만 읽게 하는 구조가 단순하다. 부분 결과라면 truncated 또는 다음 페이지 표시처럼 누락 여부를 클라이언트가 구별할 값을 제안한다.

같은 도구 설명에서도 날짜의 의미를 적어야 한다. 원래 작성일, 대표 글 공개일, 실질 수정일은 다를 수 있다. “최근 글”을 요청했을 때 어느 날짜로 정렬했는지 반환하면 사용자와 에이전트가 같은 기준으로 결과를 읽을 수 있다. 기존 원고를 보강했다는 이유로 최초 작성일을 오늘로 바꾸는 방식은 피한다.

타입과 설명만으로 권한 경계를 만들 수는 없다

MCP 사양은 구조화한 출력과 입력 스키마를 설명하고 서버의 입력 검증·접근 제어를 요구한다. 스키마는 요청 형식을 확인하는 데 도움이 되지만 특정 사용자가 그 자료를 읽을 권한까지 대신 판단하지는 않는다. 서버가 인증된 주체와 대상 자료의 권한을 대조해야 한다. MCP 도구 보안 고려사항

도구에 읽기 전용이라는 힌트를 붙여도 실제 구현이 파일을 쓰면 안전하지 않다. 반대로 쓰기 도구의 이름이 친절해도 메일 발송이나 운영 DB 변경 같은 부작용은 남는다. 읽기 서버와 쓰기 서버의 자격 증명을 나누고, 처음 연결할 때는 필요한 읽기 권한만 부여하는 설계를 택하겠다.

토큰은 그 토큰을 사용하도록 발급받은 대상에서 검증한다. 다른 서비스용 토큰을 확인 없이 전달하거나 서버가 사용자 대신 넓은 권한을 행사하게 하면 신뢰 경계가 흐려진다. 외부 연결을 허용할 때는 MCP 보안 권고와 해당 인증 공급자의 설정을 함께 검토해야 한다. MCP 보안 모범 사례

외부 글의 본문도 신뢰하지 않는 입력이다. 블로그 글을 읽는 도구가 반환한 텍스트에 다른 파일 전송이나 설정 변경을 지시하는 문장이 있어도 새 사용자 요청으로 실행하지 않는다. 공개 자료 조회와 운영 설정 변경을 같은 광범위한 자격 증명으로 묶지 않으면 이런 오류의 피해 범위를 줄일 수 있다.

블로그 공개, 뉴스레터 발송, 일정 등록을 한 상위 작업으로 묶을 때는 승인도 나눠야 한다. “초안을 정리해줘”라는 요청을 발송 승인으로 해석하지 않는다. 최종 제목, 대상 URL, 수신 범위를 확인한 뒤 부작용이 있는 작업을 실행한다. 환경 변수 하나를 켰다고 오작동 가능성이 사라지지는 않는다.

코드로 여러 도구를 묶을 때는 부분 실패를 결과에 남긴다

코드 기반 호출은 반복 조회와 데이터 집계에 쓸 수 있다. 예를 들어 공개 글 목록을 읽고 출처 링크가 없는 글만 추리는 작업에서는 각 본문 전체를 모델에 넘기지 않고 필요한 필드만 집계할 수 있다. 단, 호출을 묶어도 네트워크 오류와 권한 문제는 남는다. 각 작업의 결과를 확인하는 코드를 작성해야 한다.

아래는 처리 규칙을 설명하는 의사코드다. 특정 SDK 문법이나 실행 가능한 제품 예제로 제시하지 않는다. 실제 구현에서는 사용하는 SDK의 오류 형식과 타임아웃을 맞춰야 한다.

목록 조회에 실패하면 작업 전체를 실패로 기록한다.
목록이 비어 있으면 성공한 빈 결과로 기록한다.
각 글을 읽고 성공, 권한 거부, 찾을 수 없음, 시간 초과를 구분한다.
실패한 글을 제외한 결과라면 부분 결과라고 표시한다.
모든 글을 확인했을 때만 전체 점검 완료라고 답한다.

일시적인 읽기 오류는 제한된 횟수로 재시도할 수 있다. 권한 거부를 우회하거나 더 넓은 계정으로 자동 전환하지 않는다. 쓰기 작업을 추가한다면 중복 요청을 어떻게 구별할지도 설계해야 한다. 응답이 끊겼다는 이유로 같은 메일을 다시 보내면 사용자는 두 통을 받는다.

배포도 비슷하다. 배포 요청 수락, 빌드 완료, 운영 주소의 새 본문 확인은 서로 다른 상태다. 도구 응답에서 이 상태를 합쳐 “성공”이라고 하면 다음 단계가 잘못 출발할 수 있다. 글을 DB에 공개하는 절차가 있다면 운영 배포 검증이 실패한 경우 공개 단계로 넘어가지 않도록 별도 조건을 둔다.

도입 효과는 토큰과 오작동을 함께 잰다

첫 시험에서는 같은 질문을 기존 수동 흐름과 도구 흐름에 각각 제공하겠다. 작업 완료까지 걸린 시간, 입력·출력 토큰, 잘못 고른 도구 수, 사람이 수정한 횟수를 기록한다. 가격표와 캐시 과금이 다르면 토큰 수와 실제 비용도 구분한다. 다른 회사의 내부 실험에서 줄인 비율을 내 시스템의 예상 절감률로 사용하지 않는다.

정상 사례 외에 빈 목록, 삭제된 slug, 허용 범위 밖의 글, 긴 본문, 오래된 배포 상태를 시험한다. 잘못된 입력을 받았을 때 에이전트가 이유를 설명하고 멈추는지도 본다. 읽기 전용 구성에서는 파일·DB·메시지 상태가 바뀌지 않았음을 확인해야 한다.

이 기준을 통과한 뒤에야 초안 작성 같은 제한된 쓰기 작업을 추가하겠다. 공개와 발송은 그보다 뒤의 단계다. 자동화에 맡기는 범위를 넓히는 근거는 도구 수가 늘었다는 사실보다, 실패했을 때 무엇을 했고 무엇을 하지 않았는지 확인할 수 있다는 점이어야 한다.

참고자료

MCP 도구를 설계할 때: 검색·권한·실패 처리를 먼저 정한다 · iamlazyck