MCP를 쓰기 위한 첫 환경 구성

2026-09-15Views 13약 8분생성형 AI 활용

Summary

설정을 끝내야 MCP가 보인다

MCP는 설명만 들으면 추상적입니다. 호스트, 클라이언트, 서버라는 말도 실제 화면에서 서버 하나를 연결해 보기 전까지는 잘 와닿지 않습니다. 이번 장의 목표는 단순합니다. 대표적인 MCP Host에서 기존 MCP 서버 하나를 연결하고, 설정 파일의 기본 문법을 읽을 수 있게 되는 것입니다.

처음부터 거창한 서버를 붙일 필요는 없습니다. API 키가 필요 없는 서버나, 권한 범위가 작은 서버로 시작하는 편이 좋습니다. 예를 들어 브라우저 자동화용 Playwright MCP 서버, 읽기 전용 문서 서버, 테스트용 로컬 서버가 적당합니다. 중요한 것은 "AI 앱이 외부 기능 목록을 발견하고, 필요할 때 호출한다"는 흐름을 내 컴퓨터에서 직접 확인하는 일입니다.

MCP를 쓰기 위한 첫 환경 구성 AI 생성 이미지

MCP 설정은 어디에서 찾는가

MCP 설정 위치는 Host마다 다릅니다. 하지만 공통점이 있습니다. 대부분의 Host는 "MCP 서버 목록"을 JSON 설정 파일이나 설정 화면으로 관리합니다.

Host	설정을 찾는 대표 경로	주로 쓰는 설정 파일
Claude Desktop	`Settings > Developer > Edit Config`	`claude_desktop_config.json`
Cursor	`Settings > MCP` 또는 프로젝트 설정	`~/.cursor/mcp.json`, `.cursor/mcp.json`
VS Code 계열	Command Palette의 `MCP: Add Server`, `MCP: Open User Configuration`, Extensions의 `@mcp` 검색	사용자 `mcp.json`, 워크스페이스 `.vscode/mcp.json`

Claude Desktop은 개발자 설정에서 Edit Config를 누르면 claude_desktop_config.json을 열어 MCP 서버 설정을 추가하는 방식이 기본 흐름입니다. 저장한 뒤에는 앱을 완전히 종료하고 다시 열어야 새 설정이 반영됩니다.¹

VS Code는 조금 더 IDE답게 동작합니다. 명령 팔레트에서 MCP: Add Server를 실행하거나, Extensions 화면에서 @mcp로 서버를 찾아 설치할 수 있습니다. 워크스페이스 단위로 설치하면 .vscode/mcp.json에 설정이 들어갑니다. 사용자 전체에 적용하려면 사용자 설정의 mcp.json을 엽니다.²

Cursor는 전역 설정과 프로젝트 설정을 나눠 생각하면 쉽습니다. 모든 프로젝트에서 쓸 서버는 ~/.cursor/mcp.json에 두고, 특정 프로젝트에서만 쓸 서버는 .cursor/mcp.json에 둡니다. GitHub MCP 서버 설치 문서도 이 두 범위를 구분해 설명합니다.³

도구마다 메뉴 이름은 조금씩 바뀔 수 있습니다. 그래도 찾는 키워드는 같습니다. MCP, Server, Tools, Connectors, Developer, mcp.json입니다.

첫 예제: 로컬 MCP 서버 연결하기

가장 흔한 방식은 Host가 내 컴퓨터에서 MCP 서버 프로세스를 직접 실행하는 구조입니다. 이를 보통 stdio 방식이라고 부릅니다. 표준 입력과 표준 출력으로 Host와 Server가 메시지를 주고받는다는 뜻입니다.

예를 들어 Playwright MCP 서버는 Node.js 기반 서버입니다. Playwright 공식 문서는 Node.js 18 이상과 MCP 클라이언트를 준비한 뒤 npx로 서버를 실행하는 구성을 안내합니다.⁴

Claude Desktop 계열 설정은 보통 다음 모양입니다.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

VS Code의 .vscode/mcp.json에서는 최상위 키가 다릅니다. mcpServers가 아니라 servers를 씁니다. 또한 서버 타입을 명시하는 편이 좋습니다.

{
  "servers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  },
  "inputs": []
}

