책에 포함된 노트MCP, 진짜로 써먹는 법: 연결부터 서버 제작, 운영까지

사용자 관점 입문: Claude, VS Code, Cursor에서 MCP 붙이기

2026-03-30Views 21약 10분

MCP, 이제 구경 말고 연결해 보자

앞 장들에서 MCP를 개념으로 이해했다면, 이제는 손에 잡히는 도구로 바꿔 볼 차례다. 사실 MCP는 설정 파일을 한 번도 안 만져 보면 꽤 멀게 느껴진다. 이름은 거창한데, 막상 어디에 뭘 적어야 하는지 감이 안 오기 때문이다.

그런데 재미있는 건, 첫 서버 하나만 붙여 보면 분위기가 확 바뀐다는 점이다. 전에는 "AI가 외부 도구와 연결된대" 정도의 이야기였다면, 이제는 "내 프로젝트 폴더를 읽고, 필요한 파일을 찾고, 실제로 도와주는구나"라는 감각으로 바뀐다. 이 지점부터 MCP는 뉴스가 아니라 장비가 된다.

이번 장에서는 사용자 관점에서 가장 많이 만나는 세 가지 호스트 환경을 다룬다. Claude, VS Code, Cursor다. 목표는 복잡한 이론이 아니라 아주 실용적인 감각 하나를 익히는 것이다. 설정 파일을 읽고, 서버를 붙이고, 연결이 됐는지 확인할 수 있는 상태가 되면 된다.

시작 전에 준비할 것

처음에는 욕심을 줄이는 편이 좋다. GitHub, 데이터베이스, 브라우저 자동화까지 한꺼번에 붙이면 멋있어 보이지만, 처음엔 어디서 막혔는지 찾기 어려워진다. 그래서 첫 실습은 보통 파일시스템 MCP 서버가 가장 좋다. 눈으로 확인이 쉽고, 결과도 직관적이기 때문이다.

준비물은 많지 않다.

Node.js와 npx
MCP를 붙일 호스트 앱 하나 이상
접근을 허용할 폴더 하나

Node.js는 자바스크립트 프로그램을 실행하는 도구라고 생각하면 된다. 많은 MCP 서버가 npx로 바로 실행되기 때문에 사실상 기본 공구함 같은 존재다.

그리고 하나 더 기억하자. MCP 서버는 크게 두 가지 방식으로 붙는다고 보면 편하다. 내 컴퓨터에서 직접 실행하는 로컬 stdio 서버, 그리고 주소로 연결하는 원격 HTTP 서버다. 예전 자료에서는 SSE 서버라는 표현도 보일 수 있지만, 최신 흐름은 보통 Streamable HTTP를 중심으로 읽는 편이 좋다. 처음엔 로컬 stdio가 이해하기 쉽다. 내 컴퓨터에서 프로그램 하나를 켜고, 호스트가 그 프로그램과 대화한다고 생각하면 된다.

설정 파일은 무섭지 않다

처음 JSON 파일을 열면 많은 사람이 순간 얼어붙는다. 하지만 MCP 설정은 생각보다 단순하다. 거의 항상 아래 요소만 읽으면 된다.

서버 이름
실행 명령어 command
실행 인자 args
환경 변수 env
원격 서버라면 type, url, 필요 시 headers

쉽게 말하면 이런 느낌이다. 서버 이름은 별명이고, command는 뭘 실행할지, args는 어떻게 실행할지, env는 비밀번호나 토큰 같은 준비물이다. 원격 서버일 때는 실행 명령 대신 주소를 적는다고 보면 된다.

이 감각만 있으면 호스트가 Claude든 VS Code든 Cursor든 훨씬 덜 낯설다. 겉모습은 달라도 속마음은 비슷하기 때문이다.

Claude에서 MCP 붙이기

