무엇을 어디에 담을 것인가
규칙과 능력을 주는 방법은 하나가 아닙니다. 항상 알아야 할 사실, 외부 시스템 연결, 가끔 필요한 절차, 반드시 지켜야 할 통제는 각각 다른 곳에 담아야 합니다.
| 도구 | 담는 것 | 로드 시점 | 강제력 |
|---|---|---|---|
| CLAUDE.md | 항상 알아야 할 사실 | 세션 시작 시 항상 | 맥락 — 확률적 |
| MCP | 외부 시스템 연결 | 서버가 붙어 있는 동안 | 도구 — 실제 동작 |
| 스킬 | 절차적 작업 | 호출될 때만 | 맥락 — 확률적 |
| 훅 | 반드시 지킬 통제 | 도구 호출 시 자동 | 코드 — 100% 확정 |
외부 도구를 Claude에 붙이기
MCP(Model Context Protocol)는 Claude를 외부 시스템에 연결하는 공개 표준입니다. 지라 이슈를 복사해 붙여넣고, 결과를 다시 옮겨 적던 일을 Claude가 직접 합니다.
| 연결 대상 | 할 수 있게 되는 일 |
|---|---|
| 이슈 트래커 | "ENG-4521에 적힌 기능을 구현하고 PR 올려줘" |
| 모니터링 | "어제 오류가 늘어난 원인을 지표에서 찾아줘" |
| 데이터베이스 | "이 기능을 쓴 사용자 10명을 뽑아줘" |
| 문서 사이트 | "훅 설정하는 법을 공식 문서에서 찾아줘" |
모델은 바깥에 있습니다
"Claude가 내 DB를 직접 읽는다"는 말은 편의상의 비유입니다. 실제로 내 PC에서 도는 것은 Claude Code이고, 모델은 Anthropic 서버 — 바깥에 있습니다. MCP 서버를 실제로 부르는 손도 모델이 아니라 내 PC입니다.
도구를 한 번 쓸 때 데이터는 이렇게 내 PC와 바깥을 왕복합니다.
| 순서 | 어디서 | 무슨 일이 일어나나 |
|---|---|---|
| ① | 내 PC Claude Code | 내 말과 문맥, 그리고 붙어 있는 도구 목록(이름 · 설명 · 입력 스키마)을 묶어 Anthropic API로 보냅니다 |
| ② | 바깥 모델 | 도구가 필요하다고 판단하면 "이 도구를 이 인자로 불러라"는 지시만 돌려줍니다. 모델이 직접 부르지 않습니다 |
| ③ | 내 PC Claude Code | 그 지시를 받아 실제 호출을 실행합니다. 권한 승인 창도, 훅도 여기서 걸립니다 |
| ④ | MCP 서버 | 서버가 DB · 지라 · 파일에 접속해 결과를 만듭니다. stdio면 이 PC 안의 프로세스, http면 원격 서버입니다 |
| ⑤ | 내 PC Claude Code | 결과를 받아 대화에 이어 붙입니다 |
| ⑥ | 바깥 모델 | ①과 같은 경로로 결과까지 실려 다시 나갑니다. 이때 처음으로 모델이 결과를 봅니다 |
--transport http로 붙인 원격 서버라면 ④에서 한 번 더 밖으로 나갑니다 — 내 PC에서 그 서버로. 그 서버를 운영하는 쪽도 인자와 결과를 볼 수 있습니다. ④ 구간을 어디에 둘지는 다음 절에서 Oracle 예시로 봅니다.
그래서 무엇이 밖으로 나가나
| 항목 | 모델에게 가나 |
|---|---|
| 서버 접속 정보 — DB 비밀번호 · API 토큰 | 아니오. 내 PC의 설정과 서버 안에만 있습니다 |
| 도구 이름 · 설명 · 입력 스키마 | 예. 모델이 골라 쓸 수 있도록 요청에 함께 실립니다 (서버가 많으면 필요한 것만 골라 싣기도 합니다) |
| 호출 인자 | 예. ②에서 모델이 만든 값이니 당연합니다 |
| 도구가 돌려준 결과 | 예. 전부. ⑥에서 그대로 실려 나갑니다 |
서버를 어디에 둘까 — stdio vs 원격
앞 절 ④ 구간을 확대한 그림입니다. 사내 Oracle DB를 조회하는 oracle-mcp를 만들었다고 해봅시다 — 서버를 어디에 두느냐에 따라 이 구간이 달라집니다. 아래 두 도식에는 모델이 나오지 않습니다. 모델은 앞 절에서 본 대로 바깥에 있고, 어느 쪽을 고르든 조회 결과는 그리로 나갑니다.
① stdio — 내 PC에서 프로세스로
Claude Code가 내 PC에서 서버를 직접 실행합니다. 둘은 같은 컴퓨터 안에서 표준입출력으로 주고받고, DB 접속도 내 PC에서 나갑니다.
claude mcp add --transport stdio oracle -- node ./oracle-mcp/server.js
| 구간 | 지나가는 것 | 어디를 지나나 |
|---|---|---|
| Claude Code ↔ oracle-mcp | 도구 호출 · 결과 | 내 PC 안 (네트워크를 타지 않음) |
| oracle-mcp ↔ Oracle | SQL · 조회 결과 | 내 PC → 사내망 |
| 접속 정보 | DB 계정 · 비밀번호 | 내 PC에만 보관 |
② 원격 HTTP — 서버에 두고 호출
서버가 사내 서버나 클라우드에서 상시 실행되고, 내 PC는 HTTPS로 호출만 합니다. DB 접속은 그 서버에서 나갑니다.
claude mcp add --transport http oracle https://mcp.example.co.kr/oracle \ --header "Authorization: Bearer $TOKEN"
| 구간 | 지나가는 것 | 어디를 지나나 |
|---|---|---|
| Claude Code ↔ 서버 | 도구 호출 · 결과 | 내 PC → 네트워크 (HTTPS) |
| 서버 ↔ Oracle | SQL · 조회 결과 | 서버 → 사내망 |
| 접속 정보 | DB 계정 · 비밀번호 | 서버에만 보관 (사용자는 모름) |
둘 다 해당되는 것 — 결과는 모델로 갑니다
stdio가 지켜주는 것은 DB 접속 자격증명과 DB 자체에 대한 접근 경로이지, 조회 결과의 비공개가 아닙니다. 그래서 민감한 테이블일수록 서버 쪽에서 아래를 통제해야 합니다.
| 통제 | 방법 |
|---|---|
| 읽기 전용 | 조회 전용 계정만 사용. INSERT · UPDATE · DELETE 권한 제거 |
| 범위 제한 | 필요한 뷰·테이블만 노출. 전체 스키마를 열지 않기 |
| 건수 제한 | 도구가 반환하는 행 수에 상한. 전체 덤프 방지 |
| 마스킹 | 주민번호·연락처 등은 서버에서 가린 뒤 반환 |
서버 하나 붙여보기
아래는 Claude Code 공식 문서를 검색·조회하는 읽기 전용 서버입니다. 붙여두면 추측 대신 실제 문서를 읽고 답합니다.
claude mcp add --transport http claude-docs https://code.claude.com/docs/mcp
| 부분 | 뜻 |
|---|---|
| mcp add | 서버를 등록 |
| --transport http | 원격 HTTP 서버로 연결. 내 PC에서 프로세스를 띄우는 방식은 stdio |
| claude-docs | 내가 정하는 이름. 이후 목록과 도구 이름에 붙습니다 |
| https://… | 서버 주소 |
등록됐는지 확인하고, 세션 안에서는 /mcp로 봅니다.
claude mcp list
저장 위치는 --scope로 정합니다 — 생략하면 나만, project는 .mcp.json에 저장돼 팀과 공유, user는 내 모든 프로젝트에 적용됩니다.
claude mcp add --scope project --transport http claude-docs https://code.claude.com/docs/mcp
- MCP가 필요한 순간을 복사·붙여넣기로 판별할 수 있다
- 모델은 바깥, 호출은 내 PC라는 구분을 설명할 수 있다
- 서버를 하나 연결하고 claude mcp list로 확인했다
- --scope 세 가지의 차이를 안다
- stdio와 원격 HTTP의 데이터 경로 차이를 설명할 수 있다
- 조회 결과가 모델로 전송된다는 것을 안다