Claude Code MCP 설정법: 서버 추가 명령어와 범위·보안
Claude Code에 MCP 서버를 추가하는 명령어를 정리했다. HTTP와 stdio 차이, local·project·user 범위, OAuth 로그인, 보안 주의점까지 공식 문서로 확인했다.
MCP(Model Context Protocol)는 Claude Code를 Notion, Sentry, 데이터베이스 같은 외부 도구에 연결하는 표준이다. 등록은 claude mcp add 한 줄이면 된다. 실수는 대개 두 곳에서 나온다. 설정이 저장될 범위를 잘못 고르거나, 믿을 수 있는지 확인하지 않은 서버를 붙이는 경우다. 아래 명령은 2026년 11월 1일에 Anthropic 공식 MCP 문서와 claude mcp add --help 출력(v2.1.316)으로 확인했다.
본문의 "Astra 첨언"은 OpenAI Codex의 GPT-6 Astra가 이 글을 읽고 남긴 말이다. 사람의 사용 경험담이 아니라 코딩 에이전트 관점의 판단이다.
Claude Code에 MCP 서버 추가하기: 원격과 로컬
서버는 위치에 따라 추가하는 방식이 다르다.
원격 HTTP 서버는 공식 문서가 클라우드 서비스에 권장하는 방식이다.
claude mcp add --transport http notion https://mcp.notion.com/mcp토큰을 헤더로 넘겨야 하는 서버는 아래처럼 등록한다.
claude mcp add --transport http secure-api https://api.example.com/mcp \
--header "Authorization: Bearer your-token"로컬 stdio 서버는 내 컴퓨터에서 프로세스로 실행된다.
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
-- npx -y airtable-mcp-serverSSE는 더 이상 권장되지 않는다. 서버가 HTTP를 지원하면 HTTP로 등록한다.
-- 는 왜 필요한가
stdio 서버 명령에서 가장 헷갈리는 부분이 --다. 이 두 글자는 Claude Code의 옵션과 서버 실행 명령을 나눈다. -- 뒤에 있는 내용은 그대로 서버에 전달된다.
claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080--가 없으면 --port를 Claude Code의 옵션으로 해석한다. 또 하나 주의할 점이 있다. --env는 값을 여러 개 받을 수 있어서 바로 뒤에 서버 이름을 쓰면 안 된다. 공식 문서처럼 --env와 서버 이름 사이에 --transport stdio 같은 다른 옵션을 둔다.
MCP 범위: local, project, user
범위는 이 서버를 어디에서 쓸지 정한다. --scope로 지정하고, 지정하지 않으면 local이다.
| 범위 | 쓰이는 곳 | 팀 공유 | 저장 위치 |
|---|---|---|---|
| local (기본값) | 현재 프로젝트만 | 안 됨 | ~/.claude.json |
| project | 현재 프로젝트만 | 버전 관리로 공유 | 프로젝트 루트의 .mcp.json |
| user | 내 모든 프로젝트 | 안 됨 | ~/.claude.json |
claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic같은 서버가 여러 범위에 있으면 local, project, user 순서로 우선한다. 설정값은 합쳐지지 않는다. 그래서 "분명히 고쳤는데 안 바뀐다"면 다른 범위의 정의가 이기고 있을 수 있다.
project 범위는 비밀값을 조심해야 한다. .mcp.json은 저장소에 함께 올라가는 파일이다. 토큰을 직접 적으면 저장소를 보는 사람에게 노출된다. .mcp.json에 있는 서버는 대화형 세션에서 쓰기 전에 승인을 묻는다. 승인 선택을 되돌리려면 claude mcp reset-project-choices를 실행한다.
확인하고 지우기
claude mcp list # 등록한 서버 전체 보기
claude mcp get notion # 서버 하나 자세히 보기
claude mcp remove notion # 서버 지우기Claude Code 안에서는 /mcp로 연결 상태를 본다.
Astra 첨언. 연결 뒤에는 알고 있는 문서 하나를 읽게 해 계정과 워크스페이스를 확인한다. 연결 성공만으로 원하는 자료에 접근할 수 있다고 판단하지 않는다. 검색 결과가 비어 있으면 자료가 없다는 결론보다 검색 범위와 권한을 먼저 확인한다.
로그인이 필요한 서버
OAuth 2.0을 지원하는 원격 서버는 세션 안에서 로그인한다. 앞에서 본 헤더 방식으로 인증하는 서버도 있다. 세션 안에서 /mcp를 실행하고 브라우저 안내를 따르면 된다. 토큰은 저장되고 자동으로 갱신된다.
claude mcp login sentry
claude mcp logout sentry셸에서는 위 명령으로 세션 없이 처리할 수 있다. 서버를 지워도 인증 서버 쪽의 토큰이 취소되지는 않는다. 취소까지 하려면 지원되는 서버에서 claude mcp logout을 먼저 실행한 뒤 remove를 실행한다.
MCP 보안: 붙이기 전에 볼 것
공식 문서의 경고는 이렇다. 연결하기 전에 각 서버를 믿을 수 있는지 확인해야 한다. 외부 내용을 가져오는 서버는 프롬프트 인젝션 위험에 노출될 수 있다. 프롬프트 인젝션은 웹페이지나 이슈 본문에 숨겨 둔 지시로 에이전트를 조종하는 공격이다.
아래 확인 항목은 공식 문서 내용이 아니라 내 기준이다.
- 만든 곳이 서비스 공식 조직인지 본다.
- 처음에는 읽기 권한만 주는 토큰을 쓴다. 서비스가 지원할 때의 이야기다.
- 외부 글을 읽는 서버와 내부 데이터를 쓰는 서버를 함께 붙일 때 특히 조심한다. 읽은 글의 지시가 쓰기 행동으로 이어질 수 있기 때문이다.
Astra 첨언. 외부 쓰기 요청이 시간 초과로 끝났다면 같은 요청을 바로 반복하지 않는다. 대상 서비스에서 반영 여부를 먼저 조회한다. 응답만 유실된 경우에는 재시도가 중복 생성이나 중복 발송으로 이어질 수 있다.
결과가 잘리거나 사용량이 늘 때
MCP 도구 출력이 1만 토큰을 넘으면 경고가 뜨고, 기본 한도는 2만 5천 토큰이다. 늘리려면 환경 변수를 쓴다.
MAX_MCP_OUTPUT_TOKENS=50000 claude서버를 많이 붙여도 도구 정의는 기본으로 미뤄 불러온다. 도구를 쓰기 전까지는 도구 이름과 서버 안내만 컨텍스트에 들어간다. 그래도 공식 비용 문서는 두 가지를 권한다. gh, aws, gcloud처럼 CLI가 있는 도구는 CLI가 컨텍스트를 덜 쓰니 CLI를 쓴다. 쓰지 않는 서버는 /mcp에서 끈다. 컨텍스트가 무엇으로 차 있는지는 /context로 본다.
첫 서버는 하나만
여러 개를 한 번에 붙이지 않는 편이 낫다. 복사해서 붙여 넣는 일이 가장 잦은 도구 하나부터 연결한다. OpenAI도 Codex 문서에서 손으로 반복하던 일을 분명히 없애 주는 도구 한두 개로 시작하라고 권한다.
기본 쓰는 법은 클로드 코드 사용법에, Codex의 MCP 설정 차이는 Codex와 Claude Code 비교에 적었다.
MCP로 맡기는 일이 늘수록 에이전트의 "확인했다"가 무거워진다. 내 사이트는 그 말 뒤에서 100일 넘게 깨져 있었다. 무료로 사건 읽기