오늘만 무료

MCP 서버 관리 완전 가이드

add·list·get·remove 4가지 커맨드와 스코프 운용법

9시간전 brunch_membership's

1장, 2장에서도 add / get / list / remove는 사용했지만, 어디까지나 "filesystem 서버를 동작시킨다" "stdio와 HTTP의 차이를 체감한다"를 위한 수단이었습니다. 이번 회차에서는 이러한 커맨드 자체에 초점을 맞춥니다.

환경 변수의 전달 방법 (-e 옵션, JSON 설정 파일의 env 필드)

스코프의 우선순위와 의도하지 않은 덮어쓰기 회피

설정 변경 시의 삭제 → 재등록 패턴

자주 있는 실수와 그 대처법

즉, 1장·2장에서 "MCP 서버를 사용해본다"였다면, 3장은 "MCP 서버를 올바르게 관리한다" 를 위한 장입니다.

전제 조건

1장·2장를 완료했을 것

~/mcp-workspace 프로젝트가 존재할 것

filesystem, memory MCP 서버가 등록되어 있을 것 (2장에서 등록)

GitHub CLI 툴(gh)이 설치되어 있으면 바람직함

이번 장의 목표

MCP 서버의 4가지 관리 커맨드(add / list / get / remove)를 체계적으로 이해하여 여러 MCP 서버를 효율적으로 관리할 수 있게 됩니다. GitHub MCP 서버를 "외부 서비스 통합 워크스페이스"에 추가합니다.

배경 지식

MCP 서버 관리의 전체 구조

Claude Code에서는 MCP 서버의 라이프사이클을 4가지 커맨드로 관리합니다.

각 커맨드의 개요

중요: 이러한 커맨드는 모두 터미널에서 실행합니다. Claude Code의 대화 모드(채팅) 내에서는 MCP 서버의 추가·삭제는 할 수 없습니다. 대화 모드 내에서 MCP 서버의 상태를 확인하려면 /mcp 슬래시 커맨드를 사용합니다.

스코프의 개념 (복습과 심화)

MCP 서버의 등록에는 스코프가 있으며, 설정의 적용 범위를 제어합니다.

스코프의 우선순위는 local > project > user입니다. 동명의 서버가 여러 스코프에 존재하는 경우, 더 한정적인 스코프가 우선됩니다. 스코프를 생략한 경우의 기본값은 local 입니다.

� 한국 팀 개발 환경에서의 스코프 운용 가이드

따라하기

1단계: claude mcp add의 상세

claude mcp add의 완전한 구문을 확인합니다.

stdio 서버의 추가:

claude mcp add --transport stdio --scope <scope> <n> -- <command> [args...]

HTTP 서버의 추가:

claude mcp add --transport http --scope <scope> <n> <url>

각 파라미터의 의미:

※ <command>는 stdio의 경우에 필수, <url>은 HTTP의 경우에 필수입니다.

2단계: 환경 변수를 포함하여 서버를 추가한다

MCP 서버에 환경 변수를 전달해야 하는 경우(GitHub PAT, Slack 토큰 등)의 두 가지 방법을 확인합니다.

방법 1: -e 플래그로 직접 전달

claude mcp add의 -e / --env 옵션으로 환경 변수를 직접 지정할 수 있습니다. 다음은 구문의 예시입니다 (Step 3에서 GitHub MCP 서버를 추가하므로, 여기서는 실행하지 마세요).

# 구문 예시 (실행 불필요)
claude mcp add --transport stdio --scope project <n> -e KEY=value -- <command> [args...]

방법 2: JSON 설정 파일의 env 필드를 사용

여러 환경 변수를 관리하는 경우는 JSON 설정 파일 쪽이 관리하기 쉽습니다.

cat > ~/mcp-workspace/config/mcp-with-env.json << 'EOF'
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx"
}
}
}
}
EOF

