Azure MCP Server 3.0이 2026-10-12에 GA(General Availability)가 되었습니다. Claude Code와 같은 클라이언트에 연결할 때, 도구 정의가 컨텍스트를 얼마나 사용하는지, --read-only 등의 옵션으로 줄일 수 있는지 알고 싶은 분들을 위한 글입니다.
시작 옵션 7가지의 도구 수와 토큰 수, 3.0에서 추가된 namespace(도구를 서비스 단위로 그룹화한 단위), 그리고 --read-only와 --disable-proxy-tools(외부 소스에서 중계되는 도구를 제외하는 옵션)의 효과, 3.0에서 변경된 미지 파라미터 처리 방식에 대해 알 수 있습니다. 핵심 숫자는 모든 namespace의 도구를 개별적으로 출력하는 --mode all이 504개 도구, 약 14.3만 토큰인 반면, 기본값이 69개 도구, 약 1.4만 토큰이라는 차이입니다.
모든 도구를 로드하면 약 14만 토큰, 기본값은 약 1.4만
npx -y @azure/[email protected] server start
에 시작 옵션을 변경하며 연결하고, tools/list의 건수와 토큰 수를 측정했습니다. --mode all의 건수는 Azure 로그인 상태에 따라 달라집니다. 다음 표의 값은 az login을 완료했고 azd를 설치하지 않은 환경에서, 미로그인일 경우 foundry와 arm이 가져와지지 않아 504건이 407건으로 변합니다.
| 시작 옵션 | 도구 수 | 토큰 수 |
|---|
--mode single | 1 | 298 |
| 기본값 (namespace) | 69 | 13,825 |
기본값 + --read-only | 67 | 13,399 |
기본값 + --disable-proxy-tools | 65 | 12,915 |
--mode all | 504 | 143,110 |
--mode all + --read-only | 267 | 68,816 |
--mode all + --disable-proxy-tools | 404 | 115,869 |
起動オプション別のトークン数。single 298、既定 13,825、all 143,110（対数軸）
위 표의 실측값으로 만든 그림입니다(화면 캡처가 아닙니다)
--mode all은 504개 도구, 약 14.3만 토큰입니다. 도구 정의를 처음에 한 번에 로드하는 클라이언트에서는 무언가를 요청하기 전에 컨텍스트의 약 7할이 채워집니다. 기본값 namespace의 경우 약 1.4만, single의 경우 298토큰으로 충분합니다.
다만 Claude Code는 기본적으로 MCP 도구가 필요할 때까지 로드하지 않습니다(Claude Code의 MCP 문서에
그렇다면 504개에서 267개로 줄어들고, 토큰도 약 절반(143,110개에서 68,816개)이 됩니다. 기본 모드에서는 목록의 개수가 거의 변하지 않으며, 효과가 나타나는 것은 각 라우터(기본 모드에서 namespace별로 제공되는 도구) 내부의 작업입니다.
외부를 경유하는 도구를 제외합니다.
\--help에는 서버의 registry.json에 설정된 외부 소스에서 중계되는 도구를 비활성화한다고 되어 있습니다. 기본 모드에서는 다음 4개가 줄어들었습니다.
arm
azd
documentation
foundry
all
모드에서는, 줄어든 100개 항목의 내역은 foundry가 80개, arm이 17개, microsoft_*가 3개였습니다. arm에는 Resource Graph의 쿼리나 비용 조회, 배포 생성 등이 포함되며, microsoft_*에는 Learn 검색이 포함됩니다. 이 옵션을 추가하면 이러한 기능들을 사용할 수 없게 됩니다.
알지 못하는 파라미터는 거부됨
3.0의 파괴적 변경 사항 중 하나로 '알지 못하는 파라미터를 가진 도구 호출은 명시적으로 거부된다'는 내용이 있습니다. group_list에 존재하지 않는 인수를 전달하여 확인해 보았습니다.
{"name":"group_list","arguments":{"bogus":"x"}}
돌아온 것은 isError: true와 다음 메시지였습니다.
Request rejected due to unknown arguments: bogus
릴리스 노트에서는 많은 도구에서 사용되지 않는 --subscription이나 --resource-group 파라미터가 삭제되었습니다. 2.x 버전을 위해 작성된 저장된 프롬프트나 스크립트가 이들을 전달하고 있다면, 3.0에서는 오류가 발생할 가능성이 있습니다.
시도해 볼 순서
- 먼저
--mode single 또는 기본 모드로 작동하는지 확인합니다.
- 사용할 namespace가 정해져 있다면
--namespace로 범위를 좁힙니다.
arm, azd, foundry, Learn 검색을 사용하지 않는다면 --disable-proxy-tools를 추가합니다(사용한다면 제외하지 않습니다).- 쓰기를 피하고 싶다면
--read-only를 추가합니다. 기본 모드에서는 개수가 변하지 않는 점에 주의하세요.
도구 정의를 처음에 모두 로드하는 클라이언트의 경우, --mode all로 전부 연결하는 것은 추천하지 않습니다.
참고
Discussion