Claude 계열에서는 크게 두 갈래로 생각하면 편하다. 데스크톱 앱에서 설정하는 방법과, Claude Code에서 명령으로 추가하는 방법이다. 둘 다 알아두면 좋지만, 입문자는 데스크톱 앱이 더 눈에 잘 들어온다.

Claude Desktop: 가장 직관적인 첫 연결

Claude Desktop에서는 개발자 설정 쪽에서 구성 파일을 열어 MCP 서버를 추가할 수 있다. 버전에 따라 메뉴 이름은 조금 달라질 수 있지만, 핵심 흐름은 비슷하다. 설정에서 MCP 관련 구성 파일을 열고, 여기에 서버 정의를 추가하는 방식이다.

가장 쉬운 예시는 파일시스템 서버다.

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

이 설정의 뜻은 단순하다. filesystem이라는 이름의 서버를 만들고, npx로 파일시스템 서버를 실행하되, Claude가 접근 가능한 폴더를 데스크톱과 프로젝트 폴더로 제한하겠다는 의미다.

Windows에서는 경로를 적을 때 백슬래시를 두 번 써야 한다. JSON 안에서는 \처럼 이스케이프가 필요하기 때문이다.

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

저장한 뒤에는 Claude Desktop을 완전히 종료했다가 다시 켜는 편이 안전하다. 재시작 후 도구 관련 표시가 보이거나, 도구 사용 승인 창이 나타나면 연결이 시작된 것이다.

첫 테스트는 아주 소박하게 해 보자.

내가 접근 가능한 폴더를 보여줘.

혹은 이렇게 물어도 좋다.

Projects 폴더 안에서 README 파일을 찾아 요약해줘.

여기서 중요한 건 Claude가 갑자기 마법을 부린 게 아니라, MCP 서버를 통해 실제 폴더 정보를 읽었다는 점이다. 이제부터 AI의 답변이 공중부양이 아니라 현장답사가 된다.

Claude Code: 명령 한 줄로 붙이는 맛

터미널 중심으로 작업한다면 Claude Code 방식이 더 빠르다. 이쪽은 설정 파일을 손으로 열지 않고 명령으로 서버를 추가할 수 있다.

예를 들어 현재 프로젝트 폴더에 파일시스템 서버를 붙이려면 이런 식으로 시작할 수 있다.

claude mcp add --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem "$PWD"

이 명령은 filesystem이라는 이름으로 로컬 stdio 서버를 등록하고, 현재 폴더를 접근 대상으로 삼는 예시다. 등록 후에는 아래 명령으로 상태를 확인할 수 있다.

claude mcp list

특정 서버 정보를 보고 싶다면 다음처럼 확인한다.

claude mcp get filesystem

Claude Code에서는 범위 개념도 알아두면 좋다. 보통 local, project, user 같은 스코프가 있고, 어디에 저장하느냐에 따라 서버가 현재 프로젝트에서만 보일지, 여러 프로젝트에서 보일지가 달라진다.

초보자에게 중요한 한 줄 요약은 이것이다.

혼자 잠깐 테스트할 땐 local이나 user, 팀과 함께 쓸 설정이면 project 범위가 편하다.

프로젝트 범위로 등록하면 .mcp.json 같은 공유 가능한 설정 파일이 생긴다. 이건 나중에 팀원들이 같은 도구 구성을 바로 재현할 때 꽤 유용하다. 다만 프로젝트 범위 서버는 팀과 공유될 수 있으므로, 과한 권한이나 민감한 토큰이 들어가지 않도록 더 조심하는 편이 좋다.

원격 HTTP 서버를 붙일 때는 다음처럼 추가할 수 있다.

claude mcp add --transport http myserver https://example.com/mcp

예전 문서나 오래된 서버에서는 SSE 전송 예시도 볼 수 있다. Claude Code는 이런 서버도 지원할 수 있지만, 새 서버를 이해할 때는 HTTP 중심으로 보는 편이 덜 헷갈린다.

VS Code에서 MCP 붙이기

