2026년 8월 18일 기준으로 Anthropic의 공식 모델 안내와 API 변경 기록을 먼저 확인해야 합니다. 클로드 소네트 5 API를 배포한다면 처음부터 MCP 도구를 여러 개 연결하지 말고, 읽기 전용 도구 하나와 위험이 낮은 실행 도구 하나로 호출 흐름을 검증해야 합니다. 이후 엄격한 도구 입력, 구조화된 최종 응답, 권한, 시간 제한, 멱등성, 사람 승인 절차를 차례로 추가하는 방식이 가장 안전합니다.
이 글을 볼 사람: 처음 클로드 소네트 5 API를 사용하는 백엔드 개발자라면 최소 도구 집합부터 시작하면 됩니다. 이미 Claude Tool Use 프로젝트를 운영 중인 팀은 엄격한 입력 모드와 출력 형식을 다시 점검해야 합니다. 원격으로 에이전트를 실행하려는 엔지니어는 프로세스와 로그 검증에 집중해야 합니다.
마지막 업데이트: 2026년 8월 18일. 모델 사용 가능 여부와 기능 범위는 Claude Sonnet 5 공식 발표, 모델 안내, Tool Use, 구조화 출력, MCP 문서를 기준으로 확인해야 합니다.
배포 전에 도구 경계를 먼저 줄입니다
에이전트가 검색, 파일 수정, 배포, 결제, 메시지 전송을 한 번에 수행하도록 만들면 오류 원인을 찾기 어렵습니다. 도구 설명이 겹치고, 모델이 선택할 수 있는 경로가 늘어나며, 권한 검사가 실행기 곳곳으로 흩어집니다.
처음에는 다음처럼 기능을 작게 나누십시오.
| 시작 도구 | 권장 역할 | 허용 범위 | 실패 시 처리 |
|---|---|---|---|
| 읽기 전용 도구 | 저장소 조회, 문서 검색 | 데이터 변경 없음 | 빈 결과를 반환하고 모델에 재질문 |
| 낮은 위험의 실행 도구 | 임시 파일 생성, 테스트 실행 | 별도 작업 공간만 사용 | 시간 초과 후 중단 |
| 고위험 도구 | 배포, 삭제, 외부 전송 | 명시적 승인 필요 | 실행 전 사람 승인 |
도구 이름은 동사와 대상이 분명해야 합니다. search_repository처럼 목적이 드러나는 이름을 사용하고, “필요할 때 사용” 같은 설명은 피해야 합니다. 입력 스키마에는 필수값, 허용된 열거값, 문자열 길이 제한, 기본값의 의미를 구분해서 적으십시오.
| 결정 항목 | 먼저 선택할 값 | 나중에 확장할 조건 |
|---|---|---|
| 도구 수 | 읽기 도구 1개와 저위험 실행 도구 1개 | 호출 기록과 오류 유형을 확인한 뒤 추가 |
| 권한 | 작업 공간 내부와 읽기 권한 | 승인 흐름과 감사 로그가 준비된 뒤 확대 |
| 입력 방식 | 필수값이 적고 평평한 스키마 | 중첩 구조가 실제 업무에 필요할 때만 복잡화 |
| 결과 방식 | 상태, 요약, 오류를 포함한 명시적 결과 | 여러 도구 결과를 최종 응답으로 조합 |
이 단계에서 비용도 확인해야 합니다. 모델 가격이나 지원 범위는 배포 시점에 바뀔 수 있으므로 공식 모델 페이지와 API 변경 기록에서 직접 확인하십시오. 문서에 없는 성능이나 고정 가격을 일반적인 수치처럼 사용하면 안 됩니다.
첫 단계: 클로드 소네트 5 API로 최소 호출 고리를 완성합니다
Claude Sonnet 5 API의 외부 도구 호출은 모델이 직접 서버 명령을 실행하는 방식이 아닙니다. 애플리케이션이 도구 정의를 전달하고, 모델이 tool_use 요청을 반환하면, 애플리케이션이 권한을 확인한 뒤 실제 함수를 실행합니다. 실행 결과를 tool_result로 다시 보내야 다음 답변이 완성됩니다. 공식 Tool Use 개요도 이 책임 분리를 전제로 설명합니다.
일반적인 흐름은 다음과 같습니다.
- 사용자 요청과 도구 정의를 애플리케이션에서 준비합니다.
- API 응답에서 텍스트와
tool_use블록을 분리합니다. - 도구 이름, 입력값, 호출 식별자를 검증합니다.
- 실행기가 권한과 중복 호출 여부를 검사합니다.
- 실제 함수를 실행하고 결과를 정규화합니다.
- 같은 대화 흐름에
tool_result를 넣어 다음 모델 응답을 요청합니다.
간단한 형태는 다음과 같습니다.
response = client.messages.create(
model="Claude Sonnet 5",
messages=messages,
tools=tools
)
for block in response.content:
if block.type == "tool_use":
call_id = block.id
name = block.name
arguments = validate_input(block.input)
result = executor.run(
name=name,
arguments=arguments,
idempotency_key=call_id
)
messages.append({"role": "assistant", "content": response.content})
messages.append({
"role": "user",
"content": [{
"type": "tool_result",
"tool_use_id": call_id,
"content": result
}]
})
실제 SDK의 필드명과 모델 식별자는 배포 시점의 공식 문서에 맞춰 확인해야 합니다. 중요한 점은 tool_use_id 또는 이에 해당하는 호출 식별자를 저장하는 것입니다. 식별자가 없으면 재시도 중 같은 작업이 두 번 실행되었는지 판별하기 어렵습니다.
Claude Tool Use 결과를 어떻게 안전하게 반환할까
Claude Tool Use의 결과는 단순한 문자열보다 애플리케이션이 처리할 수 있는 구조가 좋습니다. 성공과 실패를 같은 형식으로 관리하면 모델이 오류를 성공 결과로 오해하는 문제를 줄일 수 있습니다.
| 결과 유형 | 애플리케이션이 반환할 내용 | 모델에 기대하는 다음 행동 |
|---|---|---|
| 성공 | 상태, 핵심 데이터, 출처 식별자 | 사용자용 답변 작성 |
| 사용자 입력 오류 | 오류 유형, 수정 가능한 필드 | 필요한 값 재질문 |
| 권한 오류 | 거부 이유, 승인 필요 여부 | 작업 중단 또는 승인 요청 |
| 시간 초과 | 중단 상태, 재시도 가능 여부 | 재시도 또는 대체 경로 선택 |
| 내부 오류 | 공개 가능한 요약과 추적 식별자 | 사용자에게 실패 알림 |
도구 실행 결과에 내부 비밀값, 접근 토큰, 전체 로그를 그대로 넣지 마십시오. 모델이 볼 수 있는 결과와 운영자가 보는 로그를 분리해야 합니다. Tool Use 결과 처리 문서는 애플리케이션이 도구 실행과 결과 전달을 담당하는 구조를 다룹니다.
장점은 모델과 실제 실행 권한을 분리할 수 있다는 점입니다. 반대로 단점은 실행기, 대화 상태, 오류 변환 계층을 직접 관리해야 한다는 점입니다. 이 분리를 생략하고 모델 응답만 신뢰하면 업무 자동화가 아니라 통제되지 않은 명령 전달기가 됩니다.
두 번째 단계: 엄격한 도구 입력과 최종 구조를 분리합니다
Claude strict tool use 설정은 도구 입력을 검증하는 기능입니다. 반면 Structured Outputs는 모델의 최종 응답을 애플리케이션이 읽을 수 있는 구조로 맞추는 데 사용합니다. 둘을 같은 문제를 해결하는 옵션으로 취급하면 설계가 흔들립니다.
| 검증 대상 | 사용하는 기능 | 해결하는 문제 | 실패 분기 |
|---|---|---|---|
| 도구 호출 인자 | 엄격한 도구 입력 | 함수에 잘못된 타입이나 누락된 값 전달 | 입력 거부, 재질문 |
| 최종 모델 응답 | Structured Outputs | 후속 코드가 읽을 응답 형식 불일치 | 파싱 실패, 재요청 |
| 실행 권한 | 애플리케이션 검사 | 허용되지 않은 작업 실행 | 즉시 차단 |
| 결과 신뢰성 | 업무 규칙 검증 | 형식은 맞지만 내용이 부정확한 결과 | 보류, 사람 검토 |
Anthropic의 Structured Outputs 문서를 기준으로 최종 스키마를 설계하되, 스키마가 복잡할수록 예외 처리를 별도로 두십시오. 필수 필드가 지나치게 많거나 중첩 배열이 깊으면 정상적인 응답도 검증에서 탈락할 수 있습니다.
다음 세 가지 분기는 반드시 구현해야 합니다.
- 모델이 요청을 거부하면 거부 내용을 기록하고 도구 실행을 시작하지 않습니다.
- 응답이 길이 제한으로 중단되면 불완전한 JSON을 성공으로 저장하지 않습니다.
- 스키마 검증에 실패하면 원문을 업무 결과로 확정하지 말고 재요청 또는 사람 검토로 보냅니다.
구조화 출력은 안전한 실행을 대신하지 않습니다. 올바른 JSON 안에도 잘못된 파일 경로나 위험한 작업 요청이 들어갈 수 있기 때문입니다.
세 번째 단계: 시간 제한과 재시도 규칙을 실행기에 넣습니다
도구마다 시간 제한을 따로 두십시오. 저장소 조회와 외부 서비스 요청을 같은 제한으로 묶으면 짧은 작업이 느린 서비스 때문에 지연되거나, 반대로 긴 작업이 너무 일찍 종료됩니다. 시간 제한 값은 해당 서비스의 실제 운영 기록을 보고 정해야 하며, 근거 없는 고정 수치는 문서에 박아 넣지 않는 편이 낫습니다.
재시도는 모든 오류에 적용하면 안 됩니다.
- 연결 끊김이나 일시적인 서버 오류처럼 재실행해도 상태가 변하지 않는 작업만 자동 재시도합니다.
- 파일 삭제, 배포, 메시지 전송처럼 상태가 바뀌는 작업은 멱등 키를 먼저 확인합니다.
- 같은 호출 식별자와 같은 멱등 키가 다시 들어오면 이전 결과를 반환하고 함수를 재실행하지 않습니다.
- 고위험 작업은 실행기에서 승인 상태를 확인한 뒤에만 외부 효과를 발생시킵니다.
로그에는 요청 식별자, 호출 식별자, 도구 이름, 검증 결과, 시작과 종료 시각, 재시도 사유, 최종 상태를 남기십시오. 사용자 입력 전체와 비밀값을 무조건 기록하는 방식은 개인정보와 보안 문제를 만들 수 있으므로 마스킹 규칙이 필요합니다.
네 번째 단계: MCP는 공유가 필요할 때만 추가합니다
Claude API와 MCP를 항상 함께 사용해야 하는 것은 아닙니다. 한 애플리케이션이 소수의 내부 도구만 호출한다면 직접 도구 정의를 관리하는 편이 단순합니다. 여러 에이전트나 클라이언트가 같은 도구를 발견하고 재사용해야 할 때 MCP 계층을 검토하십시오.
MCP 연결 문서는 원격 도구 연결에 필요한 구조와 제한을 확인하는 기준이 됩니다. 연결 전에는 다음을 점검해야 합니다.
- 원격 연결이 끊겼을 때 에이전트가 안전하게 중단되는가
- 인증 토큰의 발급, 만료, 교체를 관리할 수 있는가
- 도구 목록이 바뀌었을 때 허용 목록과 스키마가 함께 갱신되는가
- 제3자 데이터가 어느 경계를 넘어가는지 추적할 수 있는가
- MCP 도구가 추가되었을 때 기존 권한 정책을 우회하지 않는가
MCP의 장점은 공유와 검색입니다. 단점은 네트워크, 인증, 도구 목록 변경이라는 운영 계층이 추가된다는 점입니다. 따라서 최소 호출 고리가 안정화된 뒤 MCP를 연결해야 원인 분석 범위를 통제할 수 있습니다.
다섯 번째 단계: 원격 맥 환경에서 실제 업무로 검증합니다
로컬에서 성공한 호출이 원격 환경에서도 안정적이라고 단정하지 마십시오. 원격 맥에서 에이전트를 운영한다면 다음 순서로 확인하십시오.
- 프로세스가 터미널 종료 후에도 유지되는지 확인합니다.
- 환경 변수를 셸 설정 파일에 평문으로 남기지 않고 비밀 저장 방식으로 주입합니다.
- API, MCP 서버, 업무 시스템으로 향하는 네트워크 경로를 각각 점검합니다.
- 표준 출력과 오류 로그를 분리하고 호출 식별자로 연결합니다.
- 키를 교체해도 기존 작업이 중복 실행되지 않는지 확인합니다.
- 새 버전 배포 후 실패하면 이전 실행기로 되돌릴 수 있는지 시험합니다.
- 검색, 코드 수정, 저위험 자동화처럼 실제 업무를 기록하며 검증합니다.
원격 개발 환경을 함께 검토한다면 원격 맥 지원 안내에서 운영 조건을 확인할 수 있습니다. 계약이나 사용 전에는 구성 주문 안내를 통해 필요한 환경과 작업 범위를 정리하십시오. 장기간 운영이 아니라 특정 프로젝트 기간에만 에이전트가 필요하다면 처음부터 전체 시스템을 고정하지 말고 작은 작업으로 인수 테스트를 진행하는 편이 좋습니다.
현재 방식과 원격 맥을 비교해 최종 운영 방식을 정합니다
개발자 개인 맥에서 계속 실행하면 초기 설정은 빠르지만, 절전과 재부팅이 작업을 끊을 수 있고 개인 개발 환경과 운영 환경이 섞입니다. 일반 서버나 컨테이너만 사용하는 방식은 백엔드 자동화에는 편리하지만, 맥 전용 빌드 도구나 실제 맥 운영 조건을 검증하기 어렵습니다. 여러 MCP 도구를 처음부터 붙이는 방식은 공유성은 높지만 권한과 장애 지점이 빠르게 늘어납니다.
따라서 장기적으로 고정된 고부하 작업이나 물리 장치 연결이 핵심이면 직접 장비를 운영하는 편이 맞습니다. 반대로 특정 기간의 코드 에이전트, 맥 전용 테스트, 원격 자동화 환경이 필요하다면 Macstripe의 맥 렌탈을 작은 실제 업무로 먼저 검증하는 선택이 더 현실적입니다. 프로세스 유지, 로그 수집, 키 교체, 회귀 테스트를 직접 확인한 뒤 사용 기간을 늘리면 불필요한 장비 구매와 초기 운영 부담을 함께 피할 수 있습니다.
