MCP로 사내 시스템 연결

02이 차시를 마치면

• 1.MCP가 왜 필요한지, 기존의 복사·붙여넣기식 연동과 무엇이 다른지 설명할 수 있다.
• 2.MCP의 구성 요소(클라이언트·서버·도구·리소스)를 각각의 역할로 구분해 설명할 수 있다.
• 3.이미 만들어진 MCP 서버를 Claude Code에 연결해 실제로 사용할 수 있다.
• 4.사내 API 하나를 감싸는 자체 MCP 서버를 최소 기능으로 만들 수 있다.
• 5.MCP 서버가 노출하는 권한 범위를 좁히고 기본적인 보안 점검을 할 수 있다.

03왜 필요한가

사내에는 이슈 트래커, 재고 조회용 사내 API, 휴가 신청 시스템, 업무용 구글 시트가 각각 따로 돌아가고 있다고 해보자. AI에게 '이번 주 미해결 이슈랑 재고 부족 품목을 같이 정리해줘'라고 시키고 싶어도, 지금 방식으로는 이슈 트래커 화면을 열어 내용을 복사하고, 사내 API 응답을 따로 조회해 붙여넣는 과정을 매번 사람이 대신 해줘야 한다. 시스템이 하나 더 늘어날 때마다 이 수작업도 하나씩 늘어난다.

• ·AI에게 새 데이터를 보여주려면 사람이 먼저 조회해서 붙여넣어야 한다 — 자동화가 아니라 반자동화에 머문다.
• ·시트는 시트대로, 이슈 트래커는 이슈 트래커대로 연결 방식이 제각각이라 시스템이 늘 때마다 매번 새로 설계해야 한다.
• ·복사·붙여넣기로 넘긴 데이터는 AI가 어디까지 접근했는지 기록이 남지 않아 권한 관리가 사실상 불가능하다.
• ·나 혼자 익힌 연동 요령은 파일이나 설정으로 남지 않아 동료에게 그대로 넘겨줄 수 없다.

04개념 설명

05실습 가이드

1. 1. 이미 있는 MCP 서버 하나 연결해보기

   • -Claude Code의 MCP 설정 화면(또는 설정 파일)을 연다.
   • -공개적으로 제공되는 MCP 서버 중 하나(예: 파일 시스템 조회용 서버)를 골라 설정에 등록한다.
   • -Claude Code를 재시작하고, 도구 목록에 새 서버의 도구가 나타나는지 확인한다.

   예상 결과 — 설정한 MCP 서버의 도구가 Claude Code의 사용 가능한 도구 목록에 나타난다.

   안 될 때 — 도구가 안 보이면 설정 파일 형식(따옴표, 쉼표 등)이 잘못됐을 가능성이 크다. P7-1 프롬프트로 설정 파일 내용을 그대로 보여주고 검토를 요청한다.

2. 2. 연결된 도구로 실제 요청해보기

   • -채팅창에 연결한 서버의 기능을 쓸 수밖에 없는 질문을 던져본다 (예: '지금 폴더에 있는 파일 목록을 보여줘').
   • -AI가 실제로 그 도구를 호출했는지, 답변 과정에 도구 사용 흔적이 보이는지 확인한다.

   예상 결과 — AI가 직접 답을 지어내지 않고, 연결된 도구를 호출해 실제 데이터를 가져와 답한다.

   안 될 때 — AI가 도구를 안 쓰고 짐작으로 답하면, 질문을 더 구체적으로(어떤 도구를 써야만 답할 수 있는 질문으로) 바꿔 다시 물어본다.