VS Code는 코드를 쓰는 공간이니만큼 MCP와 잘 어울린다. 특히 채팅 에이전트가 파일, 브라우저, 외부 서비스와 함께 움직일 때 체감이 크다. VS Code에서는 크게 두 가지 방식이 있다. 갤러리에서 설치하는 방법과 mcp.json을 직접 편집하는 방법이다.

처음엔 갤러리 방식이 편하다. 확장 보기에서 @mcp로 검색하면 MCP 서버 목록을 볼 수 있고, 원하는 서버를 설치할 수 있다. 하지만 MCP가 어떻게 연결되는지 배우는 데는 설정 파일을 직접 보는 편이 훨씬 좋다.

워크스페이스 단위 설정은 보통 .vscode/mcp.json에 둔다. 예시는 이렇게 생겼다.

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

이 설정은 현재 작업 중인 프로젝트 폴더를 MCP 파일시스템 서버에 연결한다. ${workspaceFolder}는 지금 열려 있는 프로젝트 루트를 뜻하는 변수다. 매번 경로를 길게 적지 않아도 되니 꽤 편하다.

원격 HTTP 서버를 붙일 때는 모양이 달라진다.

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp"
    }
  }
}

즉, 로컬 서버는 command와 args, 원격 서버는 type과 url이라고 기억하면 된다. 인증이 필요하면 headers나 입력 변수, 환경 파일 같은 방식을 함께 쓸 수 있다. 중요한 건 비밀값을 설정 파일에 직접 박아 넣지 않는 것이다.

VS Code에서는 사용자 전체 설정도 가능하다. 모든 프로젝트에서 쓰고 싶은 MCP 서버가 있다면 사용자 구성 파일에 넣으면 된다. 반대로 팀과 공유할 도구라면 .vscode/mcp.json에 넣고 버전 관리에 포함시키는 방식이 좋다.

연결 후에는 채팅 뷰에서 에이전트 모드와 사용 가능한 도구를 확인해 보자. 필요하면 특정 도구만 켜고 끌 수도 있다. 이게 꽤 실용적인데, 도구가 너무 많으면 AI가 괜히 멀티툴 욕심을 부릴 수 있기 때문이다.

첫 테스트는 이런 식이 좋다.

현재 프로젝트의 모든 Markdown 파일을 찾아서 어떤 문서들이 있는지 한 줄씩 정리해줘.

여기서 VS Code가 실제 파일을 읽고 응답하면 연결 성공이다. 이제 AI는 "그럴 것 같아요"가 아니라 "제가 읽어봤는데요" 모드로 들어간다.

VS Code에서 알아두면 좋은 포인트

VS Code는 macOS와 Linux에서 로컬 stdio 서버를 샌드박스처럼 제한해서 돌릴 수 있는 기능도 제공한다. 샌드박스는 쉽게 말해 "도구를 좁은 운동장 안에서만 뛰게 하는 울타리"다. 특히 파일 쓰기 범위나 네트워크 접근을 제한하고 싶을 때 유용하다. 초반엔 꼭 쓰지 않아도 되지만, 보안 감각을 키우는 데 도움이 된다.

또 한 가지 흥미로운 점은, 다른 앱에서 설정한 MCP 서버를 VS Code가 자동으로 발견해 재사용할 수 있다는 것이다. 이미 Claude Desktop 쪽에서 구성을 만들어 둔 사람이라면 꽤 편하다.

Cursor에서 MCP 붙이기

Cursor는 AI 친화적인 코드 에디터답게 MCP 설정 진입이 비교적 직관적이다. 보통 설정에서 MCP 메뉴로 들어가 서버를 추가하거나, 설정 파일을 직접 편집하는 방식으로 사용한다.

프로젝트별로 쓰려면 보통 .cursor/mcp.json 파일을 쓴다. 예를 들어 현재 프로젝트에 파일시스템 서버를 붙이려면 이런 식이다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Projects/my-app"
      ]
    }
  }
}

