전 장에서 MCP의 정체 —— 「Claude를 외부 서비스에 연결하는 규격」 —— 은 이해했다. 이 장에서는 실제 접속 절차를 자주 사용하는 서비스별로 해설한다.

하는 일은 간단하다. 설정 파일에 몇 줄 적고, Claude Code를 재시작하는 것뿐이다. 함께 해보자.

설정 파일은 어디에 있는가

Claude Code의 MCP 설정은 홈 디렉터리 안에 있는 JSON 파일에 작성한다.

~/.claude/settings.json

이 파일이 없는 경우에는 직접 만들어도 된다. 이미 있는 경우에는 열어서 내용을 확인한다.

참고로, Claude Desktop (데스크톱 앱 버전)의 경우에는 경로가 다르다:

~/Library/Application Support/Claude/claude_desktop_config.json (Mac)
%APPDATA%\Claude\claude_desktop_config.json (Windows)

CLI 버전 (터미널에서 claude라고 입력하여 사용하는 것)과 Desktop 버전은 설정 파일이 별개다. 이 기사는 CLI 버전을 전제로 진행한다.

설정의 기본 구조

settings.json에 MCP를 추가할 때는 mcpServers라는 키 안에 각 서비스를 나열한다. 예시를 보는 것이 가장 빠르다.

{
"mcpServers": {
"github": {
...

각 파트의 의미는 다음과 같다.

• mcpServers: 모든 MCP의 부모 키
• github: MCP의 이름 (직접 지정 가능)
• command: 실행 커맨드 (대부분 npx)
• args: 실행할 구체적인 패키지와 인자 (Arguments)
• env: API 키 등 해당 MCP가 필요로 하는 비밀 정보

여러 개의 MCP를 연결하고 싶을 때는 mcpServers 안에 나열하여 작성한다.

{
"mcpServers": {
"github": { ... },
...

케이스 1: GitHub MCP

리포지터리(Repository) 목록 취득, Issue 생성, PR 리뷰 등이 가능해진다.

API 키 (Personal Access Token) 발급 방법

• GitHub 로그인
• 우측 상단 아이콘 → Settings → Developer settings → Personal access tokens → Tokens (classic)
• 「Generate new token」 클릭
• 스코프(Scope)는 최소한으로. repo와 read:org만으로도 많은 조작을 커버할 수 있다.
• 발급된 토큰 (ghp_...)을 복사

토큰은 발급된 순간에만 표시된다. 복사를 잊었다면 다시 만들어야 한다.

settings.json에 추가

{
"mcpServers": {
"github": {
...

케이스 2: Notion MCP

Notion의 페이지나 DB 조작이 가능해진다. "회의록 페이지를 읽고 요점을 정리해줘", "태스크 DB에 추가해줘"와 같은 요청을 한마디로 실행할 수 있다.

API 키 (Integration Token) 발급 방법

• Notion My integrations 접속
• 「+ New integration」 클릭
• 이름을 붙여 생성 (예: Claude Code)
• 발급된 Internal Integration Token (secret_...)을 복사
• 중요: 사용하려는 Notion 페이지를 열고, 우측 상단 「・・・」 → 「Connections」에서 방금 만든 integration을 추가한다. 이 작업을 하지 않으면 Claude는 페이지를 읽을 수 없다.

settings.json에 추가

{
"mcpServers": {
"notion": {
...

케이스 3: Slack MCP

Slack으로 메시지 전송이나 채널의 히스토리 취득이 가능해진다.

Bot Token 발급 방법

• Slack API: Your Apps 접속
• 「Create New App」 → 「From scratch」
• App 이름과 Workspace 설정
• 왼쪽 메뉴 「OAuth & Permissions」 열기
• Bot Token Scopes에 다음을 추가:
• chat:write

（메시지 전송） -
channels:read

（채널 목록） -
users:read

（사용자 정보）

• 페이지 상단의 「Install to Workspace」를 클릭
• 발행된 Bot User OAuth Token (xoxb-...)을 복사

settings.json에 추가

{
"mcpServers": {
"slack": {
...

연결 확인

설정을 모두 작성했다면, Claude Code를 완전히 재시작한다. Ctrl+C로 빠져나온 뒤, 다시 한번 claude로 실행한다. 다시 로드되지 않았다면 아무것도 작동하지 않는다.

실행되었다면, 각각 시도해 본다.

• GitHub: "내 리포지토리 목록을 보여줘"
• Notion: "Notion 페이지 목록을 가져와줘"
• Slack: "Slack의 #general 채널에 '테스트'라고 게시해줘"

연결되어 있다면, Claude가 실제로 동작하여 결과를 반환한다.

자주 발생하는 실패 패턴 3가지

1. Claude Code를 재시작하지 않음

이것이 가장 흔한 경우다. 설정 파일은 실행 시에만 읽힌다. 내용을 수정했다면 반드시 재시작해야 한다.

2. API 키 앞뒤에 공백이 섞여 있음

복사 및 붙여넣기 과정에서 앞부분이나 뒷부분에 불필요한 공백이 들어갈 수 있다. 에디터의 「보이지 않는 문자 표시」 기능으로 확인하거나, 다시 한번 붙여넣는다. 키 자체가 무효화되는 것은 아니므로, 몇 번이고 다시 붙여넣어도 괜찮다.

3. npx를 사용할 수 없음

대부분의 MCP는 Node.js의 npx 명령어로 동작한다. 터미널에서 npx --version을 입력하여 버전이 나오는지 확인한다. 나오지 않는다면 Node.js 공식 사이트에서 설치한다.

처음에는 하나만 연결하자

"전부 연결하고 싶다"는 마음은 억누르고, 처음에는 하나만 연결한다. 이유는 세 가지다.

• 문제가 발생했을 때 원인을 좁힐 수 있다 —— 어떤 MCP가 문제를 일으키는지 한눈에 알 수 있다.
• 설정 실수를 알아채기 쉽다 —— 확인해야 할 부분이 한 블록으로 끝난다.
• 성취감을 느끼기 쉽다 —— "이거 정말 편리하다"라고 실감한 뒤에 다음 단계로 넘어갈 수 있다.

가장 자주 사용하는 서비스(매일 접하는 것)부터 추가하고, 안정적으로 운영할 수 있게 되면 두 번째로 넘어간다. 이 페이스가 결국 가장 빠르다.

다음 단계

MCP를 통해 "외부 세계"와 연결되었다면, 다음은 "Claude 내부의 기능"을 더 끌어내는 방법이다. 다음 장에서는 **Skills (스킬)**를 다룬다. /seo-audit 같은 슬래시 명령어를 본 적이 있는가? 그것의 정체와 사용법을 해설한다.

Claude Code 초급~중급자용 교과서 시리즈 / 중급편 Chapter 2

Discussion