클로드 코드 MCP 연결 · 설정(claude code mcp setup): claude mcp add 한 줄로 붙이고, 읽기 도구만 승인 없이 열어 둔다

카테고리 없음

클로드 코드 MCP 연결 · 설정(claude code mcp setup): claude mcp add 한 줄로 붙이고, 읽기 도구만 승인 없이 열어 둔다

코드짜는아빠 2026. 10. 20. 18:55

붙이는 건 명령 한 줄이고, 손이 더 가는 건 붙인 다음이다. Claude Code에 MCP 서버를 연결하는 명령은 claude mcp add. 원격 서버는 --transport http 와 주소를, 내 컴퓨터에서 도는 서버는 -- 뒤에 실행 명령을 적는다. 설정이 어디에 저장될지는 --scope 로 고르고, 기본은 지금 프로젝트에서 나만 쓰는 local. 붙인 뒤엔 claude mcp list 로 연결을 확인하고 곧바로 도구 권한을 정한다. 우리 기준은 읽기 도구만 승인 없이 쓰게 하고, 바깥을 바꾸는 쓰기 · 입력 도구는 계속 승인을 거치게 두는 것. 출처는 Claude Code MCP 문서 · 권한 문서 · 설정 문서 · 훅 문서 · MCP 공식 소개, 모두 2026-10-20 조회.

MCP 서버를 붙이면 Claude Code 안에 도구가 생긴다

MCP 공식 소개는 MCP를 「AI 애플리케이션을 외부 시스템에 연결하는 오픈소스 표준」이라고 부르고, AI 애플리케이션용 USB-C 포트에 빗댄다. Claude Code에 서버를 붙이면 그 서버의 도구가 다른 도구와 똑같이 쓰이고, 이름은 mcp__<서버>__<도구> 꼴. 공식 예시로 mcp__filesystem__read_file 은 파일 시스템 서버의 파일 읽기 도구다. 4단계의 권한 규칙이 이 이름으로 걸리니 기억해 둘 것.

1단계: claude mcp add 로 붙인다 (2026-10-20 공식 문서 기준)

# 원격 서버(HTTP)
claude mcp add --transport http <SERVER_NAME> https://example.com/mcp

# 내 컴퓨터에서 도는 서버(stdio) — 패키지 버전까지 적는다
claude mcp add --transport stdio <SERVER_NAME> -- npx -y <PACKAGE>@<VERSION>

원격 서버는 공식 문서가 HTTP 방식을 권한다. SSE 방식은 「deprecated」로 표시돼 있어서, 고를 수 있으면 HTTP 쪽. stdio 에서는 -- 가 경계선. Claude Code 자신의 옵션(--transport · --env · --scope)은 앞에, 서버를 띄우는 명령과 인자는 뒤에 두고, 뒤쪽은 손대지 않고 그대로 서버로 넘어간다. --env 바로 뒤에 서버 이름이 오면 그 이름까지 KEY=value 로 읽혀 거부되니, 사이에 --transport stdio 같은 옵션을 하나 끼울 것.

npx -y 의 -y 는 설치 전에 묻는 확인을 건너뛰는 옵션이다(npm 문서). @<VERSION> 자리에는 범위(^1 같은)나 태그가 아니라 정확한 버전 숫자를 적는다. 버전을 적는 이유는 아래 「붙이고 나서 먼저 막은 것」에.

2단계: --scope 로 저장 범위를 고른다

claude mcp add --transport http <SERVER_NAME> --scope project https://example.com/mcp
claude mcp add --transport http <SERVER_NAME> --scope user https://example.com/mcp

범위	어디서 쓰이나	저장 위치(공식 문서)
`local`(기본)	지금 프로젝트에서 나만	`~/.claude.json` 안, 그 프로젝트 경로 아래
`project`	지금 프로젝트, 버전 관리로 팀과 공유	프로젝트 맨 위 `.mcp.json`
`user`	내 모든 프로젝트에서 나만	`~/.claude.json`

같은 서버가 여러 곳에 있으면 Claude Code는 한 번만 연결한다. 이기는 순서는 local → project → user → 플러그인이 준 서버 → claude.ai 커넥터. 같은 서버인지는 세 범위끼리는 이름으로, 플러그인 · 커넥터는 주소나 실행 명령으로. 이긴 쪽 항목을 통째로 쓰고, 범위끼리 필드를 섞지 않는다. local · user 범위가 저장되는 ~/.claude.json 은 Claude Code가 스스로 쓰는 파일이라 손으로 고칠 필요가 없다고 문서는 적는다. 추가 · 확인 · 삭제는 claude mcp 명령으로.

project 범위의 .mcp.json 은 다르다. 대화형 세션에서는 그 서버를 사용하기 전에 승인을 묻고, 그 선택을 되돌리는 명령은 claude mcp reset-project-choices. 그런데 claude -p 실행에서는 묻지 않고 바로 불러온다. 남이 만든 저장소에서 자동 실행을 돌린다면 .mcp.json 부터 열어 볼 것.

