Agents SDK, 변환된 도구에 MCP 주석 노출

변환된 도구에서 MCP 메타데이터를 읽습니다

Python Agents SDK 0.24.0은 한국시간 2026년 10월 15일 공개됐습니다. MCP 도구를 SDK의 함수 도구로 변환할 때 서버가 제공한 주석을 읽을 수 있도록 FunctionTool.mcp_annotations 속성이 추가됩니다. 도구 설명을 다시 조회하지 않고 실행 훅에서 관련 메타데이터를 확인할 수 있는 변화입니다.

PR #5356은 readOnlyHint나 destructiveHint 같은 힌트를 예로 듭니다. 조회 성격인지, 파괴적 변경 가능성이 있는지 분류하는 데 참고할 수 있지만, 서버가 제공한 힌트라는 출처를 잊어서는 안 됩니다. 이름이나 주석만으로 실제 동작을 보장할 수는 없습니다.

주석은 실행 승인이 아닙니다

원문은 승인·실행 동작과 직렬화된 도구 출처가 바뀌지 않는다고 명시합니다. 따라서 읽기 전용 힌트가 있다는 이유로 기존 승인 절차를 건너뛰거나 위험한 작업을 자동 허용하도록 바꾸는 기능이 아닙니다. 앱의 권한 판단은 도구의 실제 기능과 사용자에게 허용받은 범위를 기준으로 유지해야 합니다.

이 구분은 외부 서버의 도구를 함께 쓰는 시스템에서 특히 중요합니다. 메타데이터는 검색과 표시를 돕는 자료이고, 실행 권한은 별도의 통제입니다. 이번 업데이트가 자동으로 안전한 도구만 골라 준다고 설명하면 범위를 과장하게 됩니다.

없는 값과 거짓 값을 구분합니다

속성은 변환할 때 보관한 주석의 사본을 반환합니다. MCP 주석이 없는 도구나 일반 함수 도구에는 None을 반환합니다. 사본을 받으므로 호출자가 결과를 수정해도 원래 검색 메타데이터를 바꾸는 방식으로 사용하지 않습니다.

생략된 힌트는 생략된 채 남습니다. 따라서 값이 없다는 사실을 거짓으로 단정해서 처리하지 말고 사용하는 MCP 버전의 기본 규칙을 적용해야 합니다. 해당 릴리스의 이전 안내도 이 점을 별도로 짚고 있습니다.

앱에서 활용한다면 표시부터 확인하세요

도구 목록에 ‘서버가 읽기 전용으로 표시함’처럼 출처가 드러나는 안내를 붙이거나, 운영 로그에서 실행 전후 메타데이터를 비교하는 방식으로 활용할 수 있습니다. 다만 이는 앱 설계 제안이며 SDK가 해당 UI를 자동으로 제공한다는 의미는 아닙니다.

시험은 주석이 있는 MCP 도구, 주석이 없는 MCP 도구, 일반 함수 도구를 나누어 진행해 보세요. 훅에서 None을 안전하게 처리하는지, 스트리밍 여부와 관계없이 기대한 정보가 보이는지 확인할 수 있습니다. PR은 MCP 1.19.0과 2.0.0에서 집중 테스트를 보고하지만, 이 글에서 이를 다시 실행한 것은 아닙니다. 핵심은 더 많은 정보를 얻되 그 정보를 권한으로 오해하지 않는 데 있습니다.

출처

• Agents SDK 0.24.0 공식 릴리스
• PR #5356 · 읽기 전용 주석 속성과 한계