Claude Code Hooks MCP 연동 방법: 개발 워크플로 자동화하기

Claude Code Hooks와 MCP를 연동하면 이슈 관리, 코드 저장소, 데이터베이스와 모니터링 도구를 호출하는 시점에 자동 검증과 기록을 추가할 수 있습니다. 예를 들어 외부 시스템에 쓰기 전에 대상 프로젝트와 입력값을 검사하고, 성공 후 결과를 감사 로그에 남기며, 실패하면 복구 절차를 Claude에 전달하는 방식입니다. 다만 사후 Hook은 이미 실행된 외부 작업을 취소하지 못하므로 차단이 필요한 검사는 반드시 실행 전에 배치해야 합니다.

Claude Code Hooks와 MCP를 함께 쓰는 이유

MCP는 Claude Code에 외부 서비스의 도구와 데이터를 제공하고, Hooks는 특정 생명주기 이벤트에서 정해진 검사를 실행합니다. 두 기능을 결합하면 “외부 도구를 사용할 수 있다”에서 “정해진 조건과 감사 절차 안에서 사용한다”로 개발 워크플로를 확장할 수 있습니다.

• MCP 쓰기 도구 호출 전에 허용 범위와 입력값 검사
• 외부 작업 성공·실패 기록과 알림
• 파일 수정 후 MCP 기반 보안·품질 검사 실행
• 사용자 입력이 필요한 MCP elicitation 흐름 감사
• 실패 결과에 복구 문맥을 추가해 재시도 방향 제시

연동 방식은 두 가지다

첫 번째 방식은 외부 작업의 정책과 감사에, 두 번째는 자동화 파이프라인에 적합합니다. 하나의 이벤트에서 서로를 반복 호출해 무한 루프가 생기지 않도록 matcher와 도구 책임을 좁혀야 합니다.

사용 전 준비 사항

1. 공식 또는 내부 검토를 거친 MCP 서버를 연결합니다.
2. /mcp에서 연결 상태와 실제 도구 목록을 확인합니다.
3. 읽기·쓰기·삭제 도구와 필요한 인증 scope를 구분합니다.
4. /hooks에서 현재 프로젝트의 기존 Hook과 출처를 확인합니다.
5. 테스트 계정과 되돌릴 수 있는 데이터로 먼저 검증합니다.

MCP 연결부터 필요하다면 Claude Code MCP 서버 설정 가이드에서 HTTP·stdio, OAuth와 설정 범위를 먼저 확인하세요.

MCP 도구 이름 확인하기

Hook matcher에서 사용하는 MCP 도구 이름은 다음 구조입니다.

mcp__<server>__<tool>

예를 들어 github 서버의 search_repositories 도구는 mcp__github__search_repositories로 표시됩니다. 정확한 이름은 설치 문서에서 추정하지 말고 현재 세션의 /mcp에서 확인하세요.

MCP matcher 작성 규칙

서버 전체를 지정할 때 mcp__github만 쓰면 정확히 그 문자열인 도구를 찾으므로 일반적으로 일치하지 않습니다. 공식 문서는 서버 prefix 뒤에 .*를 붙이라고 안내합니다. matcher는 대소문자를 구분합니다.

Hook 설정 파일 위치

외부 명령이 포함된 프로젝트 Hook은 저장소를 신뢰하기 전 반드시 내용을 읽으세요. Hook은 사용자 권한으로 실행될 수 있습니다.

1단계: MCP 도구 호출을 기록하는 Hook

먼저 차단 없이 어떤 도구가 언제 호출되는지 테스트 로그를 남기면 matcher와 입력 구조를 확인하기 쉽습니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__.*",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/audit-mcp-call.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Hook command는 이벤트 JSON을 표준 입력으로 받습니다. audit script에서는 tool_name, 필요한 비민감 식별자와 시각만 기록하고 토큰, 프롬프트 전문, 소스코드와 고객 데이터는 제외하세요.

로그 스크립트에서 입력을 다루는 기준

• 표준 입력을 JSON parser로 검증합니다.
• 예상한 hook_event_name과 tool_name만 처리합니다.
• 도구별 허용 필드 목록을 두고 나머지는 폐기합니다.
• 로그 파일 권한, 보존 기간과 접근 책임자를 정합니다.
• stdout은 Hook 제어용 JSON을 위해 깨끗하게 유지합니다.
• 진단 메시지는 stderr 또는 승인된 감사 채널로 분리합니다.

2단계: PreToolUse로 외부 쓰기 검사하기

PreToolUse는 MCP 도구가 실제로 호출되기 전에 실행됩니다. command Hook은 입력을 검사한 뒤 Claude Code가 이해하는 JSON으로 allow, ask 또는 deny 결정을 반환하도록 구성할 수 있습니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__create_issue|mcp__github__update_issue",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/validate-github-write.sh",
            "timeout": 15
          }
        ]
      }
    ]
  }
}

