[Claude Code] MCP (10)

개발/Claude Code

[Claude Code] MCP (10)

firsthg 2026. 9. 3. 17:34

목표: 클로드가 외부 도구와 데이터에 접근할 수 있도록 만들기

Step 1. MCP(Model Context Protocol)란?

지금까지 클로드 코드가 쓴 도구는 내장 도구로서
파일을 읽고(Read), 고치고(Edit), 검색하고(Grep), Shell 명령을 실행(Bash)했다.
전부 내 컴퓨터의 파일과 명령에 대한 것이다.

그런데 실제 개발은 내 컴퓨터의 파일 밖에서도 일어난다.
기존에 이슈 트래커, 데이터베이스, 브라우저, 문서 사이트와 같은 외부 서비스에 접근하려면 Bash로 우회하거나,
클로드 코드를 벗어나 다른 프로그램을 열어야 했다.

MCP는 클로드 코드가 외부 데이터에 쉽게 접근하고 연동할 수 있도록 돕는 표준화된 통신 규약이다.
외부 서비스가 "나는 이런 도구를 제공한다"고 정해진 형식으로 노출하면, 클로드는 그걸 자기 도구 목록에 추가한다.
그 외부 서비스를 제공하는 프로그램을 MCP 서버라고 부른다.

서버는 두 종류가 있다.

종류	어디서 도나	예
HTTP	인터넷 어딘가의 서버	문서 검색 등
stdio	내 컴퓨터에서 프로그램으로	브라우저 제어, 로컬 DB 접근 등

Step 2. 클로드 코드에 MCP서버 추가하기

클로드 코드 공식 문서 검색 서버를 추가해보자.
인증이 필요 없어서 클로드 코드에 추가하는 첫 번째 서버로 적당하다.
이제 클로드 코드가 클로드 코드의 공식 문서를 직접 찾아볼 수 있게 된다.

실습 프로젝트 루트에서

cd ~/shop-api

다음 명령어를 실행하여 mcp 서버 설정 파일을 생성한다.

cat > .mcp.json <<'EOF'
{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    }
  }
}
EOF

파일 구조

claude-code-docs — 사용자가 설정하는 mcp 서버 이름이다. 클로드의 출력에서 이 서버의 도구에 붙는 이름표가 되고, 나중에 서버를 지목할 때 쓴다.
type: "http" — 인터넷 주소로 접속하는 서버라는 뜻
url — 접속할 주소

MCP 서버 설정 적용 범위

범위	파일	적용 대상
local	~/.claude.json, 이 프로젝트의 항목 아래	나만, 이 프로젝트만 (기본값)
project	.mcp.json	저장소(git)를 받는 모든 사람
user	~/.claude.json, 최상위 mcpServers 키 아래	나만, 모든 프로젝트

.mcp.json을 골랐을 때의 이점은 두 가지이다.
파일로 직접 만들 수 있어서 CLI 명령이 필요 없고, git에 커밋되어 팀원이 저장소를 받으면 같은 설정을 쓰게 된다.

터미널에서 claude-code를 실행하면 mcp 서버 승인 요청이 나타나고 해당 승인 요청을 수락한 다음에 다음 명령어를 입력하면

/mcp

설정한 mcp 서버와 정상적으로 연결된 것을 확인할 수 있다. (connected)

Step 3. MCP 사용해보기

설정한 MCP 서버 이름을 직접 지목하고 클로드 코드 문서에 관한 질문을 던진다.

claude-code-docs 서버를 써서, 서브에이전트가 무엇인지 찾아줘.

그러면 위와 같이 도구 호출 줄에 설정한 claude-code-docs 라는 이름표가 붙어 있는 것을 볼 수 있다.

클로드가 기억으로 답한 것이 아니라 실제로 문서를 검색한 것이다.

그리고 평소에는 서버 이름을 말할 필요가 없다. 클로드가 알아서 필요한 도구를 고릅니다.

여기서 지목하는 이유는 답이 정말 이 서버에서 왔는지 확인하기 위해서이다.

Step 4. 연결된 MCP 서버는 컨텍스트를 차지한다.

연결된 MCP 서버는 도구 이름과 설명을 매 대화에 싣는다.
MCP 서버는 책상 위에 미리 놓여 있는 사용 설명서이다. 아직 쓰지 않았어도 자리를 차지한다.

서버 하나가 도구를 20개 제공하면 그 20개의 설명이 매번 실린다. 서버 셋을 붙이면 50개가 넘어가고, 그만큼 실제 작업에 쓸 공간이 줄어든다. 도구가 많아질수록 클로드가 어떤 걸 써야 할지 고르기도 어려워진다.

그래서 안 쓰는 서버는 빼는 것이 좋다. 이번 실습이 끝나면 .mcp.json을 지우거나, 계속 쓸 거라면 남겨두면 된다.

핵심 정리

1. MCP는 외부 도구를 클로드 코드에 붙이는 규약이다.
내장 도구는 내 컴퓨터의 파일과 명령에 대한 것이고, MCP는 그 바깥으로 나간다.

2. 서버는 HTTP와 stdio 두 종류다.
전자는 인터넷 주소로 접속, 후자는 내 컴퓨터에서 프로그램으로 실행.

3. .mcp.json은 프로젝트 범위 설정이다.
git에 커밋되어 팀과 공유된다. 나만 쓸 거면 ~/.claude.json에 user 범위로 둔다.

4. 프로젝트 범위(.mcp.json)로 등록된 서버는 승인을 거친다.
내가 만든 파일이어도 마찬가지이며 동의 없이 프로그램이 실행되지 않게 하기 위해서다.

5. 서버 이름을 지목하면 확인이 쉬워진다.
도구 호출에 붙는 이름표로, 답이 기억이 아니라 그 서버에서 왔음을 알 수 있다.

6. 연결된 서버는 쓰지 않아도 컨텍스트를 차지한다.
도구 이름과 설명이 매 대화에 실린다. 안 쓰는 서버는 뺀다.