Cursor에서는 다음처럼 mcpServers 구조를 자주 사용합니다.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

여기서 핵심은 JSON 키 이름을 외우는 것이 아닙니다. 같은 서버라도 Host마다 감싸는 형식이 조금씩 다르다는 사실을 아는 것입니다. 서버 문서에 "Claude용 설정"만 나와 있어도, 구조를 이해하면 VS Code나 Cursor 설정으로 옮길 수 있습니다.

command, args, env의 의미

MCP 설정을 읽을 때 가장 먼저 볼 필드는 세 가지입니다.

command는 서버를 실행할 명령입니다. npx, node, python, uvx, docker 같은 실행 파일이 들어갑니다. Host는 이 명령을 실행해 MCP 서버 프로세스를 띄웁니다.

args는 그 명령에 넘기는 인자 목록입니다. 터미널에서 다음처럼 실행한다고 생각하면 됩니다.

npx @playwright/mcp@latest

이 명령은 JSON에서는 이렇게 쪼개집니다.

{
  "command": "npx",
  "args": ["@playwright/mcp@latest"]
}

Docker 기반 서버라면 구조가 더 길어질 수 있습니다.

{
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "ghcr.io/example/example-mcp-server"
  ]
}

env는 서버 프로세스에 주입할 환경변수입니다. API 키, 토큰, 프로젝트 ID처럼 코드에 직접 쓰면 안 되는 값을 넣을 때 사용합니다.

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

환경변수 이름은 대소문자를 구분합니다. GITHUB_TOKEN과 GITHUB_PERSONAL_ACCESS_TOKEN은 다른 이름입니다. 서버 문서가 요구하는 이름을 그대로 써야 합니다.

가능하면 토큰은 최소 권한으로 발급하세요. 읽기만 필요한 서버에 쓰기 권한을 줄 필요는 없습니다. 테스트가 끝난 토큰은 폐기하고, 팀원이 보는 저장소에 실제 토큰이 들어간 mcp.json을 커밋하지 마세요.

로컬 서버와 원격 서버의 차이

MCP 서버 연결은 크게 두 종류로 나뉩니다.

첫째, 로컬 서버입니다. Host가 내 컴퓨터에서 명령을 실행합니다. command, args, env가 중심입니다. 파일 시스템 접근, 로컬 개발 도구, Docker 컨테이너, 사내 VPN 안에서만 접근 가능한 도구를 붙일 때 자주 씁니다.

둘째, 원격 서버입니다. 이미 어딘가에서 실행 중인 MCP 서버에 URL로 접속합니다. 이때는 command 대신 url, headers, OAuth 설정 같은 값이 중요해집니다. VS Code는 HTTP 또는 SSE 방식의 원격 MCP 서버 설정을 지원하며, 서버 URL과 인증 헤더를 설정할 수 있습니다.²

예를 들어 Cursor에서 원격 GitHub MCP 서버를 연결하는 설정은 다음처럼 URL과 헤더 중심으로 구성될 수 있습니다.³

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_GITHUB_PAT"
      }
    }
  }
}

로컬 방식은 시작하기 쉽고 디버깅하기 좋습니다. 하지만 내 컴퓨터에 Node.js, Python, Docker 같은 실행 환경이 필요합니다. 원격 방식은 설치 부담이 작고 팀 단위 운영에 유리합니다. 대신 인증, 네트워크, 서버 운영 상태를 함께 봐야 합니다.

시작 전 준비물

처음 MCP 서버를 붙이기 전 다음을 확인하세요.

Node.js: npx 기반 서버에 필요합니다. 터미널에서 node --version으로 확인합니다.
Python: Python 기반 서버에 필요합니다. python --version 또는 python3 --version으로 확인합니다.
패키지 매니저: Node 서버는 npm, npx, Python 서버는 pip, uv, uvx를 쓰는 경우가 많습니다.
Docker Desktop: Docker 이미지로 배포되는 MCP 서버를 실행할 때 필요합니다.
API 키와 토큰: GitHub, Slack, Notion, Supabase 같은 외부 서비스를 연결할 때 필요합니다.
접근 권한: 로컬 폴더, 회사 네트워크, 사내 API, 브라우저 자동화 권한을 확인해야 합니다.

