6차시. 환각을 막는 도구 — MCP

이 차시에서 준비할 것

선행5차시 완료

필수 설치Python — 공통 준비 3-9절
그다음 MCP 서버 설치가이드 (5분)

선택 준비법제처 인증키 — 무료, 5분 (3절에서 안내)

코드쓰지 않습니다. 읽고, 붙이고, AI에게 시킵니다

이 차시에서 처음 나오는 말

환각 (할루시네이션): AI가 사실이 아닌 것을 사실처럼 말하는 것. 모른다고 하지 않고 그럴듯하게 만들어 냅니다.
도구 (Tool): AI가 실제로 실행하는 코드. 계산하거나, 외부에서 자료를 가져옵니다.
MCP: 도구를 AI에 붙이는 공개 표준. 하나 만들면 Claude Code·Codex 등이 같이 씁니다.
결정론: 같은 입력이면 언제나 같은 출력. 코드의 성질이고, 모델에는 없는 성질입니다.

이 차시에서 배우는 것

환각이 어떻게 생기고 왜 안 걸리는지 두 종류로 확인한다 — 계산과 사실
도구를 붙여 지어내지 못하게 막는다 (계산 도구 · 법령 조회 도구)
내 업무에 필요한 도구를 AI에게 시켜 직접 만든다

1. 문제 — 두 종류의 환각

1-1. 계산 환각 — 그럴듯한 숫자

Windows · PowerShell

cd C:\harness-edu\tool\mcp-server; claude

macOS · 터미널

cd ~/harness-edu/tool/mcp-server && claude

Claude Code 입력창에 붙여넣기

data/production.csv 를 보고 B라인 2026-07-14 의 OEE를 알려줘.
OEE는 가동률 × 성능 × 품질이야. 계산 과정도 보여줘.

관찰: 답은 그럴듯합니다. 그런데 이 숫자가 맞는지 어떻게 확인하죠? 계산 과정을 사람이 다시 검산해야 한다면 AI를 쓴 이득이 사라집니다. 소수점 아래가 회차마다 미묘하게 다르기도 합니다.

1-2. 사실 환각 — 있지도 않은 조문

더 위험한 쪽입니다. 숫자는 이상하면 눈에 띄지만, 법 조문·규정·인용은 틀려도 그럴듯합니다.

Claude Code 입력창에 붙여넣기

근로기준법에서 임산부의 야간·휴일 근로 제한을 정한 조문이 몇 조인지 알려주고,
그 조문 원문을 그대로 인용해줘. 몇 항까지 있는지도 알려줘.

관찰: 조문 번호와 그럴듯한 문장이 나옵니다. 맞을 수도 있고 틀릴 수도 있습니다. 문제는 — 읽는 사람이 구분할 수 없다는 것입니다. 조문 번호가 하나 어긋나거나, 개정 전 내용이거나, 아예 없는 항이 섞여 있어도 문장은 매끄럽습니다.

보고서에 이대로 들어가면 어떻게 될까요. 이것이 사실 환각이 계산 환각보다 위험한 이유입니다.

두 환각의 공통점 — AI가 모른다고 말하지 않는다는 것입니다. 해결책도 같습니다. 지어낼 여지를 없애고 사실을 가져오는 창구를 붙입니다. 그 창구가 Tool 이고, 붙이는 표준이 MCP 입니다.

2. 개념 — Skill은 설명서, Tool은 창구

축	무엇인가	형태	같은 질문에 같은 답?	배운 차시
Agent	역할·경계 (누가)	지시문 파일	—	4·5차시
Skill	지식·절차 (무엇을·어떻게)	AI가 읽는 문서	✗ 모델이 해석	2·5차시
Tool	실행·조회 (무엇으로)	실제 코드 / 외부 시스템	✓ 항상 같음	이번 차시

판단 규칙
정의가 고정돼 늘 같은 답이 나와야 하는 일 (계산 · 조회 · 외부 시스템) → Tool
맥락에 따라 달라지는 판단 (무엇이 중요한가 · 어떤 톤으로) → Skill

2차시에서 "OEE는 가동률 × 성능 × 품질" 을 용어집(Skill)에 적어 두기만 하면 모델이 그 설명을 읽고 암산합니다. 법 조문도 마찬가지로 기억에서 꺼냅니다. Tool은 계산을 실행하고, 원문을 가져옵니다.