전역으로 쓰고 싶다면 홈 디렉터리 쪽 설정 파일을 사용할 수 있다. 그러면 여러 프로젝트에서 같은 MCP 서버를 반복해서 등록할 필요가 없다. 다만 입문 단계에서는 프로젝트별 설정이 더 안전하다. 왜냐하면 실수로 너무 넓은 범위를 열 가능성이 줄어들기 때문이다.

Cursor에서는 데이터베이스처럼 환경 변수가 필요한 서버도 자주 쓴다. 예를 들어 PostgreSQL 서버는 이런 식으로 등록할 수 있다.

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres"
      ],
      "env": {
        "DATABASE_URL": "postgresql://readonly:password@localhost:5432/appdb"
      }
    }
  }
}

여기서 핵심은 env다. 비밀번호나 토큰 같은 값은 보통 여기에 전달한다. 물론 실제로는 설정 파일에 비밀 값을 직접 박아 넣는 것보다 운영체제 환경 변수나 별도 비밀 관리 방식을 쓰는 편이 더 안전하다.

Cursor는 에이전트가 관련성이 높다고 판단하면 MCP 도구를 자동으로 선택해 쓰기도 한다. 그래서 초보자는 처음에 "내가 언제 누른 거지?" 하는 순간이 올 수 있다. 놀라지 말자. 보통은 사용 승인 창이나 호출 정보가 함께 보인다. 한 번씩 확인하면서 어떤 도구가 어떤 입력으로 실행되는지 익히면 된다.

첫 테스트는 이렇게 해 보자.

이 프로젝트에서 package.json을 읽고, 어떤 스크립트를 실행할 수 있는지 설명해줘.

혹은 데이터베이스 서버를 붙였다면 이렇게도 가능하다.

users 테이블 구조를 보여줘.

연결이 잘 되면 Cursor는 말만 잘하는 조수에서, 직접 창고에 들어가 물건을 찾아오는 조수로 진화한다.

세 호스트를 한 번에 이해하는 비교 감각

겉보기엔 Claude, VS Code, Cursor가 제각각처럼 보이지만, 실제로는 비슷한 패턴을 반복한다. 이 감각을 잡아두면 새로운 호스트를 만나도 당황하지 않는다.

Claude Desktop은 설정 파일 중심이고, 재시작 후 확인하는 흐름이 명확하다.
Claude Code는 명령어 중심이라 빠르고, 범위 관리가 강력하다.
VS Code는 워크스페이스 공유와 도구 토글, 갤러리 경험이 좋다.
Cursor는 AI 작업 흐름 안에 MCP를 자연스럽게 섞어 쓰기 편하다.

핵심은 같다. 서버를 등록하고, 접근 범위를 정하고, 승인 흐름을 확인하고, 실제 질문으로 테스트한다. 이 네 단계만 기억하면 된다.

처음 연결할 때 가장 자주 틀리는 것들

MCP 입문에서 막히는 이유는 대개 거대한 설계 문제가 아니다. 아주 소박한 오타와 재시작 부족이 대부분이다. 정말로 그렇다. 놀랍도록 인간적이다.

가장 흔한 실수는 이렇다.

JSON 쉼표나 따옴표가 하나 빠진 경우
Windows 경로에서 \ 대신 ``를 한 번만 쓴 경우
node나 npx가 설치되지 않았거나 경로가 잡히지 않은 경우
설정을 바꿨는데 앱을 재시작하지 않은 경우
서버에 너무 넓은 권한을 줬거나, 반대로 필요한 폴더를 빼먹은 경우

JSON은 특히 까다로운 척을 잘한다. 사실은 규칙이 단순한데, 쉼표 하나만 빠져도 전부 삐친다. 그래서 설정이 안 먹을 때는 멋진 추론보다 먼저 JSON 형식부터 의심하는 편이 현명하다.

보안은 처음부터 습관이다

