mcp.json 설정 완전 해설 — mcpServers 구조와 환경변수 작성법
mcp.json 설정 파일의 mcpServers 구조, 환경변수 작성법, 자주 발생하는 오류 해결법을 예시와 함께 완전 해설합니다. MCP 설정 파일 위치와 작성 방법을 한 번에 파악하세요.
mcp.json(또는 Claude Desktop의 경우 claude_desktop_config.json) 하나만 제대로 이해하면 어떤 MCP 서버든 연결할 수 있습니다. 이 글은 mcpServers 객체의 필드별 의미, 환경변수 작성 패턴, 클라이언트별 파일 위치, 그리고 자주 마주치는 오류와 해결법을 한 번에 정리합니다. MCP 설정 파일이 어떻게 작동하는지 전체 구조를 파악하고 나면, 어떤 서버를 추가하더라도 공식 README만 보고 바로 적용할 수 있게 됩니다.
MCP 설정 파일이 필요한 이유
MCP(Model Context Protocol)는 AI 클라이언트가 외부 도구나 데이터 소스를 표준화된 방식으로 호출할 수 있게 해주는 프로토콜입니다. Claude Desktop, Cursor, Claude Code 같은 클라이언트는 어떤 MCP 서버를 어떻게 실행할지 알아야 하는데, 그 정보를 담은 파일이 바로 설정 파일입니다.
클라이언트가 시작될 때 설정 파일을 읽고, mcpServers에 등록된 서버들을 자식 프로세스(stdio 방식) 또는 원격 연결(SSE/HTTP 방식)로 구동합니다. 이 파일을 올바르게 작성하지 않으면 서버가 아예 뜨지 않거나, 실행은 되지만 도구 목록이 빈 상태로 표시되는 문제가 생깁니다.
클라이언트별 설정 파일 위치
| 클라이언트 | macOS / Linux | Windows |
|---|---|---|
| Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | %APPDATA%\Claude\claude_desktop_config.json |
| Cursor (글로벌) | ~/.cursor/mcp.json | %APPDATA%\Cursor\mcp.json |
| Cursor (프로젝트) | {프로젝트 루트}/.cursor/mcp.json | 동일 |
| Claude Code | {프로젝트 루트}/.mcp.json | 동일 |
| VS Code (MCP 확장) | ~/.vscode/mcp.json | %APPDATA%\Code\mcp.json |
프로젝트 루트의 설정이 글로벌 설정보다 우선 적용되는 클라이언트가 많으니, 팀 프로젝트에서는 .gitignore에 설정 파일을 추가해 API 키가 공개 저장소에 올라가지 않도록 주의하세요.
mcp.json 기본 구조
설정 파일의 최상위 구조는 간단합니다. mcpServers 객체 하나가 핵심입니다.
{
"mcpServers": {
"서버-식별자": {
"command": "실행_명령",
"args": ["인수1", "인수2"],
"env": {
"환경변수명": "값"
}
}
}
}
각 필드의 역할을 아래 표로 정리했습니다.
| 필드 | 필수 여부 | 설명 |
|---|---|---|
command | 필수 | 서버를 실행할 명령어 (npx, uvx, node, python 등) |
args | 선택 | command에 전달할 인수 배열 |
env | 선택 | 서버 프로세스에 주입할 환경변수 객체 |
url | SSE 방식만 | 원격 서버 엔드포인트 URL (command 대신 사용) |
npx 서버 등록 방법
Node.js 기반 MCP 서버 대부분은 npx로 실행합니다. 설치 없이 패키지를 바로 실행하는 방식이라 관리가 편합니다.
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"]
},
"hwp-mcp": {
"command": "npx",
"args": ["-y", "hwp-mcp"]
},
"hwpforge": {
"command": "npx",
"args": ["-y", "@hwpforge/mcp"]
}
}
}
args의 -y 플래그는 npx가 패키지 설치 여부를 묻는 프롬프트를 건너뛰게 합니다. 클라이언트가 자동으로 서버를 실행할 때 사용자 입력을 기다리면 안 되므로 반드시 포함해야 합니다.
위 세 서버는 코르독(KorDoc), HWP-MCP, 한포지(HwpForge)로, 모두 한글 문서 처리에 특화된 MCP 서버입니다. API 키가 필요 없어 env 필드 없이 바로 사용할 수 있습니다.
uvx 서버 등록 방법
Python 기반 서버는 주로 uvx를 사용합니다. uv 패키지 관리자가 설치되어 있어야 합니다.
{
"mcpServers": {
"my-python-server": {
"command": "uvx",
"args": ["패키지명"],
"env": {
"API_KEY": "your-api-key"
}
}
}
}
환경변수(env) 작성 패턴
API 키나 토큰이 필요한 서버는 env 필드에 환경변수를 지정합니다.
{
"mcpServers": {
"some-api-server": {
"command": "npx",
"args": ["-y", "some-mcp-package"],
"env": {
"SOME_API_KEY": "sk-xxxxxxxxxxxxxxxx",
"SOME_BASE_URL": "https://api.example.com/v1",
"LOG_LEVEL": "info"
}
}
}
}
환경변수 이름은 대문자와 밑줄을 사용하는 관례(SCREAMING_SNAKE_CASE)가 일반적입니다. 값은 문자열이어야 하며, 숫자도 큰따옴표로 감싸야 합니다.
보안 주의: API 키가 포함된 설정 파일은 절대 공개 저장소에 올리면 안 됩니다. 팀 작업 시에는 .env 파일과 OS 환경변수를 활용하고, 설정 파일 자체는 .gitignore에 추가하세요.
원격(SSE/HTTP) 서버 등록 방법
로컬 프로세스가 아닌 원격으로 운영되는 MCP 서버는 url 필드를 사용합니다.
{
"mcpServers": {
"remote-server": {
"url": "https://mcp.example.com/sse",
"headers": {
"Authorization": "Bearer your-token"
}
}
}
}
command 대신 url을 쓰면 클라이언트는 해당 엔드포인트로 SSE 연결을 맺습니다. 인증 헤더가 필요하면 headers 필드에 추가합니다.
데이터 흐름 구조
설정 파일이 어떻게 동작하는지 전체 흐름을 ASCII 다이어그램으로 표현하면 다음과 같습니다.
[Claude Desktop / Cursor / Claude Code]
|
| mcp.json 읽기
v
[mcpServers 파싱]
|
┌────┴─────────────────┐
| |
v v
[npx -y kordoc setup] [npx -y hwp-mcp]
(stdio 프로세스) (stdio 프로세스)
| |
v v
[KorDoc 도구 목록] [HWP-MCP 도구 목록]
| |
└────────┬─────────────┘
|
v
[AI 어시스턴트 도구 팔레트]
→ 사용자 요청 시 해당 도구 호출
서버를 여러 개 등록할 때 알아둘 점
MCP 구성 요소와 설정 파일의 관계
설정 파일은 MCP 호스트(Claude Desktop, Cursor, Claude Code 같은 클라이언트)가 어떤 MCP 서버를 어떤 전송 방식으로 띄울지 적어 두는 곳입니다. 서버가 호스트에 노출하는 기능은 Tools(AI가 호출하는 함수), Resources(AI가 읽는 데이터), Prompts(재사용 프롬프트 템플릿) 세 가지입니다. 로컬 서버는 stdio로, 원격 서버는 HTTP 계열 방식으로 연결되며, 설정 파일의 command 방식과 url 방식이 각각 여기에 대응합니다.
서버 식별자는 고유해야 합니다
mcpServers 아래의 키는 클라이언트 안에서 서버를 구분하는 이름입니다. JSON에서 같은 키를 두 번 쓰면 뒤쪽 항목이 앞쪽을 덮어쓰므로, 서버를 추가했는데 기존 서버가 사라졌다면 키 이름이 겹치지 않았는지 먼저 확인하세요. 서버가 늘어날수록 역할이 드러나는 이름을 붙여 두면 관리가 쉽습니다.
env 블록은 서버마다 독립적입니다
각 서버 항목에 둔 env는 그 서버 프로세스에만 전달됩니다. 키가 필요 없는 서버에는 env를 생략해도 되며, API 키가 필요한 서버에만 해당 서버의 README가 요구하는 변수명을 그대로 적습니다. 변수명은 대소문자를 구분하므로 README 표기와 정확히 일치해야 합니다.
Linux 경로와 Claude Desktop
Claude Desktop 설정 파일은 macOS와 Windows 경로가 널리 알려져 있고, Linux에서는 보통 홈 디렉터리의 .config 아래 Claude 폴더에서 찾습니다. 파일이 아직 없다면 앱을 한 번 실행하면 만들어지는 경우가 있으니, 없을 때는 직접 만들기 전에 앱을 먼저 실행해 보세요. 경로는 버전에 따라 달라질 수 있어 앱 문서로 확인하는 편이 안전합니다.
Claude Code는 명령어로도 등록할 수 있습니다
Claude Code에서는 claude mcp add 명령어로 서버를 추가하거나 프로젝트 루트의 .mcp.json을 직접 편집합니다. mcpServers 구조는 Claude Desktop의 설정 파일과 같습니다. .claude/settings.json은 서버 정의를 넣는 파일이 아니므로 여기에 mcpServers를 적어도 서버가 등록되지 않습니다.
# Claude Code CLI로 서버 추가
claude mcp add kordoc npx -- -y kordoc mcp
claude mcp add hwp-mcp npx -- -y hwp-mcp
# 등록된 서버 확인
claude mcp list
마지막 항목 뒤 쉼표(trailing comma)
JSON 문법 오류 중 가장 흔한 것이 마지막 항목 뒤에 쉼표를 붙이는 실수입니다. 표준 JSON은 이를 허용하지 않아 파일 전체가 파싱되지 않고, 그러면 서버가 한 개도 인식되지 않는 증상으로 나타납니다. 서버를 복사해 붙일 때 쉼표가 남지 않았는지 마지막 줄을 꼭 확인하세요.
자주 발생하는 오류와 해결법
오류 1: “Server failed to start” 또는 서버가 도구 목록에 없음
원인: command가 PATH에 없거나, args의 패키지명이 잘못됨.
해결:
- 터미널에서 동일한 명령을 직접 실행해 에러 메시지 확인
npx -y kordoc mcp
- Node.js와 npm이 설치되어 있는지 확인
node --version
npm --version
- 클라이언트를 완전 종료 후 재시작
오류 2: JSON 파싱 실패
원인: 설정 파일에 문법 오류(쉼표 누락, 따옴표 불일치 등).
해결: JSON 유효성 검사 도구로 파일을 확인합니다.
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool
오류 줄 번호와 메시지가 출력됩니다. 흔한 실수는 마지막 항목 뒤에 쉼표를 붙이는 것(trailing comma)인데, 표준 JSON은 이를 허용하지 않습니다.
오류 3: 환경변수 인식 안 됨
원인: env 필드의 값이 문자열이 아니거나, 오타.
해결: 모든 값을 큰따옴표로 감싸고, 키 이름을 서버 README와 대조해 확인합니다.
"env": {
"PORT": "3000"
}
숫자처럼 보여도 JSON에서는 문자열로 넘겨야 합니다.
오류 4: 권한 오류 (EACCES)
원인: npx 캐시 또는 글로벌 node_modules 권한 문제.
해결: npx 캐시를 삭제하고 다시 실행합니다.
npm cache clean --force
여러 서버를 한 번에 등록하는 예시
실제 사용 환경에서 여러 서버를 등록하는 완성된 예시입니다.
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"]
},
"hwp-mcp": {
"command": "npx",
"args": ["-y", "hwp-mcp"]
},
"hwpforge": {
"command": "npx",
"args": ["-y", "@hwpforge/mcp"]
}
}
}
각 서버는 독립된 프로세스로 실행되므로 서로 충돌하지 않습니다. 클라이언트 UI에서는 각 서버의 도구 목록이 합쳐져 하나의 팔레트처럼 보입니다.
자주 묻는 질문
mcp.json 파일은 어디에 있나요?
클라이언트마다 위치가 다릅니다. Claude Desktop은 macOS 기준 ~/Library/Application Support/Claude/claude_desktop_config.json, Windows는 %APPDATA%\Claude\claude_desktop_config.json입니다. Cursor는 프로젝트 루트의 .cursor/mcp.json 또는 글로벌 ~/.cursor/mcp.json을 사용합니다. Claude Code는 프로젝트 루트의 .mcp.json을 우선 읽습니다.
mcpServers 키 이름은 자유롭게 지어도 되나요?
네, mcpServers 아래의 키(예: my-server, kordoc)는 클라이언트 UI에 표시될 이름이며 임의로 지정할 수 있습니다. 단, 영문 소문자·하이픈·숫자 조합을 권장하며 특수문자는 피하는 것이 안전합니다.
환경변수를 설정 파일에 직접 써도 되나요?
소규모 개인 사용 시에는 env 필드에 직접 작성해도 동작하지만, API 키 등 민감한 값은 가능하면 OS 환경변수나 별도 시크릿 관리 도구를 활용하고 설정 파일은 버전 관리에서 제외(.gitignore)하는 것을 권장합니다.
mcp.json을 수정한 뒤 바로 반영되나요?
대부분의 클라이언트는 파일을 수정한 후 앱을 재시작해야 변경사항이 반영됩니다. Claude Desktop은 완전 종료 후 재실행이 필요하고, Cursor는 창 새로고침으로 반영할 수 있습니다.
npx로 실행하는 서버와 uvx로 실행하는 서버의 설정이 다른가요?
command 필드 값만 다릅니다. npx 서버는 command를 "npx", args 첫 번째 요소를 "-y"로 시작하고, uvx 서버는 command를 "uvx"로 지정합니다. env 필드는 두 방식 모두 동일하게 사용합니다.
여러 MCP 서버를 동시에 등록할 수 있나요?
네, mcpServers 객체 안에 서버 항목을 여러 개 나열하면 됩니다. 클라이언트는 시작할 때 등록된 모든 서버를 병렬로 구동하므로 서버 개수에 원칙적인 제한은 없지만, 메모리와 시작 속도를 고려해 실제로 사용하는 서버만 등록하는 것이 좋습니다.
다음 단계
mcp.json 구조를 이해했다면 이제 실제 서버를 연결해 볼 차례입니다. 한글 문서 작업이 많다면 코르독(KorDoc), HWP-MCP, 한포지(HwpForge) 세 서버가 좋은 시작점입니다. 더 많은 한국산 MCP 서버는 개발 도구 카테고리에서 찾아볼 수 있으며, 전체 서버 목록은 MCP 서버 디렉토리에서 확인하세요. 직접 만든 서버가 있다면 등록 신청을 통해 MCP모아에 추가할 수도 있습니다.