3. 실습 A — 계산 도구 붙이기

설치가이드를 마쳤다면 등록은 끝나 있습니다. 확인부터 합니다.

Claude Code 입력창에 붙여넣기

/mcp

예상 결과: production-metrics 가 connected. 도구 3개(list_records · compute_oee · defect_ppm)가 보입니다. 안 보이면 설치가이드 3-5절부터.

Claude Code 입력창에 붙여넣기

production-metrics 도구로 2026-07-14 A·B·C 세 라인의 OEE를 구하고,
가장 낮은 라인의 병목이 무엇인지, 개선하려면 어디를 봐야 하는지 정리해줘.

예상 결과: 도구를 세 번 호출해 값을 받아 온 뒤 해석만 얹습니다. B라인은 69.8%, 병목은 가동률 — 몇 번을 돌려도 같습니다.

도구가 돌려주는 것

{ "availability": 0.75, "performance": 0.9444, "quality": 0.9853,
  "oee": 0.6979, "oee_pct": "69.8%", "bottleneck": "가동률" }

1-1절의 암산 답과 비교해 보세요. 정확한 산수는 도구, 해석은 모델 이라는 분업이 눈에 보입니다.

4. 실습 B — 법령 조회 도구 붙이기 (korean-law-mcp)

계산은 막았습니다. 이번엔 사실 차례입니다. 법제처 국가법령정보센터의 공식 데이터를 AI가 직접 조회하게 붙입니다.

법률 담당이 아니어도 해볼 가치가 있습니다. "AI가 기억으로 답하던 것을 원문 조회로 바꾼다" 는 구조는 사내 규정·제품 사양·계약 조건 등 모든 ‘틀리면 안 되는 사실’ 에 똑같이 적용됩니다.

4-1. 법제처 인증키 받기 (무료 · 5분)

공공 API라 본인 인증키(OC)가 필요합니다. 브라우저에서 아래 주소로 들어가 로그인 → OPEN API 신청 → API인증키관리 에서 키를 복사합니다.

주소창에 붙여넣기

https://open.law.go.kr/LSO/openApi/guideList.do

인증키 보안 — 발급받은 키는 본인만 씁니다.

메모장·단톡방·문서에 적지 않습니다. 발급 화면에서 복사해 설치 화면에 바로 붙여넣으세요
다시 볼 일이 있으면 법제처 사이트 → API인증키관리에서 언제든 확인됩니다
화면 공유·녹화 중에는 입력하지 않습니다

4-2. 플러그인으로 설치하기

Claude Code 입력창에서 두 줄이면 됩니다. 설치가이드에서 해 본 플러그인 설치와 같은 방식입니다.

설치 범위(scope)를 묻는 화면이 또 나옵니다 — 이번에도 User 입니다. 과정 통틀어 세 번째이자 마지막입니다.

선택지	뜻	이 과정에서
User scope 사용자 범위	내 계정의 모든 폴더에서 쓸 수 있게 설치	✅ 이것을 선택
Project scope 프로젝트 범위	이 폴더에서만. 설정이 폴더에 기록돼 팀원과 공유됨	❌ 다른 폴더로 옮기면 안 됩니다
Local scope 로컬 범위	이 폴더에서만, 나만	❌ 같은 이유로 부적합

지금까지 범위를 물은 세 곳 — ① Harness·Skills 플러그인(설치가이드 3-8절) ② MCP 서버 --scope user(설치가이드 3-5절) ③ 지금 이 법령 플러그인. 전부 User 입니다. 이유는 하나 — 이 과정은 폴더를 계속 옮겨 다니기 때문입니다.

Claude Code 입력창에 붙여넣기 ①

/plugin marketplace add chrisryugj/korean-law-mcp

Claude Code 입력창에 붙여넣기 ② — 설치 범위는 User

/plugin install korean-law@korean-law-marketplace

예상 결과: 설치 중 법제처 API 키를 입력하라는 프롬프트가 뜹니다. 4-1에서 복사한 값을 붙여넣으면 민감정보로 안전하게 저장됩니다. 설치 후 Run /reload-plugins to activate. 가 나오면 그 명령을 한 번 실행하세요.