validator에서는 허용 저장소, 제목·본문 길이, 민감정보 패턴과 사용자 승인 필요 여부를 검사할 수 있습니다. 실제 tool_input 필드명은 MCP 서버의 도구 스키마에 따라 다르므로 예제 값을 그대로 가정하지 마세요.

PreToolUse가 반환할 판단

Hook의 allow는 settings의 deny 또는 ask 규칙을 우회하지 못합니다. 반대로 차단 Hook은 더 넓은 permission mode에서도 작업을 막을 수 있으므로 정책을 강화하는 보조 장치로 사용할 수 있습니다.

PostToolUse는 차단용이 아니다

PostToolUse는 도구가 성공한 뒤 실행됩니다. 추가 문맥을 제공하거나 결과를 가공하고 감사 기록을 남길 수 있지만 이미 생성한 이슈, 전송한 메시지 또는 변경한 데이터는 되돌리지 못합니다. 외부 부작용을 막아야 한다면 검사를 PreToolUse에 둬야 합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "mcp__github__create_issue",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/record-created-issue.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

PostToolUseFailure로 실패 복구하기

PostToolUseFailure는 MCP 도구 호출이 오류 또는 실패 결과를 반환할 때 실행됩니다. 인증 만료, rate limit, 서버 연결과 입력 검증 실패를 분류해 로그와 안내를 제공할 수 있습니다.

• 같은 요청을 무제한 자동 재시도하지 않습니다.
• 인증 오류는 토큰을 출력하지 않고 재인증 절차만 안내합니다.
• rate limit은 대기 또는 수동 재시도 기준을 제시합니다.
• 부분 성공 가능성이 있으면 외부 시스템의 실제 상태를 먼저 조회합니다.
• 실패 알림에도 요청 전문과 비밀정보를 포함하지 않습니다.

3단계: Hook에서 MCP 도구 직접 호출하기

연결된 MCP 서버의 도구를 Hook handler로 직접 사용할 수 있습니다. 다음은 Claude가 파일을 Write 또는 Edit한 뒤 security_scan MCP 도구에 파일 경로를 전달하는 공식 구조 기반 예시입니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "my_server",
            "tool": "security_scan",
            "input": {
              "file_path": "${tool_input.file_path}"
            },
            "timeout": 60
          }
        ]
      }
    ]
  }
}

server와 tool에는 연결 설정과 MCP schema의 실제 이름을 사용합니다. input 역시 해당 도구가 요구하는 형식과 일치해야 합니다. 서버가 연결되기 전에 실행될 수 있는 시작 이벤트에서는 동작 순서를 별도로 확인하세요.

mcp_tool Hook 사용 시 주의점

• MCP 서버가 현재 세션에서 연결된 뒤에만 사용할 수 있습니다.
• 모든 matching Hook은 병렬 실행될 수 있으므로 실행 순서에 의존하지 않습니다.
• 동일 이벤트에서 호출한 MCP 도구를 다시 matching해 반복 실행하지 않게 합니다.
• 쓰기 도구보다 읽기·검사 도구를 우선 연결합니다.
• Hook timeout과 MCP 서버 자체 timeout을 함께 설계합니다.
• 검사 실패가 개발을 차단할지 경고만 할지 명확히 정합니다.

4단계: 코드 변경과 이슈 상태 연결하기

실전에서는 한 Hook에 모든 업무를 넣기보다 이벤트의 책임을 나눕니다.

1. Skill 또는 사용자 요청으로 대상 이슈와 변경 범위를 확인합니다.
2. MCP 읽기 도구로 이슈 요구사항을 가져옵니다.
3. Claude가 코드를 수정하면 PostToolUse Hook이 파일 검사를 실행합니다.
4. Stop 단계에서 프로젝트 테스트와 남은 변경을 검증합니다.
5. 사용자가 diff와 테스트 결과를 승인합니다.
6. 승인 후 MCP 쓰기 도구로 이슈 상태나 PR을 업데이트합니다.
7. PostToolUse Hook이 결과 ID와 성공 여부만 감사 기록에 남깁니다.

이슈 업데이트와 PR 생성 같은 외부 쓰기를 파일 수정 직후 자동 실행하면 불완전한 상태가 게시될 수 있습니다. 최종 사람 승인 뒤 호출되도록 워크플로를 구성하세요.

5단계: MCP Elicitation 이벤트 다루기

MCP 서버가 도구 호출 중 사용자 입력을 요구할 때 Elicitation과 ElicitationResult 이벤트가 발생할 수 있습니다. 이 이벤트는 matcher에서 도구 이름이 아니라 설정한 MCP 서버 이름을 기준으로 필터링합니다.

