Claude Code에서 MCP를 설정하는 방법

Overview

개인적으로 앤트로픽(Anthropic) 사의 기술 문서를 좋아하지 않는다. 겉보기에 내용은 많지만 정작 실속은 없기 때문이다. 이 글에서는 내가 Claude Code를 사용하면서 MCP 설정에서 느꼈던 불편함, 그리고 이걸 해결한 방법에 대해 설명한다.

간단 요약

~/.claude.json 에 들어가서 $.mcpServers 항목을 편집하면 다른 IDE와 같은 방식으로 MCP 설정을 할 수 있다.

본문

CLI를 통한 MCP 등록

아래는 클로드 코드 기술문서에서 "MCP" 항목을 들어가면 볼 수 있는 명령어이다.

# 기본 구문
claude mcp add <name> <command> [args...]

# 실제 예시: Airtable 서버 추가
claude mcp add airtable --env AIRTABLE_API_KEY=YOUR_KEY \
  -- npx -y airtable-mcp-server

그렇다. 클로드 코드는 MCP 추가를 CLI로 진행할 것을 공식적으로 가이드한다. 나한테는 당황스러웠던 부분인데, Cline이나 Cursor, Windsurf 등의 AI 에이전트 기반 코딩 툴은 전부 아래와 같이 .json 파일 편집을 하기 때문이다.

{
  "mcpServers": {
    "slack": {
      "command": "cmd",
      "args": ["/c", "npx", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "my_bot_token",
        "SLACK_TEAM_ID": "TEAM_ID"
      }
    }
  }
}

대부분의 MCP 서버는 API 토큰 등 추가적으로 설정해줘야 할 것들이 있다. 이것을 CLI 하나로 처리하는 건 생각보다 귀찮은 일이다.

이에 관해서 앤트로픽은 ".mcp.json" 파일에서 변수 확장을 할 수 있다고 아래와 같이 가이드한다.

{
  "mcpServers": {
    "api-server": {
      "type": "sse",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

이 부분이 매우 흥미로운데, .mcp.json이 도대체 어디에 있는 것 말하는지 일언반구도 하지 않는다. ~/.mcp.json 일까? ~/.claude/.mcp.json 일까? 프로젝트 디렉토리의 ~/.mcp.json 일까? 내가 어딘가를 안 읽고 건너 뛴걸까? 이 글을 쓰기 위해서 다시 들어가봤지만, 여전히 이에 대한 설명은 없다.

지금까지 확인한 결과로는, 프로젝트 디렉토리의 .mcp.json 을 의미하는 것 같다.

JSON 파일 편집을 통한 MCP 설정

구글링을 해도 마땅한 답이 나오지 않던 도중, reddit에서 한 유저가 알려준 방법이 실제로 효과가 있었다.

Reddit의 ClaudeAI 커뮤니티: Setting Up MCP Servers in Claude Code: A Tech Ritual for the Quietly Desperate

 

정답은 ~/.claude.json 파일을 수정하는 것이다.

{
  "numStartups": 24,
  "installMethod": "unknown",
  "autoUpdates": true,
  // ... 생략
  "mcpServers": {
    "api-server": {
      "type": "sse",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

~/.claude.json 파일을 열어보면 Claude Code와 관련된 수많은 설정값이 나오는데, 그 중 mcpServers 라고 하는 부분을 찾으면 된다. 찾으면 {}로 비워져있을 텐데, 여기를 편집하고 저장한 뒤에 claude 명령어를 실행하면 확인이 가능하다.

주의점. mcpServers라는 프로퍼티가 하나만 등장하지 않는다. project마다 mcpServers가 별도로 생성되는데, 전역(global)으로 사용하고 싶은 mcpServer 라면 무조건 가장 상위 단계에 있는 mcpServers를 수정해야한다.

 

추가된 mcp는 /mcp 명령어 입력으로 상태를 확인해볼 수 있다.

부록. MCP 설치 범위(scope)에 대해서

클로드 코드는 MCP의 설치 범위를 세밀하게 나누어서 제공하고 있다. 로컬, 프로젝트, 사용자인데. 범위에 대한 설명은 아래와 같다.

• 로컬 : 특정 프로젝트 안에서 나만 쓰도록 설정하는 MCP 설치 레벨. 프로젝트 루트 디렉토리의 .claude.json에 설정된다.
• 프로젝트 : 특정 프로젝트 안에서 공용으로 사용될 수 있도록 설정하는 MCP 설치 레벨. 프로젝트 루트 디렉토리의 .mcp.json에 설정된다.
• 사용자 : 모든 프로젝트에서 나만 쓰도록 설정하는 MCP 설치 레벨. 홈 디렉토리의 .claude.json에 설정된다.

아무래도 프로젝트를 여러명이서 개발하다보면 나만 사용하는 MCP를 설정해서 써야할 일도 있을텐데, 이것을 위해 격리레벨을 나눠놓은 것 아닌가 싶다. 실상 이것을 엄격하게 구분해가며 쓸 일이 얼마나 있을지는 모르겠지만...

.gitignore에 .claude.json을 추가해서 나만 쓰고 싶었던 MCP 서버가 커밋 로그에 포함되는 불상사를 피하도록 하자.