Claude MCP 서버 여러 개 설정하기 — 개념부터 mcpServers 복수 등록·디버깅까지

MCP 서버를 하나만 쓰다가 두 번째, 세 번째 서버를 추가하고 싶어졌다면, 정답은 간단합니다. claude_desktop_config.json 파일의 mcpServers 객체 안에 항목을 나란히 추가하기만 하면 됩니다. 서버마다 고유한 이름(키)을 부여하고 쉼표로 구분하면 Claude Desktop이 시작할 때 모든 서버를 자동으로 실행합니다. 이 글에서는 MCP가 무엇인지 개념을 먼저 짚고, 설정 파일 위치 확인부터 복수 서버 등록, 자주 발생하는 오류 해결까지 한 번에 다룹니다.

MCP란 무엇인가 — 먼저 개념부터

MCP(Model Context Protocol)는 AI 모델이 외부 도구·파일·API와 표준화된 방식으로 통신하도록 Anthropic이 2024년 11월에 오픈 표준으로 공개한 프로토콜입니다. Claude뿐 아니라 MCP를 지원하는 다른 AI 클라이언트에서도 동일한 프로토콜을 사용할 수 있도록 오픈소스로 공개되어 있습니다.

AI 모델은 학습 당시의 지식만 갖고 있으므로, 실시간 데이터를 가져오거나 내 PC의 파일을 읽으려면 별도의 연결 수단이 필요합니다. 기존 방식과 비교하면 MCP의 위치가 분명해집니다.

방식	한계
Function Calling (OpenAI 등)	특정 플랫폼에 종속, 매번 도구를 API 요청에 포함해야 함
직접 API 호출 코드 작성	개발자 필수, 모델-도구 조합마다 별도 구현 필요

MCP는 이 문제를 서버-클라이언트 분리 구조로 해결합니다. MCP 서버(도구)를 한 번 만들면 MCP를 지원하는 모든 클라이언트(Claude Desktop, Cursor, Windsurf, VS Code 등)에서 재사용할 수 있습니다. 개발자는 도구 로직에만 집중하고, AI 클라이언트는 어떤 도구를 언제 쓸지 스스로 판단합니다.

MCP의 세 가지 구성 요소

구성 요소	역할	예시
MCP 호스트(클라이언트)	AI 모델을 실행하는 앱	Claude Desktop, Cursor, Claude Code
MCP 서버	외부 도구·데이터를 AI에 노출하는 프로세스	KorDoc, HWP-MCP, HwpForge
MCP 전송 계층	호스트-서버 간 통신 방식	stdio(로컬), HTTP+SSE(원격)

MCP 서버가 클라이언트에 노출하는 기능은 세 종류입니다.

• Tools(도구): AI가 호출할 수 있는 함수. 예: “이 한글 파일을 마크다운으로 변환해줘”
• Resources(리소스): AI가 읽을 수 있는 데이터. 예: 로컬 파일, 데이터베이스 레코드
• Prompts(프롬프트): 재사용 가능한 프롬프트 템플릿

전송 계층은 JSON-RPC 2.0을 기반으로 stdio(로컬) 또는 HTTP+SSE(원격) 위에서 동작합니다. 핵심은 로컬 실행입니다. stdio 방식 MCP 서버는 사용자 PC에서 직접 실행되므로 API 키나 민감한 파일 내용이 외부 서버로 유출될 위험이 없습니다. Claude 모델은 “어떤 도구를 호출할지”만 결정하고, 실제 도구 실행은 로컬 서버가 담당합니다. 단, 원격(HTTP) 방식 MCP 서버를 쓰는 경우에는 데이터가 해당 서버로 전달될 수 있습니다.

MCP 복수 서버가 필요한 이유

MCP 서버 하나는 보통 특정 도구나 데이터 소스 하나에 집중합니다. 예를 들어 한글 문서를 읽으려면 HWP 관련 서버가 필요하고, 웹 검색을 붙이려면 검색 서버가 따로 있습니다. 실무에서는 이런 서버를 동시에 활성화해야 Claude가 여러 작업을 한 세션에서 처리할 수 있습니다.