사용자에게 무엇을 요청하는지, 민감정보가 포함되는지, 응답이 외부 서버로 전송되는지를 확인하세요. 인증 비밀을 일반 텍스트 응답으로 입력하도록 설계하지 말고 공식 OAuth 또는 승인된 비밀 관리 흐름을 사용합니다.

권한 설정과 Hook을 함께 쓰는 방법

한 계층이 다른 계층을 대신하지 않습니다. permissions는 정적 경계를 제공하고 Hook은 도구 입력과 실행 결과를 바탕으로 동적인 정책을 보완합니다.

자동화 예시: 데이터베이스 조회 후 보고서 만들기

읽기 전용 분석에서도 안전 기준이 필요합니다. PreToolUse에서 허용된 schema와 SELECT 전용 도구인지 확인하고, 결과에는 행 수 제한과 개인정보 마스킹을 적용합니다. PostToolUse에서는 실제 데이터가 아니라 쿼리 식별자, 실행 상태와 소요 구간만 기록합니다.

보고서 파일이 생성되면 로컬 Hook으로 형식 검사와 민감정보 검사를 수행하고, 외부 게시 단계는 사용자 승인을 별도로 받습니다.

자동화 예시: PR 생성 워크플로

1. MCP 읽기 도구로 이슈 요구사항을 확인합니다.
2. 코드 수정마다 로컬 lint 또는 MCP 보안 검사를 실행합니다.
3. 테스트와 diff 요약을 생성합니다.
4. PreToolUse Hook이 PR 대상 저장소·base branch·본문을 검사합니다.
5. permission ask로 사용자 승인을 받습니다.
6. MCP PR 생성 도구를 실행합니다.
7. PostToolUse에서 PR 번호와 결과만 기록합니다.

Hook이 실행되지 않을 때

• /hooks에서 Hook이 예상 event와 source 아래 표시되는지 확인합니다.
• /mcp에서 정확한 서버·도구 이름을 확인합니다.
• matcher의 대소문자와 mcp__server__.* 형식을 점검합니다.
• PreToolUse와 PostToolUse 중 실제 필요한 시점을 확인합니다.
• command 경로, 실행 권한, PATH와 JSON 출력을 검사합니다.
• claude --debug에서 Hook과 MCP 연결 오류를 확인합니다.

mcp_tool Hook이 실패할 때

1. MCP 서버가 현재 세션에서 connected 상태인지 확인합니다.
2. server와 tool 값이 MCP schema의 실제 이름과 일치하는지 봅니다.
3. input 키와 값 유형이 도구 입력 schema와 같은지 검사합니다.
4. `${tool_input.file_path}` 같은 치환값이 해당 이벤트에 존재하는지 확인합니다.
5. 서버 로그에서 인증, timeout과 rate limit을 점검합니다.
6. 터미널에서 같은 MCP 도구를 수동 호출해 Hook과 서버 문제를 분리합니다.

무한 루프와 중복 실행 방지

Hook에서 호출한 MCP 도구가 다시 같은 matcher를 만족하면 반복 호출 가능성을 검토해야 합니다. 감시 대상 서버와 Hook이 호출하는 검사 서버를 분리하거나 특정 도구 이름만 정확히 매칭하세요. 세션·tool use ID를 이용해 이미 처리한 이벤트를 중복 기록하지 않는 방식도 고려할 수 있습니다.

여러 Hook이 같은 이벤트에 일치하면 병렬로 실행될 수 있습니다. 한 Hook의 출력이 다른 Hook의 선행 조건이라고 가정하지 말고, 순서가 필요하면 하나의 검증 스크립트 또는 서버 도구 안에서 명시적으로 처리합니다.

보안 체크리스트

• MCP 공급자, 서버 코드와 도메인을 검증했는가
• 읽기·쓰기·삭제 도구와 OAuth scope를 구분했는가
• 외부 쓰기 전 PreToolUse와 사용자 승인이 있는가
• Hook script가 표준 입력과 파일 경로를 안전하게 파싱하는가
• 로그에서 비밀값·프롬프트·고객 데이터를 제외했는가
• PostToolUse를 실행 전 차단 수단으로 오해하지 않았는가
• timeout, 실패 복구와 중복 실행 방지 기준이 있는가
• Hook·MCP 제거와 토큰 폐기 절차를 시험했는가

운영 전 테스트 순서

1. 테스트 프로젝트와 테스트 MCP 계정을 준비합니다.
2. 읽기 도구 하나에 감사 Hook만 적용합니다.
3. 허용·승인·차단 입력을 각각 재현합니다.
4. 성공, 서버 오류, 인증 만료와 timeout을 시험합니다.
5. 동시 Hook에서 중복 호출과 순서 의존성이 없는지 봅니다.
6. 외부 상태와 로컬 로그의 결과가 일치하는지 확인합니다.
7. 운영 도입 전 설정·script·권한을 독립 리뷰합니다.