키가 필요한 서버: 명령줄과 공유 파일에 키를 적지 않는다

공식 예시에는 --env 로 키 값을, --header 로 Bearer 토큰을 명령줄에 바로 적는 꼴도 있다. 진짜 값을 그렇게 치면 셸 기록에 남는다. 게다가 local · user 범위 설정이 들어가는 ~/.claude.json 은 로그인 세션까지 담는 파일. 원격 서버가 OAuth 로그인을 지원하면 키 없이 /mcp 에서 인증하는 쪽이 낫다.

키를 꼭 넣어야 한다면 .mcp.json 의 환경 변수 펼치기. ${VAR} 는 그 환경 변수 값, ${VAR:-기본값} 은 값이 없을 때 쓸 기본값. command · args · env · url · headers 다섯 자리에서 펼쳐진다.

{
  "mcpServers": {
    "<SERVER_NAME>": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

이 파일은 커밋해도 키가 따라가지 않는다. 값은 권한 600 파일 하나에, 넣는 건 편집기로.

mkdir -p ~/.config
[ -e ~/.config/mcp-keys.env ] || install -m 600 /dev/null ~/.config/mcp-keys.env
chmod 600 ~/.config/mcp-keys.env
# 편집기로 열어 한 줄만 넣는다:  export API_KEY='<API_KEY>'
( . ~/.config/mcp-keys.env && exec claude )

echo 로 넣지 않는 건 그 줄이 셸 기록에 남아서. export 한 변수는 그 뒤에 실행하는 명령의 환경으로 넘어가고(bash 설명서), Claude Code도 그 명령 중 하나라 ${API_KEY} 가 펼쳐진다. 마지막 줄의 괄호는 서브셸이라, 거기서 불러온 값은 괄호가 끝나면 원래 셸에 남지 않는다(bash 설명서). 키가 들어가는 건 괄호 안에서 띄운 그 Claude Code 쪽뿐. 거꾸로, Claude Code가 그 안에서 돌리는 명령도 같은 값을 물려받는다. 키를 넣은 세션에서는 env · printenv 처럼 환경을 통째로 출력하는 명령을 승인하지 말 것.

3단계: claude mcp list 와 /mcp 로 연결을 확인한다

claude mcp list                                    # 서버마다 연결 상태
claude mcp get <SERVER_NAME>                       # 한 서버의 설정
claude mcp remove <SERVER_NAME> --scope <SCOPE>    # 뺄 때, 범위를 짚어서

claude mcp list 는 서버마다 ✔ Connected · ! Needs authentication · ✘ Failed to connect 같은 상태를 붙여 보여 준다. Claude Code 안에서는 /mcp. 연결된 서버 옆에 도구 개수가 나오고, 원격 OAuth 서버 인증과 서버 끄기도 여기서 한다. 시작이 느린 서버라면 MCP_TIMEOUT 으로 시작 대기 시간을 바꿀 수 있다. 문서 예시 MCP_TIMEOUT=10000 claude 가 10초. 원격 서버를 지우면 Claude Code가 저장해 둔 그 서버의 OAuth 토큰과 클라이언트 등록도 같이 지운다.

4단계: 도구 권한을 정한다 — 읽기 도구만 허용 규칙에

기본 모드(화면 표시는 Manual)는 도구마다 처음 쓸 때 승인을 묻고, MCP 도구에도 승인 창이 뜬다. 귀찮다고 서버 전체를 허용 규칙에 넣으면? 그 서버의 쓰기 도구까지 승인 없이 돈다. 그래서 읽기 도구만 이름으로. 여기서 읽기는 바깥 상태를 바꾸지 않는다는 뜻이지, 아무것도 내보내지 않는다는 뜻은 아니다. 주소로 이동하는 도구는 그 주소에 실린 글자를 상대 서버로 보낸다. 승인 없이 열 도구는 그것까지 감수할 수 있는지로 고를 것.

{
  "permissions": {
    "allow": [
      "mcp__<SERVER_NAME>__<READ_TOOL_1>",
      "mcp__<SERVER_NAME>__<READ_TOOL_2>"
    ],
    "ask": [
      "mcp__<SERVER_NAME>__<WRITE_TOOL>"
    ]
  }
}

사용자 설정 ~/.claude/settings.json 에 두면 내 모든 프로젝트에, 프로젝트의 .claude/settings.json 에 두면 그 폴더에서 일하는 모두에게 걸린다. /permissions 를 열면 규칙마다 어느 파일에서 왔는지 보인다.

mcp__<서버> · mcp__<서버>__*: 그 서버의 도구 전부
mcp__<서버>__<도구>: 도구 하나
mcp__<서버>__get_* 처럼 서버 이름 뒤에 붙인 글롭은 허용 규칙에서도 된다. mcp__* 처럼 서버 이름 없이 쓴 허용 글롭은 경고와 함께 건너뛰고, 아무것도 허용하지 않는다
서버 이름에 . 이나 공백이 있으면 _ 로 바꿔 적는다(my.server → mcp__my_server__*)

걸리기 쉬운 곳은 순서. 규칙은 deny → ask → allow 차례로 보고, 처음 맞는 것이 결과가 된다. 더 구체적인 규칙이라고 먼저 보는 것도 아니고. 그래서 ask 에 mcp__<SERVER_NAME>__* 를 넣으면 위의 읽기 도구 허용까지 덮여 매번 묻는다. 묻게 할 도구는 이름이나 좁은 글롭으로 따로 적을 것.

훅으로 막는다면 매처 규칙이 또 다르다. 훅 매처에 mcp__memory 처럼 서버 이름만 쓰면 아무 도구에도 맞지 않고, 서버 전체는 mcp__memory__.* 처럼 .* 를 붙여야 한다. 훅 설정의 기초는 7편에.

붙이고 나서 먼저 막은 것: 버전 · 실행 방식 · 사용 통계 · 쓰기 도구

여기부터는 우리가 브라우저 진단용 서버를 붙일 때 본 네 가지(아래 상자). 1~3은 붙이는 명령에 넣고, 4는 붙인 다음 권한에서 정한다.

버전을 적어 고정한다. 패키지가 바뀌는 때를 내가 고르려고.
서버가 띄우는 프로그램이 어떻게 뜨는지. 브라우저를 다루는 서버라면 창 없이 뜨는지, 내가 로그인해 둔 프로필이 아니라 따로 떨어진 프로필을 쓰는지. 옵션 이름은 서버마다 달라서 그 서버의 설명서나 --help 로 확인한다.
사용 통계를 보내는지. 보낸다면 끄는 옵션부터 찾는다.
쓰기 도구는 승인 뒤에. 읽기 도구만 승인 없이 쓰게 하고, 클릭 · 입력 · 업로드 · 스크립트 실행 같은 도구는 승인 대상으로 남긴다. 우리는 이 선을 훅에 그었다(아래 상자). 4단계의 허용 · ask 규칙으로 그어도 된다.

공식 문서의 경고도 같은 쪽. 「연결하기 전에 각 서버를 믿을 수 있는지 확인하라. 외부 콘텐츠를 가져오는 서버는 프롬프트 인젝션 위험에 노출될 수 있다.」 아무 페이지나 읽어 오는 브라우저형 서버가 바로 그 경우라, 우리는 붙인 뒤에도 쓰기 도구를 승인 뒤에 남겨 뒀다.

실제로 겪은 일

10월 3일, 우리 쪽 Claude Code에 브라우저 진단용 MCP 서버를 하나 붙였다. 버전은 고정, 브라우저는 화면 없이 격리된 프로필로, 사용 통계 전송(텔레메트리)은 끔. 그다음 손본 곳이 도구 권한. 훅에서 읽기 전용 진단 도구만 승인 없이 지나가게 했고, 클릭 · 입력 · 업로드 · 스크립트 실행 도구는 계속 승인을 거치게 남겼다.

내 설정 점검표: 클로드 코드 MCP 설정

서버가 어느 범위에 붙었는지 claude mcp get 으로 봤나. 같은 이름이 여러 범위에 있으면 local 이 이긴다.
claude mcp list 에 ✔ Connected 가 뜨나. ! Needs authentication 이면 /mcp 에서 인증.
키 값이 명령줄 · .mcp.json · 저장소에 그대로 들어가 있지 않나. .mcp.json 엔 ${API_KEY} 같은 자리만.
남이 만든 저장소를 claude -p 로 돌리기 전에 .mcp.json 을 열어 봤나.
내 컴퓨터에서 도는 서버의 패키지에 버전을 적었나.
허용 규칙에 서버 전체(mcp__<서버>__*)를 넣지 않았나. 읽기 도구만 이름으로.
ask 에 서버 전체를 넣어서 허용 규칙을 덮고 있지 않나.
바깥 페이지를 읽어 오는 서버라면 쓰기 도구가 승인 뒤에 있나.

같이 읽을 글

7편 — Claude Code 권한 설정(permissions)과 hooks 예시: auto mode에서 계속 막힐 때 손본 settings.json 세 곳: 허용 규칙과 훅의 기초. 4단계 규칙을 넣을 settings.json 자리.
2편 — Claude Code 설치(클로드코드 설치)부터 첫 자동화까지: 리눅스에서 매일 도는 작업 만들기: MCP 서버를 안 부르는 플래그까지 써 가며 claude -p 입력 토큰을 잰 기록.

다음 글은 클로드 코드 서브에이전트 사용법. Claude Code에서 서브에이전트를 만들고 일을 맡기는 방법을 다룬다.

다음에 다뤘으면 하는 질문은 댓글로 남기거나 codenara.contact@gmail.com 으로 보내 주세요. 받은 질문은 다음 글감으로 씁니다.