MCP는 강력하다. 강력하다는 말은 곧 조심할 포인트도 있다는 뜻이다. AI에게 도구를 준다는 건, 결국 도구가 닿을 수 있는 범위를 정해 준다는 말이기도 하다.

초보자일수록 아래 세 가지를 습관처럼 챙기면 좋다.

파일시스템 서버는 꼭 필요한 폴더만 열기
데이터베이스는 가능하면 읽기 전용 계정 쓰기
API 키나 토큰은 설정 파일에 직접 하드코딩하지 않기

쉽게 말해, 처음부터 집 열쇠 전부를 건네주지 말자는 이야기다. 주방에서 컵 하나 꺼내 달라고 했는데, 집문서 보관함까지 열 수 있으면 곤란하다.

또 낯선 MCP 서버는 무조건 믿지 말자. 로컬 서버는 실제로 내 컴퓨터에서 코드가 실행된다. 출처를 확인하고, 가능한 한 신뢰할 수 있는 서버만 쓰는 편이 안전하다.

가장 추천하는 첫 실습

처음부터 대단한 자동화를 노리기보다, 아래 순서대로 해 보면 감각이 가장 빨리 잡힌다.

먼저 파일시스템 MCP 서버 하나를 붙인다. 그리고 프로젝트 루트만 열어 둔다. 그다음 AI에게 프로젝트 파일 구조를 요약하게 한다. 이어서 README를 읽고 요약하게 한다. 마지막으로 새 메모 파일 하나를 만들게 한다.

예를 들면 이런 흐름이다.

1. 이 프로젝트에서 어떤 파일들이 중요한지 찾아줘.
2. README.md를 읽고 핵심 내용을 세 문장으로 요약해줘.
3. summary.md 파일을 만들어 방금 요약을 저장해줘.

이 세 단계가 좋은 이유는 MCP의 핵심 경험을 한 번에 맛볼 수 있기 때문이다. 읽기, 이해, 쓰기까지 이어지기 때문이다. 이걸 해 보면 "아, MCP는 그냥 플러그인 목록이 아니라 작업 흐름을 여는 장치구나"라는 감각이 온다.

사용자 입장에서 기억할 한 문장

사용자 입장에서 MCP 사용법의 핵심은 의외로 간단하다. 호스트에 서버를 등록하고, 접근 범위를 정한 뒤, 작은 질문으로 연결을 검증하는 것이다.

처음엔 설정 파일이 조금 딱딱해 보일 수 있다. 하지만 몇 번 만지다 보면 금방 익숙해진다. 오히려 익숙해지고 나면 MCP 서버 설명만 봐도 "아, 이건 어디에 넣으면 되겠네"라는 감이 생긴다. 그때부터는 새로운 도구를 붙이는 속도가 확 빨라진다.

그리고 바로 그 지점에서 재미가 시작된다. AI가 더 똑똑해지는 것이 아니라, 내 환경과 연결되면서 더 쓸모 있어지는 것이기 때문이다.

다음 장으로 가기 전, 작은 체크리스트

이번 장을 읽고 직접 해 볼 수 있다면 충분하다.

Claude, VS Code, Cursor 중 하나에서 MCP 설정 파일 위치를 찾을 수 있다.
파일시스템 같은 간단한 MCP 서버를 하나 등록할 수 있다.
연결 후 재시작이나 서버 목록 확인으로 상태를 점검할 수 있다.
실제 질문을 던져 도구가 동작하는지 검증할 수 있다.
권한 범위를 너무 넓게 주지 않아야 한다는 감각이 생겼다.

여기까지 왔다면 이제 MCP는 더 이상 소개글 속 주인공이 아니다. 실제로 내 곁에서 일하기 시작한 팀원이다. 다음 장에서는 이 팀원에게 파일, 검색, GitHub, 데이터베이스 같은 일을 하나씩 맡겨 보자.

책 목록

MCP, 진짜로 써먹는 법: 연결부터 서버 제작, 운영까지

전체 목차 보기