다행히 Claude Desktop과 Claude Code 모두 서버를 개수 제한 없이 등록할 수 있는 구조를 갖추고 있습니다. 핵심은 설정 파일의 mcpServers 객체 구조를 정확히 이해하는 것입니다.

설정 파일 위치 — 운영체제별 경로

운영체제	설정 파일 경로
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

파일이 없다면 Claude Desktop을 한 번 실행하면 자동 생성됩니다. 처음 생성 직후에는 내용이 비어 있거나 {} 형태일 수 있습니다.

mcpServers 블록의 구조 이해

mcpServers 는 JSON 최상위 키입니다. 그 안에 각 서버를 객체 키(서버 식별자) 로 구분하여 등록합니다.

{
  "mcpServers": {
    "서버-이름-A": {
      "command": "npx",
      "args": ["-y", "패키지명-A"]
    },
    "서버-이름-B": {
      "command": "npx",
      "args": ["-y", "패키지명-B"]
    }
  }
}

서버 식별자(키)는 Claude 내부에서 서버를 구분하는 이름입니다. 알파벳 소문자, 숫자, 하이픈(-) 조합을 권장하며, 같은 이름을 두 번 쓰면 뒤쪽 항목이 앞쪽을 덮어쓰므로 반드시 고유하게 지정해야 합니다.

단계별 설정 방법

1단계 — 설정 파일 열기

macOS 기준으로 터미널에서 파일을 직접 열거나, Finder에서 경로를 이동해 텍스트 편집기로 엽니다.

# macOS에서 VS Code로 열기
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

파일이 없거나 비어 있다면 아래 내용을 기본 골격으로 붙여넣으세요.

{
  "mcpServers": {}
}

2단계 — 첫 번째 MCP 서버 등록

mcpServers 객체 안에 첫 번째 서버 항목을 추가합니다. 아래는 한국 공문서(HWP·HWPX·PDF·XLSX·DOCX 등)를 Markdown으로 변환하는 코르독(KorDoc) 서버를 등록하는 예시입니다. API 키 없이 바로 쓸 수 있어 MCP 첫 경험에 적합합니다.

{
  "mcpServers": {
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "setup"]
    }
  }
}

참고: 코르독 GitHub 저장소는 https://github.com/chrisryugj/kordoc 입니다.

3단계 — 두 번째 서버 추가

첫 번째 항목 뒤에 쉼표(,) 를 붙이고 두 번째 서버를 이어서 작성합니다. 아래는 한글(.hwp/.hwpx) 문서를 AI가 직접 읽고 편집할 수 있게 해주는 HWP-MCP 서버를 함께 등록하는 예입니다.

{
  "mcpServers": {
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "setup"]
    },
    "hwp-mcp": {
      "command": "npx",
      "args": ["-y", "hwp-mcp"]
    }
  }
}

참고: HWP-MCP GitHub 저장소는 https://github.com/treesoop/hwp-mcp 입니다.

4단계 — 세 번째 이후 서버 계속 추가

같은 방식으로 서버를 계속 추가할 수 있습니다. 아래는 한글(HWPX) 문서를 AI 에이전트가 읽고 쓰고 변환할 수 있게 해주는 한포지(HwpForge)까지 세 서버를 동시에 등록한 완전한 예시입니다. 한포지는 한컴 한글 HWPX(KS X 6101) 표준을 지원합니다.

{
  "mcpServers": {
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "setup"]
    },
    "hwp-mcp": {
      "command": "npx",
      "args": ["-y", "hwp-mcp"]
    },
    "hwpforge": {
      "command": "npx",
      "args": ["-y", "@hwpforge/mcp"]
    }
  }
}

참고: 한포지 GitHub 저장소는 https://github.com/ai-screams/HwpForge 입니다.

5단계 — 저장 후 Claude Desktop 재시작

파일을 저장한 뒤 Claude Desktop을 완전히 종료하고 다시 실행합니다.