3. 3. 감쌀 사내 기능 하나 정하기

   • -실제 사내 API에 접근 권한이 있다면 조회(읽기) 기능 하나를 고른다. 접근 권한이 없다면 실습용 공개 테스트 API로 대체한다.
   • -이번 실습에서는 기능을 하나로 좁힌다 — 예: '상품 재고 조회하기' 하나만 감싼다.
   • -그 기능의 요청 방식(URL, 필요한 값)과 응답 형태를 메모해둔다.

   예상 결과 — 감쌀 기능 하나와 그 요청·응답 형태가 문서(또는 메모)로 정리된다.

   안 될 때 — API 문서가 없거나 이해가 안 되면, API 응답 예시를 그대로 AI에게 보여주고 어떤 값이 무슨 의미인지 물어본다.

4. 4. AI에게 최소 MCP 서버 코드 요청하기

   • -P7-2 프롬프트로 3단계에서 정리한 기능 하나만 감싸는 MCP 서버 코드를 요청한다.
   • -받은 코드를 프로젝트 폴더에 저장한다.
   • -필요한 패키지 설치 안내를 그대로 따라 실행한다.

   예상 결과 — 서버 코드 파일과 실행에 필요한 패키지가 준비된다.

   안 될 때 — 패키지 설치 중 에러가 나면 에러 메시지 전문을 P7-5(복구 프롬프트)에 붙여 다시 물어본다.

5. 5. 로컬에서 서버 실행하고 Claude Code에 연결하기

   • -터미널에서 서버를 실행해 오류 없이 뜨는지 확인한다.
   • -Claude Code의 MCP 설정에 방금 만든 서버를 등록한다.
   • -Claude Code를 재시작해 도구 목록에 새 도구가 뜨는지 확인한다.

   예상 결과 — 자체 서버가 로컬에서 실행되고, 그 서버의 도구가 Claude Code 도구 목록에 나타난다.

   안 될 때 — 도구 목록에 안 뜨면 설정 파일의 실행 경로나 포트 번호가 실제 서버와 다른지 먼저 확인한다.

6. 6. 실제 요청으로 동작 확인하기

   • -채팅창에서 감싼 기능을 실제로 쓰는 질문을 던진다 (예: '재고 5개 이하인 상품 있어?').
   • -서버를 거쳐 실제 응답이 돌아오는지, 값이 실제 시스템 상태와 일치하는지 확인한다.

   예상 결과 — AI가 자체 MCP 서버를 통해 실제 데이터를 가져와 정확하게 답한다.

   안 될 때 — 값이 이상하거나 에러가 나면 P7-5로 에러 내용과 요청 내용을 함께 보내 원인을 확인한다.

7. 7. 권한 범위 좁히기

   • -P7-3 프롬프트로 지금 서버가 노출하는 도구 목록을 점검받는다.
   • -실습에 필요 없는 동작(쓰기·삭제 등)이 포함돼 있다면 제거하거나 별도 승인 없이는 실행되지 않도록 막는다.
   • -변경 후 다시 실행해 필요한 조회 기능은 그대로 동작하는지 확인한다.

   예상 결과 — 서버가 노출하는 도구가 꼭 필요한 조회 기능만 남는다.

   안 될 때 — 기능을 줄였더니 필요한 조회까지 막혔다면, 어떤 도구를 남기고 뺐는지 AI에게 다시 설명하고 조정을 요청한다.

8. 8. 보안 점검하기

   • -P7-4 프롬프트로 서버 코드에 인증키가 그대로 적혀 있는지, 로그에 민감한 값이 그대로 남는지 점검받는다.
   • -지적된 부분을 환경변수 분리 등으로 수정한다.
   • -수정한 코드가 저장소에 올라가기 전이라면 커밋 이력에도 키가 없는지 다시 확인한다.

   예상 결과 — 인증키가 코드에서 분리되고, 점검 항목에서 지적된 문제가 해소된다.

   안 될 때 — 이미 커밋에 키가 들어갔다면 단순히 지우는 것으로는 이력에서 사라지지 않는다. 키를 즉시 폐기·재발급하고 AI에게 이력 정리 방법을 물어본다.

06실전 프롬프트

Claude Code에 MCP 서버를 연결하려고 설정 파일에 이렇게 등록했어.

[설정 파일 내용을 그대로 붙여넣기]