인증키 발급이 늦어지면 4-3·4-4절을 읽고 넘어가도 됩니다. 관찰 포인트만 이해하면 이 차시의 핵심은 전달됩니다. 나중에 키를 받고 나서 돌아와 해보세요.

4-3. 같은 질문을 다시 — 이번엔 원문으로

Claude Code 입력창에 붙여넣기

근로기준법 제70조 원문을 법제처에서 찾아서 그대로 보여줘.
그리고 임산부·연소자 야간근로 제한이 몇 항에 있는지 알려줘.

예상 결과: 도구 호출 표시가 뜨고 법제처 원문이 그대로 나옵니다. 1-2절의 답과 비교해 보세요 — 조문 번호나 내용이 달랐다면 그것이 환각이었습니다.

4-4. 진짜 쓸모 — 인용 검증

이 도구의 값어치는 조회보다 검증에 있습니다. AI가 쓴 문서에 존재하지 않는 조문이 섞여 있을 때 하나씩 대조해 잡아냅니다.

Claude Code 입력창에 붙여넣기

아래 문단에 인용된 법 조문이 실제로 존재하는지, 내용이 맞는지
법제처 원문과 하나씩 대조해서 표로 알려줘. 틀린 것은 무엇이 틀렸는지 적어줘.

"근로기준법 제53조에 따라 연장근로는 주 12시간을 초과할 수 없으며,
같은 법 제9999조는 위반 시 3년 이하의 징역을 규정한다.
또한 민법 제750조는 불법행위 손해배상 책임을 정하고 있다."

예상 결과: 제9999조 는 존재하지 않는 조문으로 잡힙니다. 나머지 두 개는 원문과 대조해 맞고 틀림이 표시됩니다.

여기서 배울 것 — 4차시의 검증자 분리가 도구로 구현된 모습입니다. 사람이 하던 "하나씩 대조" 를 도구가 합니다. 잘 쓰는 것과 틀린 것을 잡는 것은 다른 일이고, 후자는 기억이 아니라 원본 대조로만 됩니다.

주의 — 이 도구도 조회 결과를 요약·가공합니다. 법적 효력이 필요한 판단에는 반드시 국가법령정보센터 원문을 직접 확인하세요. 도구는 환각을 줄이지 최종 책임을 대신하지 않습니다.

5. 실습 C — 도구 직접 만들기

마지막입니다. 없는 도구는 만들면 됩니다. 코드는 AI가 씁니다 — 우리는 무엇을 만들지 정합니다.

5-1. 먼저 구조만 봅니다

Claude Code 입력창에 붙여넣기 (tool/mcp-server 폴더에서)

server.py 를 열어서, 코드를 모르는 사람도 이해할 수 있게
"함수 하나가 어떻게 도구가 되는지" 세 가지만 짚어줘.

핵심은 이게 전부입니다

@mcp.tool()                                  ← 이 한 줄이 "이건 도구다" 표시
def compute_oee(line: str, date: str) -> dict:
    """지정한 라인·날짜의 OEE를 계산한다."""   ← 이 설명을 모델이 읽고 언제 쓸지 판단
    ...
    return { "oee_pct": "69.8%", ... }        ← 돌려준 값이 그대로 모델에게 전달

세 가지	뜻
표시 한 줄	`@mcp.tool()` 을 붙인 함수 하나 = 도구 하나
설명문	모델은 이 문장을 읽고 언제 부를지 판단합니다 — 2차시의 "좋은 설명서" 원리와 같습니다
입력·출력	필요한 값과 돌려줄 값이 정해져 있습니다 — 이것이 계약입니다

5-2. 도구 하나 추가하기

지금 도구 3개로는 답할 수 없는 질문이 있습니다 — "이번 주 B라인 OEE가 오르는 추세인가?" 날짜별 추이를 돌려주는 도구를 추가합니다.

Claude Code 입력창에 붙여넣기

server.py 에 weekly_trend 도구를 추가해줘.

- 입력: line (라인 이름)
- 하는 일: 그 라인의 날짜별 OEE를 계산해서 시간순으로 돌려준다
- 출력: 날짜별 OEE 목록 + 첫날 대비 마지막날 증감 + 추세(상승/하락/보합)
- 값만 주지 말고 어느 축(가동률·성능·품질)이 추세를 이끌었는지도 함께

