2강 · 에이전트에게 여분의 손 쥐여주기

시즌 2의 2강에서 이렇게 말했어요.

초안을 읽으세요. 사실이 아닌 줄은 지우세요. 에이전트도 틀려요.

그때는 내가 의심하는 수밖에 없었어요. 에이전트에게는 확인할 방법이 없었거든요.

오늘 그 방법을 줍니다.

오늘 만들 것

에이전트가 모르는 걸 지어내는 대신 공식 문서를 직접 읽고 답하는 상태.

그리고 바깥 세계와 연결할 때 반드시 거치는 관문 하나를 손으로 통과해보기.

준비물

시즌 4의 1강을 마친 상태 (플러그인을 설치하고 지워봤어요)
my-page 폴더
35분
인터넷 연결

설치할 프로그램은 없어요. 터미널도 안 엽니다.

따라 하기

1. 먼저 지어내는 걸 봐요

/clear로 도마를 비우고, 잘 모르는 걸 물어보세요.

클로드 코드의 훅(hooks)이 뭐야? 어떤 파일에 어떻게 설정해?

답이 왔죠. 그 답을 어딘가에 적어두세요. 이따 비교할 거예요.

지금은 이게 맞는지 틀린지 알 수 없어요. 그럴듯해 보이거든요. 시즌 2에서 배운 그대로예요. 그럴듯한 게 제일 위험해요.

2. 문을 하나 내요

에이전트에게는 손이 있어요. 파일을 읽고, 고치고, 명령을 돌리죠. 그런데 그 손은 내 컴퓨터 안에서만 움직여요.

밖으로 나가는 문을 낼 수 있어요. 그 문을 MCP라고 불러요. 문 너머의 가게가 도구를 빌려주면, 에이전트는 그 도구로 여분의 일을 해요.

오늘 열 문은 공식 문서 가게예요. 클로드 코드의 진짜 문서를 그대로 읽어오는 곳이죠. 계정도, 설치도, 비밀번호도 필요 없어요.

3. 문을 다는 법

늘 하던 대로 시키면 돼요.

my-page 폴더 맨 위에 .mcp.json 파일을 만들어 줘. 내용은 이렇게:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    }
  }
}

만든 다음, 이 파일이 무슨 역할인지 설명해 줘.

파일 하나예요. 시즌 3에서 .claude/agents/reviewer.md를 만든 것과 똑같죠.

4. 관문을 통과하기

Claude Code를 껐다 켜세요.

물어봅니다. 이 프로젝트에 .mcp.json이 있는데, 여기 적힌 서버를 써도 되냐고요.

이게 중요해요. 파일을 만들었다고 바로 붙지 않아요. 내가 승인해야 붙어요.

승인하세요. 그리고 확인해요.

/mcp

연결 상태가 보여요. ✓ Connected 옆에 이 서버가 준 도구가 몇 개인지도 나오죠.

문이 열렸어요.

5. 똑같은 질문을 다시

이제 1번과 정확히 같은 질문을 하세요.

클로드 코드의 훅(hooks)이 뭐야? 어떤 파일에 어떻게 설정해?

이번엔 다르게 움직여요. 답하기 전에 도구를 부르는 게 화면에 보여요. 문 너머에서 문서를 가져오는 중이죠.

그리고 답이 옵니다.

6. 두 답을 나란히 놓기

1번에서 적어둔 답과 방금 답을 나란히 놓으세요.

파일 이름이 다를 수도 있고, 설정 방식이 다를 수도 있어요. 어느 쪽이 맞을까요.

문서를 읽고 온 쪽이에요.

이게 오늘의 순간이에요. 지어내던 것이 확인하는 것으로 바뀌었어요.

시즌 2에서는 /clear 후 "아까 뭐 했지?"를 물어 잊는 걸 확인했죠. 시즌 3에서는 위임 후 "그거 기억나?"를 물어 분리를 확인했고요. 오늘은 같은 질문을 두 번 던져 확인의 유무를 봤어요.

전부 같은 방법이에요. 전과 후를 비교하는 것.

7. 앞으로 이렇게 물어보세요

