MCP 설정 파일 완전 가이드 — 클라이언트별 형식·경로·전송 방식

업데이트 2026-07-11 · 클라이언트 설정 스키마는 빠르게 변할 수 있어 참고용입니다.

1. MCP(Model Context Protocol)란

MCP(Model Context Protocol)는 Claude Desktop·Cursor·VS Code·Windsurf 같은 AI 앱이 외부 도구와 데이터에 연결하도록 하는 개방형 표준입니다. 파일시스템, 데이터베이스, GitHub, Slack 같은 기능을 "MCP 서버"라는 작은 프로그램으로 노출하면, AI 클라이언트가 이 서버들을 실행하거나 원격으로 접속해 도구를 사용합니다.

클라이언트는 어떤 서버를 켤지 JSON 설정 파일로 지정합니다. 문제는 이 설정 파일의 위치와 형식이 클라이언트마다 조금씩 다르다는 점입니다. 쉼표 하나, 따옴표 하나만 틀려도 서버 전체가 로드되지 않기 때문에, "설정을 그대로 붙여넣었는데 서버가 안 붙는다"는 경험이 매우 흔합니다. 이 가이드는 그 차이를 정확히 정리합니다.

2. 전송 방식 — stdio · SSE · HTTP

MCP 서버는 크게 두 종류로 나뉩니다.

• stdio(로컬 프로세스): 내 컴퓨터에서 명령을 실행해 표준 입출력으로 통신합니다.command(예: npx, uvx, node)와args(인자 배열), 필요하면 env(환경변수)를 지정합니다. 대부분의 공식 서버가 이 방식입니다.
• 원격(SSE / HTTP): 이미 어딘가에서 돌고 있는 서버에 url로 접속합니다. SSE(Server-Sent Events)와 스트리밍 HTTP 두 가지 프로토콜이 있으며, 호스팅형 서버(예: Sentry의 원격 MCP)가 여기에 해당합니다.

같은 서버라도 클라이언트에 따라 원격 서버를 표현하는 키가 다릅니다. 아래 3~6절에서 하나씩 봅니다.

3. Claude Desktop — claude_desktop_config.json

Claude Desktop은 최상위 키가 mcpServers이며, stdio 서버에 type 필드가 필요 없습니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Desktop"]
    }
  }
}

설정 파일 위치:

• 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은 원격 서버를 직접 지원하지 않으므로, SSE/HTTP 서버는 npx mcp-remote <url> 프록시(stdio)로 감싸서 연결합니다. 이 도구는 원격 서버를 고르면 Claude 탭에서 자동으로 mcp-remote 형태로 변환해 줍니다.

4. Cursor — .cursor/mcp.json

Cursor도 최상위 키가 mcpServers이고 type 필드가 없지만, 원격 서버를 직접 지원합니다. 원격은 url 키를 씁니다.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
    },
    "sentry": {
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

• 프로젝트 전용: 저장소 루트의 .cursor/mcp.json
• 전역: ~/.cursor/mcp.json

5. VS Code — .vscode/mcp.json (다른 형식)

VS Code(GitHub Copilot의 에이전트 모드)는 형식이 가장 다릅니다. 최상위 키가mcpServers가 아니라 servers이며, 각 서버에 type필드를 명시해야 합니다.

{
  "servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Desktop"]
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

• 워크스페이스 전용: .vscode/mcp.json (위 형식 그대로)
• 사용자 settings.json: 넣을 때는 "mcp": { "servers": { ... } }처럼 mcp 키 안에 중첩합니다.

type은 stdio 서버에 "stdio", 원격 서버에 "http" 또는"sse"를 씁니다. 이 필드를 빠뜨리면 VS Code가 서버를 인식하지 못합니다.

6. Windsurf — mcp_config.json

Windsurf(Cascade)는 최상위 키가 mcpServers이고 stdio는 다른 클라이언트와 같지만, 원격 서버에 url이 아니라 serverUrl 키를 씁니다.

{
  "mcpServers": {
    "sentry": {
      "serverUrl": "https://mcp.sentry.dev/mcp"
    }
  }
}

설정 파일 위치는 ~/.codeium/windsurf/mcp_config.json이며,Settings → Cascade → MCP Servers에서 편집할 수 있습니다.

7. 클라이언트별 차이 한눈에 보기

8. 인기 MCP 서버 설정 예시

• filesystem: npx -y @modelcontextprotocol/server-filesystem /허용/경로 — 마지막 인자가 접근 허용 디렉터리입니다.
• github: npx -y @modelcontextprotocol/server-github + env.GITHUB_PERSONAL_ACCESS_TOKEN.
• postgres: npx -y @modelcontextprotocol/server-postgres postgresql://localhost/db — 읽기 전용.
• sqlite / fetch / git: Python 기반 uvx 서버 (예: uvx mcp-server-fetch).
• brave-search / slack: API 키·봇 토큰을 env로 넘깁니다.

9. 서버가 안 붙을 때 체크리스트

• JSON 문법: 끝 쉼표, 빠진 따옴표, 안 맞는 중괄호. 이 도구로 생성하면 구조는 항상 정확합니다.
• 클라이언트 형식: VS Code는 servers + type인지, Windsurf는 serverUrl인지 확인.
• 파일 위치: 위 경로가 정확한지, 앱 재시작을 했는지.
• 실행 파일: npx/uvx가 PATH에 있는지, 절대 경로가 필요한 OS인지.
• 권한/토큰: env의 토큰이 유효하고 필요한 스코프를 가졌는지.