기존 도구 3개는 건드리지 말고, 설명문(docstring)은 모델이 언제 부를지
판단할 수 있게 구체적으로 써줘.

예상 결과: server.py 에 함수가 하나 늘어납니다. 승인을 물으면 내용을 보고 승인하세요. 코드를 이해하지 못해도 됩니다 — 다음 단계에서 실제로 도는지로 확인합니다.

5-3. 다시 읽히고 호출하기

서버 파일이 바뀌었으니 Claude Code를 껐다 켜야 새 도구가 보입니다.

Claude Code 입력창에

/exit

터미널에서 다시 실행

claude

Claude Code 입력창에 붙여넣기

B라인 OEE가 오르는 추세인지 떨어지는 추세인지 알려줘. 원인 축도 함께.

예상 결과: 도구 이름을 말하지 않았는데 AI가 weekly_trend 를 알아서 호출합니다. 설명문을 읽고 "이 질문에 쓸 도구" 라고 판단한 것입니다 — 설명문이 곧 트리거입니다.

도구가 안 보이면: /mcp 로 연결 상태를 확인하세요. failed 면 새 코드에 오류가 있는 것입니다. "방금 추가한 코드에 오류가 있는지 확인하고 고쳐줘" 라고 그대로 시키면 됩니다.

6. 정리 — 언제 도구로 만드나

이런 일	Skill / Tool	왜
정해진 공식으로 계산	Tool	늘 같은 답이 나와야 함
법령·규정 원문 인용	Tool	기억이 아니라 원본에서 가져와야 함
사내 시스템 조회	Tool	실제 데이터가 필요함
보고서 톤 다듬기	Skill	맥락에 따라 달라지는 판단
무엇을 먼저 보고할지	Skill	사람의 우선순위가 들어감

Tool은 특별한 기술이 아닙니다. 팀이 엑셀·매크로로 하던 계산, 매번 사이트에서 찾아보던 조회 — 그것을 함수로 옮기고 표시 한 줄을 붙이면 사내 도구가 됩니다. 그리고 그 코드는 AI가 씁니다. 실무자가 할 일은 무엇이 틀리면 안 되는지 아는 것입니다.

7. 스스로 점검

계산 환각과 사실 환각을 각각 직접 봤다
왜 사실 환각이 더 위험한지 설명할 수 있다
/mcp 에서 도구가 connected 인 것을 확인했다
(선택) 법령 도구로 존재하지 않는 조문을 잡아냈다
도구를 하나 추가하고 이름을 말하지 않아도 호출되는 것을 봤다
내 업무에서 Tool로 만들 것을 하나 이상 떠올렸다

흔한 실패와 대처

증상	왜 생기나	대처
`/mcp` 에 안 보임	재시작 안 함 또는 local 스코프	`/exit` 후 재실행. 그래도 없으면 `--scope user` 로 재등록
`No module named 'mcp.server.fastmcp'`	MCP 패키지 2.x 설치됨	설치가이드 문제 해결 ①
법령 조회가 인증 오류	인증키(OC)가 잘못 입력됨	법제처 → API인증키관리에서 키를 다시 확인하고 플러그인을 재설치
인증키 입력 프롬프트가 안 뜸	플러그인 버전 차이	law-edu 설치가이드의 다른 연결 방법 참고
새로 만든 도구가 안 보임	Claude Code 재시작 안 함	5-3절대로 `/exit` 후 다시 실행
`python` 을 못 찾음	Python 미설치 또는 설치 후 창을 새로 열지 않음	공통 준비 3-9절 → 설치 후 터미널을 새로 열기
"개발자가 없는데요"	직접 만들어야 한다고 생각	코드는 AI가 씁니다. 정의(입력·출력·규칙)만 정하면 됩니다

8. 다음 차시

조각이 다 모였습니다 — 규칙(2차시) · 팀(4차시) · 스펙(5차시) · 도구(6차시). 마지막 차시에서 이것을 내 업무 하나에 맞춰 한 벌로 조립하고, 남이 돌려도 되는지 검증합니다.

7차시내 업무에 이식하기조립 → 검증 → 운영. 하네스 한 벌을 완성합니다. 준비1차시 업무 지도 다시 보기7차시는 1차시 업무 카드로 시작합니다.