Claude Code MCP 서버 연결: stdio·HTTP 설정과 범위 우선순위

공식 가이드에 예시로 나오는 Playwright MCP 서버를 그대로 붙여 봤습니다.

claude mcp list에는 √ Connected가 떴는데, Claude에게 example.com을 열어 달라고 하자 브라우저 도구가 Chromium distribution 'chrome' is not found로 실패하더라고요. 연결됐다는 표시가 곧 쓸 수 있다는 뜻은 아니었던 거죠.

Windows PowerShell 5.1에서는 그보다 한 단계 앞에서 막혔습니다. 같은 등록 명령을 그대로 치니 error: unknown option '-y'로 끝났어요.

이 글은 그 두 군데를 포함해, claude mcp add로 stdio·HTTP 서버를 붙이고 local·project·user 중 어디에 둘지 고르는 법을 정리한 것입니다.

공식 문서는 2026년 9월 10일 기준이고(범위 우선순위는 10월 6일에 다시 확인), 등록·범위 충돌·stdio 오류는 Claude Code 2.1.267로, PowerShell 절은 9월 30일 Windows 11 · Windows PowerShell 5.1에서 Claude Code 2.1.283으로 직접 실행해 확인했습니다. 10월 16일에는 같은 Windows에서 2.1.296으로 PowerShell 등록을 다시 해 보고, Playwright 도구 호출까지 해 봤습니다.

등록하고 나서 도구까지 불러 보기

Playwright 일을 겪고 나니, 확인은 등록·목록·도구 호출 세 단계로 나눠서 하는 게 맞다고 봅니다. 하나씩 보겠습니다.

1. 서버 위치에 맞는 명령으로 등록

명령은 서버가 어디서 도는지로 갈립니다.

서버 위치	전송	명령
사용자 컴퓨터의 프로세스	stdio(기본값)	claude mcp add <이름> -- <명령>
호스팅된 서비스	http	claude mcp add --transport http <이름> <URL>
호스팅된 서비스(구식)	sse	claude mcp add --transport sse <이름> <URL>

브라우저 제어, 로컬 파일 접근처럼 그 컴퓨터의 자원이 필요하면 stdio, Notion·Sentry처럼 이미 떠 있는 서비스면 http입니다. --transport(줄여서 -t)를 빼면 stdio로 취급되고, stdio 명령에서 -- 뒤는 전부 서버 명령과 인자예요. --를 빼면 Claude Code가 뒤의 플래그를 자기 옵션으로 읽다가 실패합니다.

Playwright는 Node.js만 있으면 되고 계정이 필요 없어서 연습용으로 좋습니다.

claude mcp add playwright -- npx -y @playwright/mcp@latest

Added stdio MCP server playwright with command: npx -y @playwright/mcp@latest to local config

2. claude mcp list로 연결 보기

Checking MCP server health…

playwright: npx -y @playwright/mcp@latest - √ Connected

Connected면 서버 프로세스가 뜨고 MCP 핸드셰이크까지 끝난 것입니다. Added … 줄은 설정 파일에 적혔다는 뜻일 뿐이니, 이 단계는 건너뛰지 마세요.

3. 도구를 한 번 불러 보기

세션에서 “example.com을 열고 페이지 제목을 알려 줘”라고 시키자 브라우저 도구(mcp__playwright__browser_navigate)가 이 오류로 실패했습니다.

Chromium distribution 'chrome' is not found at /opt/google/chrome/chrome

list는 서버가 안에서 쓰는 다른 실행 파일(여기서는 Chrome)까지 확인하지 않습니다. 그런 의존성은 도구를 부르는 순간에야 드러나요.

반대로 Chrome이 깔린 곳에서는 바로 됩니다. 10월 16일 Chrome이 설치된 Windows 11 테스트 환경에서 Claude Code 2.1.296에 --headless를 붙여 등록하고 같은 일을 -p로 시키자, mcp__pw__browser_navigate가 돌아 Example Domain이라고 답했습니다. Playwright가 남긴 실행 기록에는 "channel": "chrome"이 적혀 있었어요. 같은 서버라도 그 컴퓨터에 무엇이 깔려 있느냐에 따라 결과가 갈리니, 도구 호출은 서버를 쓸 컴퓨터마다 한 번씩 해 보세요.