• macOS: 상단 메뉴바의 Claude 아이콘 → Quit, 또는 Cmd+Q
• Windows: 트레이 아이콘 우클릭 → 종료
• 재실행 후 채팅창 하단에 망치(도구) 아이콘이 나타나면 MCP 서버가 정상 연결된 것입니다. Claude 대화창에 “어떤 도구를 사용할 수 있나요?”라고 물어보면 등록된 서버 목록을 확인할 수 있습니다.

환경변수가 필요한 서버를 포함할 때

API 키가 필요한 서버는 각 항목에 env 키를 추가합니다. 서버마다 독립적인 환경변수 블록을 가질 수 있습니다.

{
  "mcpServers": {
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "setup"]
    },
    "my-api-server": {
      "command": "npx",
      "args": ["-y", "some-mcp-server"],
      "env": {
        "API_KEY": "여기에-실제-키-입력"
      }
    }
  }
}

이렇게 하면 kordoc 서버에는 환경변수가 전달되지 않고, my-api-server 에만 API_KEY 가 주입됩니다. env 항목의 키 이름은 각 MCP 서버 GitHub README에서 기대하는 환경 변수명과 정확히 일치해야 하며, 대소문자도 구분됩니다.

데이터 흐름 구조

복수 서버 등록 시 Claude Desktop이 어떻게 각 서버와 통신하는지 아래 다이어그램으로 확인하세요. 각 서버는 JSON-RPC 2.0 기반 MCP 프로토콜(stdio)로 독립 통신합니다.

Claude Desktop (클라이언트)
       │
       ├─── MCP 프로토콜 ───► kordoc 프로세스      (HWP·PDF → Markdown)
       │
       ├─── MCP 프로토콜 ───► hwp-mcp 프로세스     (한글 문서 읽기·편집)
       │
       └─── MCP 프로토콜 ───► hwpforge 프로세스    (HWPX 읽기·쓰기·변환)

각 서버는 독립적인 프로세스로 실행되므로, 한 서버에 오류가 생겨도 나머지 서버는 정상 동작합니다.

Claude Code(터미널 CLI)에서 설정하기

Claude Code를 사용한다면 명령어로 서버를 추가하거나, 프로젝트 루트의 .claude/settings.json 을 직접 편집합니다. 파일 구조는 claude_desktop_config.json과 동일합니다.

# Claude Code CLI로 서버 추가
claude mcp add kordoc npx -- -y kordoc setup
claude mcp add hwp-mcp npx -- -y hwp-mcp

명령어 실행 후 claude mcp list 로 등록된 서버 목록을 확인할 수 있습니다.

흔한 오류와 해결법

증상	원인	해결 방법
서버가 한 개도 인식 안 됨	JSON 문법 오류	파일을 JSON 검증기에 붙여넣어 오류 줄 확인
특정 서버만 인식 안 됨	키 이름 중복	모든 서버 키가 유일한지 확인
도구 아이콘이 안 보임 / “Tool not found”	Claude Desktop 구버전, 서버 프로세스 비정상 종료	최신 버전으로 업데이트 후 완전 재시작
서버 실행 중 오류 메시지	npx 패키지 미설치 또는 Node.js 버전	node --version 확인, LTS 버전 권장
npx 실행 “command not found”	Node.js 미설치 또는 PATH 미등록	https://nodejs.org 에서 LTS 설치 후 터미널 재시작
저장해도 변경이 반영 안 됨	Claude Desktop 미재시작	완전 종료 후 재실행
env 변수가 서버에 전달 안 됨	env 블록 위치·키 이름 오류	command와 같은 레벨에 env 키가 있는지, 키 이름이 README와 일치하는지 확인

JSON 문법에서 가장 흔한 실수는 마지막 항목 뒤에 쉼표를 붙이는 것입니다(trailing comma). 표준 JSON은 이를 허용하지 않으므로 마지막 항목 뒤에는 쉼표를 넣지 마세요.

{
  "mcpServers": {
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "setup"]
    }
  }
}

위에서 "setup"] 뒤 } 뒤 } 앞에 쉼표가 없는 것이 올바른 형태입니다.