Plugin으로 묶어 배포하기

검증된 Hooks와 MCP 구성을 여러 저장소에서 사용하려면 Plugin으로 포장할 수 있습니다. Plugin 루트의 hooks/hooks.json과 .mcp.json, 필요한 scripts를 함께 관리하고 포함 파일 경로는 ${CLAUDE_PLUGIN_ROOT}를 사용합니다.

설치 가능한 구조와 검증 명령은 Claude Code Plugin 만들기에서 확인하세요. Plugin 배포가 Hook script와 MCP 서버의 안전성을 자동 보장하지는 않습니다.

Hooks·MCP 통합 검증 기록표

외부 부작용이 없는 테스트 계정에서 허용·승인·차단·실패 흐름을 각각 실행하고 실제 외부 상태와 Hook 기록을 대조하세요.

편집부 결론

Claude Code Hooks MCP 연동의 핵심은 자동 호출의 수를 늘리는 것이 아니라 외부 도구의 실행 전 검사, 사람 승인, 성공·실패 기록과 복구 책임을 분리하는 것입니다. MCP 도구 이름을 /mcp에서 확인하고 쓰기는 PreToolUse, 후처리는 PostToolUse, 오류는 PostToolUseFailure에 배치하세요. Hook이 MCP 도구를 직접 호출할 때는 읽기·검사 도구부터 시작하고 반복 호출과 timeout을 반드시 시험해야 합니다.

이 글은 2026년 9월 6일 Anthropic 공식 문서를 분석해 작성했으며 특정 조직에서 Hooks·MCP 자동화 효과를 장기간 측정한 후기는 아닙니다. Hook event, 출력 schema와 MCP 도구는 업데이트될 수 있으므로 적용 전 현재 Claude Code 버전과 연결 서버의 공식 schema를 확인하세요.

공식 문서와 함께 읽을 글

Claude Code Hooks 공식 레퍼런스 보기

Claude Code Hooks 자동화 가이드 확인하기

Claude Code MCP 연결 공식 문서 보기

MCP 도구 권한 설정 확인하기

Claude Code Hooks 이벤트와 출력 구조 익히기

Claude Code MCP 서버와 인증 연결하기

Hooks·MCP 워크플로를 Plugin으로 배포하기

CLAUDE.md에 자동화 원칙과 완료 기준 설정하기

자주 묻는 질문

Claude Code Hook에서 MCP 도구를 구분하는 이름은 무엇인가요?

mcp__서버이름__도구이름 형식입니다. 현재 연결에서 정확한 이름은 /mcp로 확인하세요.

한 MCP 서버의 모든 도구를 Hook으로 감시하려면 어떻게 하나요?

mcp__server__.* 형식의 matcher를 사용합니다. .*가 없으면 서버 prefix 자체와 정확히 일치하는 도구만 찾으므로 일반적으로 동작하지 않습니다.

MCP 쓰기 작업을 실행 전에 막으려면 어떤 Hook을 써야 하나요?

PreToolUse를 사용해야 합니다. PostToolUse는 작업 성공 뒤 실행되므로 이미 발생한 외부 변경을 되돌릴 수 없습니다.

Hook에서 MCP 도구를 직접 호출할 수 있나요?

가능합니다. handler type을 mcp_tool로 지정하고 연결된 server, tool과 실제 schema에 맞는 input을 설정합니다.

Hook이 allow를 반환하면 permission deny도 우회하나요?

아닙니다. Hook의 allow는 settings의 deny 또는 ask 규칙을 우회하지 않습니다. 권한과 Hook을 함께 사용해 방어 계층을 구성해야 합니다.

PostToolUseFailure에서는 무엇을 처리하면 좋나요?

인증 만료, rate limit, 연결 오류와 잘못된 입력을 분류하고 재시도 여부와 복구 절차를 안내합니다. 비밀값이나 요청 전문은 로그에 남기지 마세요.

MCP Tool Hook이 실행되지 않는 이유는 무엇인가요?

서버 연결 상태, server·tool 이름, input schema, matcher와 치환 변수를 확인하세요. /mcp, /hooks와 debug 로그를 함께 보면 원인을 분리하기 쉽습니다.

Hooks와 MCP 설정을 팀에 배포하려면 어떻게 하나요?

프로젝트 settings와 .mcp.json을 리뷰해 공유하거나 Plugin의 hooks/hooks.json과 .mcp.json으로 묶을 수 있습니다. 비밀값은 저장소나 Plugin에 포함하지 마세요.