그래서 등록한 날 도구를 한 번 불러 보는 것까지가 확인입니다. 해결 방법은 아래 오류 절에 있습니다.

범위는 쓰는 사람으로 고른다

범위는 --scope(줄여서 -s)로 정하고, 빼면 local입니다. 저는 그 서버를 누가 쓰느냐로 고르길 권합니다.

• 혼자 시험해 보는 중이면 그대로 둡니다(local). 이 프로젝트에서만 보입니다.
• 팀 전체가 같은 서버를 써야 하면 --scope project. 프로젝트 루트 .mcp.json에 저장되고 저장소에 커밋합니다.
• 모든 프로젝트에서 혼자 쓸 거라면 --scope user.

~/.claude.json은 Windows에서 %USERPROFILE%\.claude.json입니다. 서버를 지울 때 쓰는 claude mcp remove는 Claude Code 설정 파일에서 그 서버 항목만 지우니, 연결하던 Notion 문서나 데이터베이스에는 영향이 없어요.

같은 서버가 여러 범위에 있으면

같은 서버가 여러 곳에 정의돼 있으면 Claude Code는 가장 위의 정의 하나로 한 번만 연결합니다. 필드를 합치지 않아요.

local·project·user 사이에서는 이름이 같으면, 플러그인 서버와 claude.ai 커넥터는 URL이나 명령이 같으면 중복으로 봅니다. 조직이 관리 설정의 managedMcpServers로 둔 서버는 이 모두보다 위입니다(Claude Code v2.1.259 이상).

정말 그런지 같은 이름을 user와 local에 등록해 직접 확인했습니다.

claude mcp add --transport http docs-demo https://code.claude.com/docs/mcp --scope user
claude mcp add --transport http docs-demo https://code.claude.com/docs/mcp --scope local
claude mcp get docs-demo

상태	claude mcp get의 Scope:
둘 다 있음	Local config (private to you in this project)
local만 지운 뒤	User config (available in all your projects)

위의 정의가 사라지자 아래 정의가 통째로 이어받았습니다. 서버 설정이 갑자기 바뀐 것 같으면 같은 이름이 다른 범위에도 있는지 claude mcp get <이름>부터 보세요.

팀이 공유한 서버는 승인부터

팀이 .mcp.json으로 공유한 서버는 승인하기 전까지 붙지 않습니다. 목록에는 ⏸ Pending approval (run `claude` to approve)로 나오고, 그 폴더에서 claude를 실행해 대화상자에서 승인하면 연결됩니다. 저장소를 클론하기만 했는데 사용자 컴퓨터에서 프로세스가 뜨는 일을 막기 위한 절차예요.

이 승인은 “이 서버를 연결해도 되나”를 묻는 것이고, 도구를 처음 부를 때 뜨는 프롬프트는 “이 호출을 실행해도 되나”를 따로 묻습니다. 두 번째는 일반 권한 규칙을 타며, 규칙을 적는 법은 Claude Code 권한 설정 글에 있습니다.

PowerShell 5.1에서는 ’–’를 따옴표로

Windows PowerShell 5.1에서 Playwright 명령을 그대로 치면 이렇게 끝납니다.

error: unknown option '-y'

--를 작은따옴표로 감싸면 등록됩니다.

claude mcp add playwright '--' npx -y '@playwright/mcp@latest'

이유는 간단합니다. PowerShell은 3.0부터 --를 “여기부터는 PowerShell 매개변수로 해석하지 말라”는 자기 문법 기호로 씁니다.

그래서 --가 Claude Code까지 가지 못하고, Claude Code는 서버 명령의 -y를 자기 옵션으로 읽어요. 직접 실행해 보니 결과는 이랬습니다.

claude mcp add <이름> 뒤에 붙인 것	결과
-- node --version	unknown option '--version'
-- node -e "process.exit(0)"	Invalid environment variable format
'--' node --version	등록됨
'--' npx -y @playwright/mcp@latest	등록됨, ✔ Connected

