Claude Code 사용자 정의 도구 모드: Claude에게 새 도구를

Claude Code 사용자 정의 도구 모드는 턴 중에 Claude가 호출할 수 있는 새 도구를 제공합니다. 프로젝트 전용 검색, 이슈 트래커 조회, 코드베이스에서 중요한 값을 계산하는 계산기 같은 것들입니다. 도구는 모드 안에 JavaScript로 작성되어 Claude Code에서 실행되므로, 별도의 서버 프로세스를 시작할 필요가 없습니다.

Claude Code 사용자 정의 도구 모드는 도구를 어떻게 추가하나요?#

모드는 이름, Claude가 읽을 설명, 그리고 받을 입력을 지정해 $.tool.register(...)를 호출합니다. Claude가 도구를 쓰기로 결정하면 그 호출은 기본 제공 도구와 마찬가지로 tool.call 이벤트를 거치며, 모드는 { result }를 반환해 답합니다. $.tool.list()는 사용 가능한 도구를 보여 주고, $.tool.call()을 사용하면 모드가 직접 도구를 호출할 수 있습니다.

여기서 중요한 이벤트가 두 가지 더 있습니다. tool.describe는 도구 설명이 처음 Claude에 전송될 때 발생하며, 모드는 설명 텍스트를 다시 쓰거나 도구를 지연 로드로 표시해 필요할 때까지 컨텍스트를 차지하지 않게 할 수 있습니다. agent.offer와 $.agent.register는 서브에이전트 유형에 대해 같은 역할을 합니다. $.tool과 $.agent 메서드는 API 레퍼런스에 문서화되어 있습니다.

설치하기 전에 무엇을 확인해야 하나요?#

도구 모드에는 명령어/도구 추가가 표시됩니다. 나머지 배지는 도구가 무엇에 접근할 수 있는지 알려 줍니다. 웹 API를 조회하는 도구에는 네트워크, 파일을 검색하는 도구에는 파일 읽기, 린터를 실행하는 도구에는 명령어 실행이 표시됩니다. 도구를 언제 호출할지는 Claude가 결정하므로, 이런 기능은 사용자가 요청할 때만이 아니라 어느 턴에서든 쓰일 수 있습니다. 따라서 Claude가 직접 접근 권한을 가진 것처럼 검토하십시오.

오류를 어떻게 보고하는지도 확인하십시오. 좋은 도구는 예외를 던지는 대신 명확한 오류 메시지를 결과로 반환하여 Claude가 복구할 수 있게 합니다.

도구 모드와 MCP 서버는 어떻게 다른가요?#

MCP 서버는 Claude에게 도구를 제공하는 표준 방식이며 여러 클라이언트에서 작동합니다. 도구 모드는 범위가 더 좁아 Claude Code에서만 작동하지만, 플러그인 외에 별도의 설치 단계가 필요 없고, 세션과 함께 시작되며, 모드의 다른 부분과 상태를 공유할 수 있습니다. 예를 들어 도구가 몇 번 사용되었는지 보여 주는 상태 표시줄과 상태를 함께 쓸 수 있습니다.