MCP란? 뜻부터 클로드 코드에 MCP 서버 연결하는 법까지

Claude에게 노션이나 웹 문서 내용을 물으려면 매번 복사해서 붙여 넣어야 합니다. MCP(Model Context Protocol)는 Claude 같은 AI가 바깥 프로그램과 서비스를 직접 쓸 수 있게 이어 주는 표준 연결 방식입니다. 연결하면 Claude가 브라우저를 열고, 노션을 읽고, 데이터베이스를 조회합니다. MCP 자체는 무료지만, 연결하는 서비스에 따라 API 키나 요금이 필요할 수 있습니다. 이 글은 2026년 10월 13일 Claude Code에 Playwright MCP를 연결해 공식 문서를 열고 화면까지 찍게 해 본 기록입니다.

MCP는 무엇인가

MCP 서버를 연결하면 Claude가 그 서비스에 직접 들어가서 읽고, 필요하면 작업도 합니다. 전자제품마다 콘센트 모양이 같으면 어디에나 꽂을 수 있는 것처럼, 서비스들이 같은 규격으로 문을 열어 두는 셈입니다.

이 사이트도 씁니다. 글 목록을 정할 때 쓴 네이버 검색량은 검색광고 데이터를 읽는 MCP 서버를 연결해 Claude가 직접 조회한 값입니다.

	하는 일	예
MCP 서버	Claude에게 바깥 도구를 쓸 손을 달아 줌	브라우저 조작, 노션 읽기, 데이터베이스 조회
스킬	Claude에게 일하는 방법을 알려 줌	점검표, 글쓰기 기준, 작업 절차

어디서 연결하나

연결하는 곳	방법	이럴 때 고르세요
Claude Code	터미널에서 claude mcp add	내 컴퓨터의 프로그램(브라우저, 파일 도구)을 쓰게 할 때
claude.ai 커넥터	claude.ai 설정의 커넥터에서 추가	노션·구글 드라이브 같은 웹 서비스를 앱과 Claude Code에서 함께 쓸 때
Claude 데스크톱 앱	앱 설정 또는 설정 파일	터미널 없이 앱에서만 쓸 때

공식 문서에 따르면 claude.ai 구독 계정으로 Claude Code에 로그인하면, claude.ai에서 추가한 커넥터가 Claude Code에도 자동으로 나타납니다. API 키로 로그인했다면 나타나지 않습니다.

Claude Code에서 연결할 때는 범위를 고릅니다.

범위	어디서 쓰이나	저장되는 곳
local(기본값)	연결한 그 폴더에서만, 나만	~/.claude.json의 그 폴더 항목
project	그 폴더에서, 저장소를 같이 쓰는 사람 모두	폴더의 .mcp.json
user	내 모든 폴더에서	~/.claude.json

처음 써 보는 서버는 local로 연결하는 편이 안전합니다. 이번에도 연습 폴더(mcp-lab)를 만들어 그 안에만 연결했습니다.

1단계. Playwright MCP 연결하기 (약 1분)

이 단계에서는 Microsoft가 만든 Playwright MCP를 연결합니다. Claude가 브라우저를 열고 클릭하고 화면을 찍을 수 있게 해 주는 서버입니다. 이 사이트는 글마다 공식 문서 화면을 찍어 넣는데, 그 일을 Claude가 직접 할 수 있는지 보려고 골랐습니다. 연습 폴더에서 터미널로 실행합니다.

claude mcp add playwright --scope local -- npx @playwright/mcp@latest --headless --isolated --output-dir ./shots

-- 앞은 Claude Code의 옵션이고, 뒤는 서버를 실행하는 명령입니다. 뒤쪽의 --headless는 브라우저 창을 띄우지 않는 옵션, --isolated는 브라우저 기록을 남기지 않는 옵션, --output-dir는 찍은 화면을 저장할 폴더입니다. 설치는 따로 하지 않습니다. npx가 처음 실행할 때 내려받습니다.

이렇게 나오면 성공 Added stdio MCP server playwright가 나오고, claude mcp get playwright에서 Status: ✔ Connected가 보입니다.

실제 실행 기록 · macOS 26.1 · Claude Code 2.1.292 · 연습 폴더 mcp-lab · 2026-10-13 (출력 중 일부)

$ claude mcp add playwright --scope local -- npx @playwright/mcp@latest --headless --isolated --output-dir ./shots
Added stdio MCP server playwright with command: npx @playwright/mcp@latest --headless --isolated --output-dir ./shots to local config
$ claude mcp get playwright
  Scope: Local config (private to you in this project)
  Status: ✔ Connected

• ✘ Failed to connect가 나오면: 서버를 실행하는 명령이 실패한 것입니다. -- 뒤의 명령을 터미널에서 그대로 실행해 오류를 확인합니다. API 키가 필요한 서버라면 --env 이름=값을 -- 앞에 넣었는지 봅니다.
• --env 바로 뒤에 서버 이름을 쓰면: 공식 문서에 따르면 이름을 환경 변수 값으로 잘못 읽습니다. --env와 이름 사이에 --transport stdio 같은 다른 옵션을 하나 둡니다.
• ! Needs authentication이 나오면: 로그인이 필요한 원격 서버입니다. Claude Code 대화창에서 /mcp를 열어 인증합니다.

2단계. 실제로 일 시켜 보기 (약 2분)

이 단계에서는 연결한 서버로 이 사이트에 실제로 필요한 일을 시킵니다. MCP 글에 넣을 공식 문서 화면을 Claude에게 직접 찾아서 찍어 오게 했습니다.

Playwright로 https://code.claude.com/docs/ko/mcp 를 열고, 로컬 stdio 서버를 추가하는 명령 형식을 한 줄로 알려 줘. 그 설명이 보이는 부분을 화면으로 찍어서 shots/mcp-stdio.png로 저장해 줘.