문이 열려 있으면, 이렇게 부탁할 수 있어요.

공식 문서를 확인해서 답해 줘. 확실하지 않으면 확실하지 않다고 말해 줘.

시즌 2의 4강에서 배운 "지어내지 말고 확인 필요라고 표시해"의 강력한 버전이에요. 그때는 부탁이었고, 지금은 확인할 수단이 있어요.

보너스 — 진짜 눈을 달고 싶다면 (선택)

시즌 2의 4강, "막혔을 때"에 이런 줄이 있었어요.

브라우저를 열 수 없다고 해요. 환경에 따라 못 여는 경우가 있어요.

에이전트에게 "네 눈으로 확인해"라고 시켰는데 눈이 없었던 거예요. 그 눈을 달 수 있어요. Playwright라는 MCP 서버가 브라우저를 대신 열어줘요. 내 페이지를 진짜로 띄워서 보고, 폰 크기로 줄여서 확인하고, 화면을 찍어와요.

다만 값이 들어요. 정직하게 말할게요.

Node.js를 따로 설치해야 해요. 지금까지 이 강의에서 한 번도 안 깔았던 거예요.
첫 실행 때 브라우저 파일을 수백 MB 내려받아요. 몇 분 걸려요.

시간이 넉넉하고 호기심이 있을 때만 하세요. 안 해도 이 강의는 완결돼요. 그리고 이 "값"이 다음 강의의 주제예요.

해보고 싶다면 에이전트에게 물어보세요.

Playwright MCP 서버를 붙이고 싶어. 나는 Node.js가 안 깔려 있고
터미널을 잘 몰라.

1. 지금 내 컴퓨터에 Node.js가 있는지 확인하는 방법
2. 없다면 설치하는 방법 (한국어로, 클릭할 곳까지)
3. 대략 얼마나 걸리고 용량은 얼마나 쓰는지

먼저 알려 줘. 설치는 내가 결정할게.

막혔을 때

승인 창이 안 떠요. 파일 위치를 확인하세요. my-page 폴더의 맨 위여야 해요. 하위 폴더에 있으면 못 찾아요. 그리고 Claude Code를 완전히 껐다 켰는지 확인하세요.

/mcp에 연결 실패로 나와요. 인터넷을 확인하고, 주소에 오타가 없는지 보세요. https://code.claude.com/docs/mcp예요. 그래도 안 되면 에이전트에게 ".mcp.json을 읽고 형식이 맞는지 확인해 줘"라고 시키세요. 쉼표 하나가 빠져도 안 붙어요.

두 답이 별로 안 달라요. 좋은 신호예요. 에이전트가 원래 알고 있던 거죠. 더 최근에 바뀐 기능을 물어보세요. 차이가 클수록 문이 하는 일이 뚜렷해져요.

도구를 부르는 게 안 보여요. 답이 너무 빨리 왔다면 문서를 안 읽고 답한 거예요. "공식 문서를 확인해서 답해 줘"라고 명시하세요.

.mcp.json을 깃허브에 올려도 되나요? 이 파일에는 주소만 적혀 있어서 괜찮아요. 다만 비밀번호나 API 키가 들어가는 서버라면 절대 안 돼요. 다음 강의에서 자세히 다뤄요.

마무리 체크

나가기 전에 하나씩 확인해요:

문을 달기 전에 물어보고, 그 답을 적어뒀어요
my-page/.mcp.json을 만들었어요
Claude Code를 다시 켰더니 승인을 물어봤어요
/mcp에서 연결된 걸 확인했어요
같은 질문을 다시 했더니 문서를 읽고 답했어요 ← 오늘의 순간
두 답을 나란히 비교했어요

다섯 번째가 오늘의 전부예요. 에이전트가 모르는 걸 확인할 수 있게 됐어요.

그런데 문을 열면 좋은 것만 들어올까요. 다음 강의에서 값을 잽니다.

더 깊이 파고 싶다면: API vs. MCP: 하나는 메뉴판이고, 하나는 여분의 손이에요

에이전트에게 여분의 손 쥐여주기