처음에는 API 키가 필요 없는 서버로 성공 경험을 만드는 편이 좋습니다. 그다음 GitHub나 Slack처럼 인증이 필요한 서버로 넘어가세요. 인증이 필요한 서버부터 시작하면 MCP 문제인지, 토큰 문제인지, 네트워크 문제인지 구분하기 어렵습니다.

연결 실패 시 확인 순서

MCP 연결이 실패하면 무작정 설정을 바꾸지 말고 순서대로 좁혀 가야 합니다.

1. 설정 파일 위치를 확인합니다.
Claude Desktop 설정을 Cursor 파일에 넣었거나, 프로젝트 설정에 넣어야 할 내용을 사용자 설정에 넣은 경우가 많습니다.

2. JSON 문법을 확인합니다.
쉼표 하나가 잘못되어도 전체 설정이 무시될 수 있습니다. 특히 마지막 항목 뒤의 쉼표, 따옴표 누락, 중괄호 짝을 확인하세요.

3. Host를 재시작합니다.
MCP Host는 시작할 때 설정을 읽고 서버를 띄우는 경우가 많습니다. Claude Desktop은 창만 닫지 말고 앱을 완전히 종료한 뒤 다시 실행하세요. VS Code나 Cursor도 창 새로고침 또는 완전 재시작이 더 확실합니다.

4. command를 터미널에서 직접 실행합니다.
설정에 다음이 있다면,

{
  "command": "npx",
  "args": ["@playwright/mcp@latest"]
}

터미널에서 직접 실행해 봅니다.

npx @playwright/mcp@latest

여기서 실패하면 MCP Host 문제가 아닙니다. Node.js 설치, 패키지 이름, 네트워크, 권한 문제부터 해결해야 합니다.

5. 경로와 권한을 확인합니다.
파일 서버를 붙일 때 상대 경로보다 절대 경로가 안전합니다. macOS나 Windows에서는 앱에 폴더 접근 권한이 없어서 실패할 수 있습니다. Docker를 쓴다면 Docker Desktop이 실행 중인지, 컨테이너가 백그라운드 분리 모드로 실행되지 않는지도 확인하세요. MCP의 stdio 서버는 Host와 입출력을 주고받아야 하므로 프로세스가 앞에서 실행되어야 합니다.

6. 환경변수를 확인합니다.
env에 들어간 토큰 이름이 서버 문서와 같은지 봅니다. 값 앞뒤에 공백이 들어가지 않았는지도 확인하세요. 모든 Host가 .env 파일을 자동으로 읽는다고 가정하면 안 됩니다. VS Code처럼 envFile을 지원하는 도구도 있지만, 기본은 Host의 MCP 설정에 명시된 env가 서버 프로세스로 전달된다고 이해하는 편이 안전합니다.²

7. 로그를 봅니다.
VS Code에서는 MCP: List Servers에서 서버를 고른 뒤 Output을 볼 수 있고, Chat 화면의 오류 표시에서도 로그로 이동할 수 있습니다.² Claude Desktop은 Developer 또는 Advanced 설정에서 연결 상태와 로그를 확인하는 흐름을 제공합니다.¹ 로그에서 볼 키워드는 failed, ENOENT, permission, unauthorized, missing environment variable, tools/list입니다.

첫 환경 구성의 기준

첫 MCP 환경 구성은 많은 서버를 붙이는 것이 목표가 아닙니다. 기준은 세 가지입니다.

첫째, Host 안에서 서버가 연결됨으로 표시되어야 합니다. 둘째, 도구 목록이 보여야 합니다. 셋째, 간단한 요청으로 도구 호출이 실제 실행되어야 합니다.

이 세 가지가 되면 MCP는 더 이상 그림 속 구조가 아닙니다. 내 AI 앱이 외부 도구를 발견하고, 권한을 확인하고, 필요한 기능을 호출하는 업무 환경이 됩니다. 다음 장부터는 이 환경 위에서 어떤 MCP 서버를 고를지, 안전한 서버와 위험한 서버를 어떻게 구분할지 살펴보겠습니다.

참고

¹Get started with MCP Apps

²MCP configuration reference

³GitHub MCP Server Cursor installation guide

⁴Playwright MCP

책 목록

MCP: AI 에이전트 연결의 표준

전체 목차 보기