두 번째가 특히 헷갈립니다. node의 -e(코드 실행)를 Claude Code의 -e(환경 변수)로 읽어서, 환경 변수 형식이 틀렸다는 엉뚱한 오류가 나거든요. 명령 프롬프트(cmd)에서는 --를 그대로 써도 등록됐습니다.

10월 16일 Claude Code 2.1.296에서 다시 쳐 봐도 그대로였습니다. --는 error: unknown option '-y'로 끝났고, '--'로 감싸자 등록된 뒤 claude mcp list에 √ Connected가 떴어요.

공식 문서는 claude mcp add가 PowerShell과 명령 프롬프트를 포함한 모든 셸에서 똑같이 동작한다고 하지만, Windows PowerShell 5.1에서 직접 해 보니 --가 전달되지 않았습니다. 문서대로 했는데 위 오류가 난다면 '--'부터 써 보세요.

claude mcp add-json은 따옴표가 문제입니다. '{"type":"stdio",...}'처럼 작은따옴표 안의 JSON을 그대로 넘기면 Invalid configuration: : Invalid input이 나요. JSON 안의 큰따옴표를 \"로 이스케이프하면 등록됩니다.

claude mcp add-json jsonescaped '{\"type\":\"stdio\",\"command\":\"node\",\"args\":[\"--version\"]}'

같은 PowerShell 5.1에서 빈 문자열 인자가 사라지는 경우는 Claude Code 토큰 절약 글에 있습니다.

자주 만나는 오류

✘ Failed to connect

HTTP 서버라면 URL이 응답하지 않거나 토큰을 거부한 것이고, stdio 서버라면 명령이 시작하지 못한 것입니다.

HTTP는 curl -I <URL>로 찔러 보세요(PowerShell에서는 curl.exe). 404·405면 서버는 살아 있고(POST만 받는 엔드포인트가 많습니다), 401·403이면 인증이 필요합니다.

stdio는 claude mcp get <이름>에 나온 명령을 터미널에서 그대로 실행해 봅니다. 상태 뒤에 붙는 문구별 점검은 MCP 서버 연결 실패 해결 글에 따로 정리했습니다.

Chromium distribution 'chrome' is not found / browser "chrome-for-testing" not found

위 Playwright 예에서 직접 겪은 오류입니다. 서버 프로세스는 떴지만, 서버가 안에서 쓰는 브라우저가 없는 상태예요.

npx @playwright/mcp@latest install-browser chrome-for-testing으로 브라우저를 내려받으면 됩니다. 이미 설치된 다른 브라우저가 있다면 서버 인자에 --browser chromium처럼 붙여 그 브라우저를 쓰게 할 수도 있는데, 이때는 그 실행 파일 경로가 실제로 맞아야 합니다.

⏸ Pending approval (run `claude` to approve)

.mcp.json으로 받은 서버를 이 프로젝트에서 아직 승인하지 않은 상태입니다. 그 폴더에서 claude를 실행해 승인하세요. 예전에 거절했다면 claude mcp reset-project-choices로 기록을 지운 뒤 다시 실행합니다.

No MCP servers configured

local 범위는 등록한 프로젝트(그 디렉터리가 속한 git 저장소 루트)에만 묶여서, 다른 폴더에서는 보이지 않습니다. 모든 프로젝트에서 쓰려면 지우고 --scope user로 다시 추가하세요.

마치며

MCP 서버를 붙이면서 남은 건, 확인 표시마다 보는 범위가 다르다는 점이었습니다. Added …는 설정 파일에 적혔다는 뜻이고 Connected는 핸드셰이크까지 본 것이라, 서버가 안에서 쓰는 브라우저가 없다는 건 도구를 불러 보고서야 드러났어요.

등록한 날 도구 하나를 실제로 불러 보는 것까지를 등록으로 치시길 권합니다. Windows PowerShell 5.1이라면 '--'와 add-json의 \" 이스케이프만 기억해 두면 됩니다.

서버가 늘면 도구들이 컨텍스트를 차지하기 시작합니다. 그때는 조사와 검토를 떼어 내 각자의 컨텍스트에서 돌리는 도구를 좁힌 서브에이전트를 정의하는 절차를 이어서 보세요.