> ## Content Index
> Fetch the complete content index at: https://zerodraftlab.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# Claude Code MCP 설정법: 서버 추가 명령어와 범위·보안
- URL: https://zerodraftlab.com/claude-code-mcp-guide/
- Published: 2026-11-01T01:38:56.000Z
- Updated: 2026-11-02T04:20:49.000Z
- Description: Claude Code에 MCP 서버를 추가하는 명령어를 정리했다. HTTP와 stdio 차이, local·project·user 범위, OAuth 로그인, 보안 주의점까지 공식 문서로 확인했다.
- Author: JooMong
- Tags: 무료

MCP(Model Context Protocol)는 Claude Code를 Notion, Sentry, 데이터베이스 같은 외부 도구에 연결하는 표준이다. 등록은 `claude mcp add` 한 줄이면 된다. 실수는 대개 두 곳에서 나온다. 설정이 저장될 범위를 잘못 고르거나, 믿을 수 있는지 확인하지 않은 서버를 붙이는 경우다. 아래 명령은 2026년 11월 1일에 [Anthropic 공식 MCP 문서](https://code.claude.com/docs/en/mcp?ref=zerodraftlab.com)와 `claude mcp add --help` 출력(v2.1.316)으로 확인했다.

본문의 "Astra 첨언"은 OpenAI Codex의 GPT-6 Astra가 이 글을 읽고 남긴 말이다. 사람의 사용 경험담이 아니라 코딩 에이전트 관점의 판단이다.

## Claude Code에 MCP 서버 추가하기: 원격과 로컬

서버는 위치에 따라 추가하는 방식이 다르다.

**원격 HTTP 서버**는 공식 문서가 클라우드 서비스에 권장하는 방식이다.

```bash
claude mcp add --transport http notion https://mcp.notion.com/mcp
```

토큰을 헤더로 넘겨야 하는 서버는 아래처럼 등록한다.

```bash
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"
```

**로컬 stdio 서버**는 내 컴퓨터에서 프로세스로 실행된다.

```bash
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server
```

**SSE**는 더 이상 권장되지 않는다. 서버가 HTTP를 지원하면 HTTP로 등록한다.

## \-- 는 왜 필요한가

stdio 서버 명령에서 가장 헷갈리는 부분이 `--`다. 이 두 글자는 Claude Code의 옵션과 서버 실행 명령을 나눈다. `--` 뒤에 있는 내용은 그대로 서버에 전달된다.

```bash
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    |

```bash
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`를 실행한다.

## 확인하고 지우기

```bash
claude mcp list          # 등록한 서버 전체 보기
claude mcp get notion    # 서버 하나 자세히 보기
claude mcp remove notion # 서버 지우기
```

Claude Code 안에서는 `/mcp`로 연결 상태를 본다.

> **Astra 첨언.** 연결 뒤에는 알고 있는 문서 하나를 읽게 해 계정과 워크스페이스를 확인한다. 연결 성공만으로 원하는 자료에 접근할 수 있다고 판단하지 않는다. 검색 결과가 비어 있으면 자료가 없다는 결론보다 검색 범위와 권한을 먼저 확인한다.

## 로그인이 필요한 서버

OAuth 2.0을 지원하는 원격 서버는 세션 안에서 로그인한다. 앞에서 본 헤더 방식으로 인증하는 서버도 있다. 세션 안에서 `/mcp`를 실행하고 브라우저 안내를 따르면 된다. 토큰은 저장되고 자동으로 갱신된다.

```bash
claude mcp login sentry
claude mcp logout sentry
```

셸에서는 위 명령으로 세션 없이 처리할 수 있다. 서버를 지워도 인증 서버 쪽의 토큰이 취소되지는 않는다. 취소까지 하려면 지원되는 서버에서 `claude mcp logout`을 먼저 실행한 뒤 `remove`를 실행한다.

## MCP 보안: 붙이기 전에 볼 것

공식 문서의 경고는 이렇다. 연결하기 전에 각 서버를 믿을 수 있는지 확인해야 한다. 외부 내용을 가져오는 서버는 프롬프트 인젝션 위험에 노출될 수 있다. 프롬프트 인젝션은 웹페이지나 이슈 본문에 숨겨 둔 지시로 에이전트를 조종하는 공격이다.

아래 확인 항목은 공식 문서 내용이 아니라 내 기준이다.

- 만든 곳이 서비스 공식 조직인지 본다.
- 처음에는 읽기 권한만 주는 토큰을 쓴다. 서비스가 지원할 때의 이야기다.
- 외부 글을 읽는 서버와 내부 데이터를 쓰는 서버를 함께 붙일 때 특히 조심한다. 읽은 글의 지시가 쓰기 행동으로 이어질 수 있기 때문이다.

> **Astra 첨언.** 외부 쓰기 요청이 시간 초과로 끝났다면 같은 요청을 바로 반복하지 않는다. 대상 서비스에서 반영 여부를 먼저 조회한다. 응답만 유실된 경우에는 재시도가 중복 생성이나 중복 발송으로 이어질 수 있다.

## 결과가 잘리거나 사용량이 늘 때

MCP 도구 출력이 1만 토큰을 넘으면 경고가 뜨고, 기본 한도는 2만 5천 토큰이다. 늘리려면 환경 변수를 쓴다.

```bash
MAX_MCP_OUTPUT_TOKENS=50000 claude
```

서버를 많이 붙여도 도구 정의는 기본으로 미뤄 불러온다. 도구를 쓰기 전까지는 도구 이름과 서버 안내만 컨텍스트에 들어간다. 그래도 공식 [비용 문서](https://code.claude.com/docs/en/costs?ref=zerodraftlab.com)는 두 가지를 권한다. `gh`, `aws`, `gcloud`처럼 CLI가 있는 도구는 CLI가 컨텍스트를 덜 쓰니 CLI를 쓴다. 쓰지 않는 서버는 `/mcp`에서 끈다. 컨텍스트가 무엇으로 차 있는지는 `/context`로 본다.

## 첫 서버는 하나만

여러 개를 한 번에 붙이지 않는 편이 낫다. 복사해서 붙여 넣는 일이 가장 잦은 도구 하나부터 연결한다. OpenAI도 [Codex 문서](https://developers.openai.com/codex/mcp?ref=zerodraftlab.com)에서 손으로 반복하던 일을 분명히 없애 주는 도구 한두 개로 시작하라고 권한다.

기본 쓰는 법은 [클로드 코드 사용법](https://zerodraftlab.com/claude-code-usage-guide/)에, Codex의 MCP 설정 차이는 [Codex와 Claude Code 비교](https://zerodraftlab.com/codex-vs-claude-code/)에 적었다.

MCP로 맡기는 일이 늘수록 에이전트의 "확인했다"가 무거워진다. 내 사이트는 그 말 뒤에서 100일 넘게 깨져 있었다. [무료로 사건 읽기](https://zerodraftlab.com/agent-verified-site-down/)