자주 묻는 질문

MCP는 누가 만들었나요?

MCP(Model Context Protocol)는 Anthropic이 2024년 11월에 오픈 표준으로 공개했습니다. Claude뿐 아니라 다른 AI 클라이언트에서도 동일한 프로토콜을 사용할 수 있도록 오픈소스로 공개되어 있습니다.

Claude Desktop 없이도 MCP를 사용할 수 있나요?

네. MCP는 Claude Desktop 외에도 Cursor, Windsurf, VS Code 등 MCP를 지원하는 모든 클라이언트에서 사용할 수 있습니다. 각 클라이언트마다 설정 방법이 조금씩 다르지만 동일한 MCP 서버를 공유합니다.

MCP 서버는 직접 만들 수 있나요?

네. Anthropic이 공개한 MCP SDK(Python·TypeScript)를 사용하면 누구나 MCP 서버를 만들 수 있습니다. 기존 REST API나 로컬 데이터베이스를 감싸는 서버를 만들어 Claude에 연결하는 것이 일반적인 방식입니다.

MCP와 함수 호출(Function Calling)의 차이는 무엇인가요?

Function Calling은 특정 AI 플랫폼에 종속된 방식으로, 개발자가 API 요청마다 도구를 정의해야 합니다. MCP는 서버-클라이언트 구조로 분리되어 있어 한 번 만든 MCP 서버를 여러 클라이언트에서 재사용할 수 있고, 표준 프로토콜로 상호운용성이 높습니다.

MCP 서버는 몇 개까지 등록할 수 있나요?

공식 상한선은 없습니다. 다만 서버가 많아질수록 Claude 시작 시간이 느려질 수 있으므로, 실제로 사용하는 서버만 등록하는 것이 좋습니다.

서버 이름(키)에 중복이 있으면 어떻게 되나요?

JSON에서 동일 키가 두 번 나오면 마지막 값이 덮어씁니다. 각 서버에 고유한 이름을 부여해야 두 서버 모두 등록됩니다.

npx 방식과 uvx 방식 서버를 혼합해도 되나요?

네, 됩니다. mcpServers 블록 안에서 각 항목은 독립적으로 실행되므로 npx 서버와 uvx 서버를 함께 등록해도 충돌하지 않습니다.

MCP 서버를 사용하면 개인 데이터가 외부로 나가나요?

대부분의 MCP 서버는 사용자 PC에서 로컬로 실행(stdio 방식)됩니다. 민감한 API 키나 파일 내용이 Anthropic 서버로 전송되는 것이 아니라, Claude 모델이 어떤 도구를 어떻게 호출할지 결정하는 부분만 처리됩니다. 단, 원격(HTTP) 방식 MCP 서버를 사용하는 경우에는 데이터가 해당 서버로 전달될 수 있습니다.

MCP 서버는 무료인가요?

MCP 서버 자체는 대부분 오픈소스(GitHub)로 무료 제공됩니다. 다만 서버가 연결하는 외부 API는 각각의 요금 정책을 따릅니다. Claude 사용 비용은 Claude API 또는 Claude.ai 구독 요금에 따릅니다.

Claude Code(터미널 CLI)에서도 같은 방법으로 설정하나요?

Claude Code는 claude mcp add 명령어로 서버를 추가하거나 .claude/settings.json 파일의 mcpServers 블록을 직접 편집합니다. 구조는 claude_desktop_config.json과 동일합니다.

다음 단계

복수 서버 설정에 익숙해졌다면, devtools 카테고리에서 업무에 맞는 MCP 서버를 더 찾아보세요. 한글 문서 작업이 많다면 코르독(KorDoc), HWP-MCP, 한포지(HwpForge)를 함께 등록하면 Claude가 HWP·HWPX·PDF·DOCX 파일을 모두 처리할 수 있게 됩니다.

새로운 MCP 서버를 발견했다면 MCP모아 전체 서버 목록에서 검색하거나, 직접 서버를 등록해 커뮤니티와 공유해 주세요.