도구 권한 (Tool Permissions)

도구 권한(Tool Permissions)은 AI 에이전트가 파일 읽기, 명령 실행, 외부 서비스 호출 같은 작업을 수행할 때 적용하는 허용·승인·차단 규칙입니다. 모델에 어떤 도구가 보이는지와 실제 호출을 허용할지는 구분되며, 실행 환경이나 서비스 계정의 접근 권한도 따로 적용됩니다. 같은 도구라도 대상 파일, 명령, 승인 방식에 따라 실행 가능한 범위가 달라집니다.

도구 목록과 실행 허용의 차이

에이전트는 도구의 이름과 설명, 입력 형식을 보고 작업에 필요한 호출을 고릅니다. MCP 도구 명세의 2025년 6월 18일 판은 목록을 가져오는 tools/list와 호출을 보내는 tools/call을 구분합니다. 도구를 발견하는 단계와 그 도구로 실제 행동하는 단계가 나뉩니다. 목록에 보이는 도구를 호출하려 할 때에도 애플리케이션의 승인 규칙이나 서버의 접근 통제가 적용됩니다.

MCP 명세는 도구를 모델이 선택할 수 있도록 설계하면서도 특정 사용자 인터페이스를 강제하지 않습니다. 사용자가 호출을 거부할 수 있는 절차와 민감한 작업의 확인을 권고하고, 서버에는 입력 검증과 접근 통제를 요구합니다. 따라서 MCP를 지원한다는 사실만으로 모든 프로그램의 승인 화면이나 권한 정책이 같아지지는 않습니다. 도구 연결 방식과 그 도구를 허용하는 정책은 각각 확인하는 항목입니다.

애플리케이션이 호출을 허용해도 운영체제의 파일 권한이나 외부 API 계정의 권한이 새로 생기는 것은 아닙니다. 문서 조회 권한만 가진 계정으로 수정 도구를 실행하면, 호출이 승인되더라도 외부 서비스에서 수정을 거부할 수 있습니다. 실패 원인을 볼 때는 모델이 도구를 찾았는지, 애플리케이션이 실행을 막았는지, 호출을 받은 서비스가 접근을 거부했는지 구분합니다. 이 구분은 재승인과 계정 권한 점검 중 필요한 조치를 판단하는 데 쓰입니다.

허용·확인·차단 규칙의 우선순위

2026년 10월 11일 수집한 Claude Code 권한 문서는 allow, ask, deny를 구분합니다. allow는 지정한 도구를 수동 승인 없이 쓰도록 하고, ask는 해당 호출 때 확인을 요청하며, deny는 사용을 막습니다. 명시한 규칙끼리는 deny, ask, allow 순서로 평가합니다. 이 순서는 규칙에 적힌 대상이 더 구체적인지와 관계없이 적용됩니다.

넓은 차단 규칙과 좁은 허용 규칙이 겹치면 차단 규칙이 우선합니다. 문서의 Bash(aws *) 차단과 Bash(aws s3 ls) 허용 예시에서도, 뒤의 구체적인 허용이 앞의 차단에 예외를 만들지 못합니다. 확인 규칙과 허용 규칙이 함께 맞는 호출은 확인 대상입니다. 설정을 검토할 때는 원하는 명령에 허용 규칙이 있는지만 보지 않고, 같은 호출과 일치하는 차단·확인 규칙도 함께 읽습니다.

도구 전체를 막는 규칙과 일부 호출을 막는 규칙도 다르게 동작합니다. 이 문서에서 Bash처럼 도구 이름만 적은 차단은 모델에게 보이는 도구 목록에서 해당 도구를 제거합니다. Bash(rm *)처럼 범위를 둔 차단은 도구를 남겨 두고 일치하는 호출을 막습니다. 이런 규칙은 Claude Code 프로그램이 집행합니다. 프롬프트에 행동 지침을 적는 것만으로 프로그램의 허용 범위가 바뀌지는 않습니다.

설정 범위와 실행 환경의 제한

Claude Code 설정 문서는 설정 파일의 적용 범위를 구분합니다. ~/.claude/settings.json은 해당 컴퓨터에서 사용자의 여러 프로젝트에 적용하고, .claude/settings.json은 프로젝트의 공유 설정에 씁니다. .claude/settings.local.json은 같은 프로젝트에서 개인에게 적용할 설정을 담습니다. 조직이 배포하는 관리 설정도 있으므로, 한 파일의 규칙만 읽으면 실제로 적용되는 정책을 놓칠 수 있습니다.

권한 모드는 개별 규칙과 함께 도구 호출의 승인 방식을 정합니다. Claude Code의 권한 문서에 따르면 모드에 따라 사용자가 확인하는 호출의 범위나 자동 검토 방식이 달라집니다. 따라서 승인 질문이 나오지 않았다는 현상만으로 권한 검사를 건너뛰었다고 판단할 수는 없습니다. 미리 허용한 호출인지, 별도 승인이 필요 없는 동작인지, 어떤 모드가 적용됐는지를 함께 봅니다.

명령 문자열을 기준으로 한 규칙에는 표현 방식에 따른 한계도 있습니다. 같은 프로그램을 다른 경로로 부르거나 다른 실행 명령 안에 넣으면 원래 규칙과 일치하지 않을 수 있습니다. 문서도 명령 패턴을 프로그램 전체에 대한 보안 경계로 보지 않습니다. 파일이나 네트워크 접근을 실행 환경에서 제한하는 샌드박스, 서비스 계정의 접근 범위, 도구 승인 정책은 서로 다른 위치에서 작동하므로 각각의 제한을 구분해 점검합니다.