⚠️ 보안 주의: 실제 토큰을 설정 파일에 직접 쓰는 경우는, 이 파일을 반드시 .gitignore에 추가하세요. 인증 정보가 Git에 커밋되면 보안 사고로 이어집니다. 토큰의 안전한 관리 방법은 4회차·8회차에서 자세히 다룹니다.

echo "config/mcp-with-env.json" >> ~/mcp-workspace/.gitignore

3단계 GitHub MCP 서버를 추가한다

"외부 서비스 통합 워크스페이스"에 GitHub MCP 서버를 추가합니다.

먼저, GitHub Personal Access Token(PAT)을 취득합니다.

방법 A: GitHub CLI를 사용 (권장)

# GitHub CLI로 인증 완료된 경우, 현재 토큰을 확인할 수 있다
gh auth token

방법 B: GitHub 웹에서 발급

GitHub Settings > Developer settings > Personal access tokens > Tokens (classic) 또는

Fine-grained tokens에서 작성합니다.

� PAT 필요 권한 (GitHub MCP 서버)
repo, read:org, read:user 등의 권한을 부여합니다. Fine-grained tokens를 사용하는 경우는 최소 권한 원칙에 따라 필요한 리포지토리·권한만 지정하세요.

GitHub MCP 서버를 추가합니다.

claude mcp add --transport stdio --scope project github -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx -- npx -y @modelcontextprotocol/server-github

주의: ghp_xxxxxxxxxxxxxxxxxxxx는 실제 토큰으로 교체하세요. 토큰의 안전한 관리 방법은 4회차·8회차에서 자세히 다룹니다.

또는 2단계에서 작성한 JSON 설정 파일을 사용하여 기동할 수도 있습니다.

claude --mcp-config ~/mcp-workspace/config/mcp-with-env.json

4단계: claude mcp list의 활용

등록된 서버의 목록을 확인합니다.

--scope project로 추가한 서버는 .mcp.json에 저장되므로, cat .mcp.json으로 확인합니다.

cd ~/mcp-workspace
cat .mcp.json

기대되는 출력 (복수 서버 등록 시):

{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/mcp-workspace"]
},
"github": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "<gh auth token으로 취득한 토큰>"
}
}
}
}

user나 local 스코프의 서버는 claude mcp list로 확인할 수 있습니다.

claude mcp list

cat .mcp.json과 claude mcp list의 차이:

5단계: claude mcp get으로 서버 상세 확인

특정 서버의 상세 정보를 취득합니다. 1회차에서 추가한 filesystem 서버로 확인해봅시다.

claude mcp get filesystem

기대되는 출력:

filesystem:
Scope: Project config (shared via .mcp.json)
Status: ✓ Connected
Type: stdio
Command: npx
Args: -y, @modelcontextprotocol/server-filesystem, /Users/yourname/mcp-workspace

claude mcp get github

트러블슈팅 시에는 get 커맨드가 중요해집니다. 등록된 커맨드나 인수가 올바른지 확인할 때 사용합니다.

� 트러블슈팅 체크리스트
서버가 failed 상태인 경우, claude mcp get <n>으로 다음을 확인하세요.
- Command와 Args가 올바른가
- env에 지정한 토큰이 유효한가 (만료되지 않았는가)
- HTTP 서버의 경우 URL이 올바르고 서버가 기동 중인가

6단계: claude mcp remove에 의한 안전한 삭제

서버를 삭제하기 전에, 반드시 get으로 내용을 확인하는 습관을 들이세요. 여기서는 2회차에서 등록한 memory서버를 예로 사용합니다.

# 먼저 확인
claude mcp get memory

# 확인 후 삭제
claude mcp remove memory

기대되는 출력:

Removed MCP server "memory" from project config
File modified: /Users/yourname/mcp-workspace/.mcp.json

삭제되었는지 확인합니다.

claude mcp get memory

존재하지 않는 서버를 삭제하려고 한 경우:

No MCP server found with name: "memory"

에러 메시지가 표시됩니다.

7단계: 서버의 재등록 (설정 변경)

MCP 서버의 설정을 변경하려면, 한 번 삭제하고 나서 재등록합니다.