좋은 답이라면 문서에서 해당 구절을 찾아 명령 형식을 알려 주고, 그 부분이 보이게 찍은 파일을 저장합니다. 대화창이라면 위 문장을 그대로 붙여 넣으면 되고, 처음 쓸 때 도구 사용 허락을 묻습니다. 한 번만 묻고 끝내는 -p 방식에서는 허락할 사람이 없으니 --allowedTools mcp__playwright로 이 서버의 도구를 미리 허용했습니다.

답이 오기까지 조금 걸렸습니다. 처음 찍을 때 쿠키 안내 창이 내용을 가리자, Claude가 안내 창에서 거부를 누르고 다시 찍었다고 알려 왔습니다.

• Input must be provided either through stdin or as a prompt argument가 나오면: 처음엔 이 오류가 났습니다. --allowedTools는 값을 여러 개 받는 옵션이라, 바로 뒤에 쓴 질문까지 도구 이름으로 읽었습니다. 질문을 먼저 쓰고 --allowedTools를 맨 뒤에 두니 됐습니다.

3단계. 찍어 온 화면 확인하기 (약 1분)

이 단계에서는 Claude가 저장한 화면을 열어 봅니다. 아래 이미지는 Claude가 MCP로 직접 찍은 파일이고, 번호만 얹었습니다.

이렇게 나오면 성공 요청한 구절이 화면 안에 들어 있습니다. 이번에는 제목부터 기본 구문까지 한 화면에 담겨 있었습니다.

찍을 곳을 알려 주지 않았는데도 문서에서 위치를 찾아 그 부분을 찍어 왔다는 점이 쓸 만했습니다. 다만 이 사이트는 화면을 정해진 크기로 찍는 스크립트를 따로 쓰고 있고, 그쪽이 사용량이 들지 않습니다. 그래서 “어디에 있는지 모르는 화면을 찾아서 찍기”에만 Playwright MCP를 쓰기로 했습니다.

4단계. 연결 지우기 (약 1분)

이 단계에서는 연습으로 연결한 서버를 지웁니다. 연결할 때 쓴 범위를 똑같이 붙입니다. 터미널에서 실행합니다.

claude mcp remove playwright -s local

이렇게 나오면 성공 Removed MCP server playwright from local config가 나옵니다. 지운 뒤 컴퓨터 전체에 설치된 npm 패키지 목록이 연결 전과 같은 것도 확인했습니다. npx는 패키지를 전역으로 설치하지 않고 내려받아 실행만 합니다.

한계와 주의할 점

• MCP 서버는 내 컴퓨터에서 프로그램으로 돌아가거나, 내 계정 권한으로 바깥 서비스에 접속합니다. 모르는 사람이 만든 서버는 저장소를 먼저 보고, 쓰기 권한이 필요 없으면 읽기 권한만 줍니다.
• project 범위의 .mcp.json은 저장소에 함께 올라갑니다. API 키를 직접 적지 말고 ${이름} 형식의 환경 변수로 넣습니다.
• 공식 문서에 따르면 MCP 도구 하나의 결과는 기본 25,000토큰까지 받고, 10,000토큰이 넘으면 경고가 뜹니다. 긴 페이지를 통째로 읽히면 잘릴 수 있습니다.
• 원격 서버의 SSE 방식은 공식 문서에서 더 이상 권장하지 않습니다. 새로 연결한다면 HTTP 방식을 씁니다.
• 윈도우는 이번에 해 보지 않았습니다. 윈도우에서 npx로 실행하는 서버가 안 뜨면 cmd /c npx …로 감싸서 해결했다는 사용자 사례가 있습니다. 사용자 후기이며 공식 안내는 아닙니다.

대안

이름	다른 점	이럴 때 고르세요
Claude in Chrome 확장	내가 쓰는 크롬을 Claude가 직접 조작. 로그인된 사이트도 됨	로그인이 필요한 사이트에서 일을 시킬 때
직접 스크립트	Playwright 같은 도구로 정해진 일을 코드로 실행. 사용량이 들지 않음	매번 똑같이 반복하는 일
스킬	도구를 붙이지 않고 일하는 방법만 알려 줌	바깥 서비스 접속 없이 절차만 맡길 때

자주 묻는 질문

MCP 뜻이 뭔가요? API랑 다른가요?

API는 서비스마다 쓰는 법이 다르지만, MCP는 같은 규격으로 맞춰 둬서 Claude가 어느 서버든 같은 방식으로 씁니다. 많은 MCP 서버가 안에서는 각 서비스의 API를 부릅니다.

클로드 MCP는 무료인가요?

MCP 자체와 Playwright MCP 같은 서버는 무료입니다. 다만 Claude Code를 쓰려면 Pro 이상 구독이나 API 결제가 필요하고(클로드 코드 설치 방법 참고), 연결하는 서비스에 따라 따로 요금이 붙을 수 있습니다.

클로드 코드 MCP가 다른 폴더에서 안 보여요

기본 범위가 local이라 연결한 폴더에서만 보입니다. 모든 폴더에서 쓰려면 --scope user로 다시 연결합니다.

claude mcp list에 Failed to connect가 나와요

서버를 실행하는 명령이 실패한 것입니다. 원인별 확인 방법은 위 1단계 아래에 정리했습니다.

MCP 서버를 추가했는데 도구가 안 떠요. 재시작해야 하나요?

이미 열려 있던 대화창에는 바로 안 붙을 수 있습니다. 대화창에서 /mcp로 상태를 보고, 안 보이면 Claude Code를 다시 시작합니다.

출처

Claude Code MCP 문서, Playwright MCP 저장소와 README (모두 2026-10-13 확인)