Claude Code에 MCP 서버 연결하기: settings.json 직접 설정 가이드

이 가이드가 다루는 것

Claude Code는 터미널에서 동작하는 Anthropic의 공식 코딩 에이전트입니다. 여기에 MCP 서버를 연결하면 Claude가 DART 공시, 공공데이터 같은 외부 데이터·도구를 대화 중에 직접 호출할 수 있습니다.

연결 방식은 크게 두 가지입니다. claude mcp add 같은 CLI 명령으로 추가하는 방법과, 설정 파일을 직접 편집하는 방법입니다. 이 글은 ~/.claude/settings.json을 직접 편집하는 방식을 다룹니다. 설정이 파일 하나에 그대로 남아 버전 관리·복제·검토가 쉽고, 여러 서버를 한눈에 관리할 수 있어 가장 안정적입니다.

전체 과정은 “파일 열기 → mcpServers 블록 작성 → 재시작 → 확인” 네 단계로 끝납니다.

1단계 — 설정 파일 열기

홈 디렉터리의 ~/.claude/settings.json을 엽니다. 이 파일은 Claude Code의 전역 설정을 담으며, MCP 서버 목록도 여기에 둡니다. 파일이나 디렉터리가 없으면 아래 명령으로 만들면서 엽니다.

mkdir -p ~/.claude
open -e ~/.claude/settings.json   # macOS, 없으면 새로 생성됨

처음 만든 파일이라면 내용이 비어 있을 수 있습니다. 다음 단계의 JSON 전체를 그대로 붙여 넣어 시작하세요. 이미 다른 설정이 들어 있다면 mcpServers 키만 최상위에 추가하면 됩니다.

2단계 — mcpServers 블록 작성

최상위에 mcpServers 키를 두고, 그 아래에 연결할 서버를 추가합니다. 각 서버는 이름을 키로 하고 command/args/env를 값으로 갖습니다. 아래는 DART 공시 MCP와 공공데이터 MCP를 동시에 붙이는 예시입니다.

{
  "mcpServers": {
    "dart": {
      "command": "npx",
      "args": ["-y", "dart-mcp-server"],
      "env": { "DART_API_KEY": "여기에_DART_키" }
    },
    "korea-public-data": {
      "command": "npx",
      "args": ["-y", "korea-public-data-mcp"],
      "env": { "DATA_GO_KR_KEY": "여기에_공공데이터_키" }
    }
  }
}

각 필드의 의미는 다음과 같습니다.

command — 서버를 실행하는 명령입니다. npm 패키지로 배포된 서버는 보통 npx로 실행합니다.
args — 실행 인자입니다. -y는 npx의 설치 확인 프롬프트를 건너뛰어, 패키지가 없으면 묻지 않고 바로 받아 실행합니다.
env — API 키처럼 서버가 요구하는 비밀값을 환경 변수로 주입합니다. 변수명(DART_API_KEY, DATA_GO_KR_KEY 등)은 서버마다 다르므로 각 서버 상세 페이지의 설치 탭에서 정확한 이름을 확인하세요.

서버를 하나만 붙일 거라면 위 예시에서 필요한 블록 하나만 남기면 됩니다. 서버를 더 추가할 때는 mcpServers 안에 같은 형식의 블록을 쉼표로 이어 붙입니다.

키 보관: API 키는 이 env 자리에만 넣고, 설정 파일을 외부 저장소나 공개 채널에 올리지 마세요. 팀과 설정을 공유해야 한다면 키 값만 빼고 공유한 뒤 각자 채워 넣는 편이 안전합니다.

3단계 — Claude Code 재시작

Claude Code는 시작할 때 설정 파일을 읽습니다. 따라서 파일을 저장한 뒤에는 실행 중인 세션을 종료하고 다시 실행해야 새 서버가 반영됩니다.

claude   # 새 세션 시작

4단계 — 연결 확인

세션 안에서 /mcp 명령을 입력하면 현재 연결된 MCP 서버와 각 서버가 제공하는 도구 목록이 보입니다. 서버가 정상이면 상태가 connected로 표시됩니다.

이제 자연어로 요청하면 Claude가 알맞은 도구를 알아서 호출합니다. 예를 들어:

“DART에서 삼성전자 최근 공시 찾아줘”

이렇게 입력하면 Claude가 dart 서버의 도구를 골라 실행하고 결과를 정리해 줍니다.

자주 막히는 지점

서버가 /mcp 목록에 안 보일 때 — JSON 문법 오류가 가장 흔한 원인입니다. 블록 사이 쉼표 누락, 따옴표 빠짐, 마지막 항목 뒤의 불필요한 쉼표를 점검하세요. 파일 전체가 유효한 JSON인지 확인하면 대부분 해결됩니다.
인증·권한 오류가 날 때 — env에 적은 변수명이 서버가 기대하는 이름과 정확히 일치해야 합니다. 대소문자·언더스코어까지 그대로여야 하며, 키 값 자체가 만료되거나 잘못 복사되지 않았는지도 확인하세요.
첫 실행이 느릴 때 — npx는 패키지가 로컬에 없으면 처음 한 번 다운로드합니다. 이때 연결까지 몇 초가 걸릴 수 있으니 잠시 기다리세요. 두 번째부터는 빨라집니다.
재시작을 빠뜨렸을 때 — 설정을 바꿨는데 변화가 없다면 세션을 완전히 종료했다 다시 켰는지 확인하세요. 기존 세션은 저장 시점의 설정을 계속 사용합니다.

자주 묻는 질문

claude mcp add로 추가하는 것과 무엇이 다른가요? 결과는 같지만 관리 방식이 다릅니다. CLI는 한 줄 명령으로 빠르게 붙이기 좋고, settings.json 직접 편집은 여러 서버 설정을 파일 하나에 모아 검토·공유·재현하기 좋습니다. 이 글은 후자를 다룹니다.

한 파일에 서버를 여러 개 둬도 되나요? 됩니다. mcpServers 안에 서버 블록을 원하는 만큼 나열하면 됩니다. 각 서버는 고유한 이름(키)을 가져야 합니다.

설정을 바꾼 뒤 매번 재시작해야 하나요? 네. Claude Code는 시작 시점에 설정을 읽으므로, settings.json을 수정했다면 세션을 다시 시작해야 반영됩니다.