# 현재 설정을 확인
claude mcp get filesystem

# 삭제
claude mcp remove filesystem

# 새로운 설정으로 재등록 (예: 접근 디렉토리를 추가)
claude mcp add --transport stdio --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/mcp-workspace ~/Documents

# 확인 후, 원래 설정으로 되돌린다
claude mcp remove filesystem
claude mcp add --transport stdio --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/mcp-workspace

� 설정 변경의 워크플로우를 팀 규칙으로 명문화
MCP 서버 설정 변경 시의 순서(get 확인 → remove → add → 재확인)를 팀의 개발 가이드에 기술해두면, 신규 멤버도 안전하게 조작할 수 있습니다.

8단계: 복수 서버의 일괄 관리

2장에서도 JSON 설정 파일에 의한 관리를 소개했지만, 여기서는 환경 변수(env)를 포함한 복수 서버의 일괄 관리를 시험해봅시다.

⚠️ 주의: 이 파일에는 인증 정보가 포함되므로, 절대로 Git에 커밋하지 마세요. .gitignore에의 추가는 4장·8장에서 다룹니다.

cat > ~/mcp-workspace/config/mcp-all.json << 'EOF'
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/mcp-workspace"]
},
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "<gh auth token으로 취득한 토큰>"
}
}
}
}
EOF

이 설정 파일로 기동합니다.

claude --mcp-config ~/mcp-workspace/config/mcp-all.json

9단계: 자주 있는 실수와 대처법

실수 1: 동명 서버의 중복 등록

같은 이름으로 다른 스코프에 등록하면, 우선순위에 의해 한쪽만 유효해집니다.

# 다음은 설명용 예시입니다 (some-server / another-server는 가상 패키지명입니다)

# project 스코프
claude mcp add --transport stdio --scope project myserver -- npx -y some-server

# user 스코프 (동명)
claude mcp add --transport stdio --scope user myserver -- npx -y another-server

# list로 확인: project 스코프가 우선되어, user 스코프의 동명 서버는 무효가 된다
claude mcp list

대처: 서버명은 스코프 간에 유일하게 하거나, 의도적인 덮어쓰기가 아닌 한 중복을 피하세요.

실수 2: args의 구분을 잘못한다

# 잘못된 방법: 인수를 쿼트로 감싸버린다
claude mcp add --transport stdio --scope project fs "npx -y @modelcontextprotocol/server-filesystem ~/dir"

# 올바른 방법: 각 인수를 스페이스 구분으로 전달한다
claude mcp add --transport stdio --scope project fs -- npx -y @modelcontextprotocol/server-filesystem ~/dir

실수 3: 스코프를 지정하는 것을 잊는다

스코프를 생략한 경우의 기본값은 local입니다. 팀 공유 목적인데 local 스코프에 등록하면

.mcp.json에 저장되지 않아, 팀 멤버에게 공유되지 않습니다.

명시적으로 스코프를 지정하는 습관을 들이세요.

# ⚠️ 스코프 생략 → local에 등록됨 (팀 공유 안됨)
claude mcp add --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/mcp-workspace

# ✅ 명시적 지정 → project에 등록됨 (팀 공유 가능)
claude mcp add --transport stdio --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/mcp-workspace

더 나아가기

팀 공유를 위한 .mcp.json 관리 전략

인증 정보(env 필드)가 없는 서버(filesystem, memory 등)는 .mcp.json을 Git에 커밋하여 팀 공유할 수 있습니다. 인증 정보가 있는 서버는 다음과 같이 분리하여 관리하세요.

# 팀 공유용 (.mcp.json에 저장, Git 관리 성공)
claude mcp add --transport stdio --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/mcp-workspace

# 개인 인증 정보 (local 스코프, Git 관리 밖)
claude mcp add --transport stdio --scope local github -e GITHUB_PERSONAL_ACCESS_TOKEN=$(gh auth token) -- npx -y @modelcontextprotocol/server-github