그런데 재시작해도 도구 목록에 안 나타나.
설정 형식이 잘못된 부분이 있는지 봐주고,
고친 설정을 알려줘.

[상품 재고 조회] 기능 하나만 감싸는 MCP 서버를 만들고 싶어.

이 기능의 요청 방식은 이래.
· 요청 주소: [API 주소]
· 필요한 값: [상품 코드 등 파라미터]
· 응답 형태: [응답 예시]

딱 이 조회 기능 하나만 도구로 노출하고,
쓰기나 삭제 같은 다른 동작은 아예 넣지 마.
인증키는 코드에 직접 적지 말고 환경변수로 받게 해줘.

로컬에서 실행하는 방법도 순서대로 알려줘.

지금 이 MCP 서버 코드가 노출하는 도구 목록을 점검해줘.

[서버 코드 전체 또는 도구 정의 부분]

1. 지금 실습에 실제로 필요한 도구만 남기면 뭐가 남아야 하는지 알려줘.
2. 당장 필요 없는데 노출돼 있는 동작(쓰기·삭제 등)이 있으면 짚어줘.
3. 그 동작들을 빼거나 승인 없이는 실행 안 되게 막은 코드로 고쳐줘.

이 MCP 서버 코드를 저장소에 올리기 전에 보안 점검을 해줘.

[서버 코드 전체]

1. 인증키나 비밀번호가 코드에 직접 적혀 있는 곳이 있는지 찾아줘.
2. 있으면 환경변수로 옮기고, 등록 방법도 알려줘.
3. 요청·응답 로그에 민감한 값이 그대로 찍히는 부분이 있는지도 봐줘.
4. .gitignore에 빠진 게 없는지 확인해줘.

MCP 서버를 실행했더니 이런 문제가 났어.

[에러 메시지 또는 기대와 다른 결과 전체]

내가 한 것: [실행한 순서 그대로]
서버 설정: [연결에 쓴 설정 파일 내용]

무엇이 문제인지 먼저 설명하고, 고친 코드나 설정을 줘.
같은 문제가 다시 안 생기려면 뭘 확인해야 하는지도 알려줘.

07이것만은 주의

08자가 점검

09과제

자신의 실제 업무에서 AI에게 연결하고 싶은 사내 시스템(이슈 트래커, 사내 API, 내부 데이터베이스 등) 하나를 골라, 조회 기능 한 가지만 감싸는 MCP 서버를 설계하고 만들어본다. 접근 가능한 사내 시스템이 없다면 공개 테스트 API로 대체해도 된다.

제출 형식 — ① MCP 서버 코드가 담긴 저장소 링크 ② 노출한 도구 목록과 각 도구의 권한 범위 설명 ③ 보안 점검 체크리스트(인증키 분리, 로그 점검, .gitignore 확인) 결과를 문서로 정리해 제출한다.

10더 알아보기

• MCP 공식 스펙 문서 — 클라이언트·서버·도구·리소스의 정확한 정의와 통신 방식 확인용
• Claude Code MCP 연동 가이드 — 설정 파일 형식과 서버 등록 절차의 최신 방법 확인용

MCP(Model Context Protocol)

— AI 클라이언트와 외부 시스템(서버)을 표준화된 방식으로 연결하기 위한 프로토콜.

도구(tool)

— MCP 서버가 AI에게 노출해, AI가 직접 호출해 실행시킬 수 있는 동작.

리소스(resource)

— MCP 서버가 AI에게 읽을 수 있도록 열어둔 데이터 단위(문서, 테이블 등).

최소 권한 원칙

— 지금 꼭 필요한 만큼의 접근 권한만 부여하고, 필요해지면 그때 넓히는 보안 설계 원칙.

다음 차시 예고 — 다음 차시에서는 이번 차시에서 다룬 서버 하나를 넘어, 여러 개의 AI 에이전트를 동시에 굴려 작업을 나눠 맡기고 서로 검증하게 만드는 법을 다룹니다.