MCP 서버 연결 빠른 시작

기준일: 2026-07-26
공식 기준: Connect to MCP servers

개요

Model Context Protocol (MCP)는 Claude Code가 이슈 트래커 검색, DB 조회, 브라우저 제어 등 내장 도구 밖의 도구를 쓰게 합니다. 도구는 머신 로컬 또는 호스팅 MCP 서버에서 옵니다.

이 가이드는 CLI로 MCP 서버를 끝에서 끝까지 연결합니다. 끝나면 서버가 응답하고, 디스크 설정 위치를 알며, 흔한 연결 오류를 고칠 수 있습니다. Desktop·VS Code·웹 등 다른 표면: Connect from other surfaces. 전체 구성: MCP reference.

핵심 개념

항목	내용
추가	세션 밖 `claude mcp add` (대화 전 구성)
기본 스코프	`local` — 나 + 현재 프로젝트
검증	`claude mcp list` / 세션 `/mcp`
제거	`claude mcp remove <name>` (컨텍스트 절약)

상세

시작 전

Claude Code 설치·인증
프로젝트 디렉터리에서 터미널 (빈 디렉터리도 OK)

서버 추가 및 검증

예제는 인증 없는 호스팅 Claude Code docs MCP입니다. 다른 서버도 흐름은 동일(로그인형은 추가 단계).

1. 추가

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

claude mcp add — 등록
--transport http — URL 호스팅
claude-code-docs — 임의 이름 (도구 라벨·remove에 사용)
URL — 서버 엔드포인트

확인 출력 예: Added HTTP MCP server ... to local config + File modified:. local config = 이 프로젝트·본인만. 모든 프로젝트면 user scope.

2. 연결 상태

claude mcp list

상태	의미
`✔ Connected`	사용 가능
`! Connected · tools fetch failed`	연결됐으나 도구 목록 실패 → `claude mcp get <name>`
`! Needs authentication`	브라우저 로그인 또는 `--header` 토큰 필요
`✘ Failed to connect` / `Connection error`	트러블슈팅
`⏸ Pending approval`	프로젝트 스코프 미승인 → `claude` 실행 후 승인

구형 Windows 콘솔은 √/×로 표시될 수 있음.

3. 사용

claude

Use the claude-code-docs server to look up what MCP_TIMEOUT does

서버 이름을 프롬프트에 넣으면 다른 도구(WebFetch 등) 대신 해당 서버를 강제할 수 있습니다. 첫 도구 호출 시 권한 승인. 출력 라벨에 서버 이름이 붙으면 MCP 경유 확인.

4. 제거 (선택)

claude mcp remove claude-code-docs

연결 서버마다 도구 설명·서버 지시가 컨텍스트를 쓰므로 안 쓰는 서버는 제거하세요.

저장 위치

Scope	파일	가용 범위
`local` (기본)	`~/.claude.json`의 해당 프로젝트 항목	나, 이 프로젝트
`project`	프로젝트 루트 `.mcp.json`	클론한 전원
`user`	`~/.claude.json` 최상위 `mcpServers`	나, 전 프로젝트

Windows: %USERPROFILE%\.claude.json. CLAUDE_CONFIG_DIR 설정 시 그 안. claude mcp get <name>으로 스코프 확인. 다중 스코프 우선순위: MCP installation scopes.

세션 안 관리는 /mcp. PowerShell/CMD에서도 claude mcp add 동일.

서버 스코프 변경

스코프는 추가 시 고정 → 제거 후 재추가.

claude mcp remove claude-code-docs --scope local

모든 프로젝트 (user):

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

팀 공유 (project):

claude mcp add --scope project --transport http claude-code-docs https://code.claude.com/docs/mcp

.mcp.json을 커밋. 동료는 클론 후 승인 프롬프트.

추가 예제

로컬 stdio (Playwright)

머신 서브프로세스로 실행. Node.js 18+.

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

-- 뒤가 시작 명령. --transport 없음(stdio 기본). 첫 list는 npx 다운로드 중 실패할 수 있음 → 재시도. 사용 예:

Use playwright to open https://example.com and tell me the page title

다른 브라우저: --browser firefox를 명령 뒤에.

로그인 필요 (Sentry OAuth 예)

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

list에 ! Needs authentication → 세션 /mcp → 서버 선택 → Authenticate → 브라우저 승인. 정적 토큰은 --header "Authorization: Bearer <token>" (GitHub 예).

`.mcp.json` 직접 편집

프로젝트 루트 예:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

HTTP: url. stdio: command/args. 저장 후 새 세션. 프로젝트 서버 첫 등장 시 승인(클론 저장소가 임의 프로세스 실행 방지). 거절 후 재승인: claude mcp reset-project-choices.

다른 표면에서 연결

Claude Code Desktop: Connectors UI
Claude Desktop 채팅 앱 (별개): macOS/WSL에서 claude mcp add-from-claude-desktop
VS Code: VS Code MCP
Claude Code on the web: 저장소 .mcp.json
claude.ai connectors: claude.ai/customize/connectors — 동일 계정 CLI 로그인 시 자동 로드

트러블슈팅

/mcp에 서버 없음

다른 프로젝트에서 add한 local 서버 → 현재 프로젝트에서 재추가 또는 --scope user
잘못된 경로: 올바른 것은 ~/.claude.json, <project>/.mcp.json. ~/.claude/.mcp.json 등은 읽지 않음

Failed to connect / Connection error

HTTP 404: v2.1.191+ /mcp에서 MCP endpoint not found at <url> — URL·문서 경로 확인 후 remove/re-add
curl -I <url>: 404/405=살아 있음(POST only 가능), 401/403=인증 필요, 무응답=네트워크
stdio: 명령을 터미널에서 직접 실행. 대기하면 서버 OK → claude mcp get 명령 일치·-- 누락 여부. 에러면 Node/브라우저 등 메시지 확인

시작 타임아웃

MCP_TIMEOUT=60000 claude

PowerShell: $env:MCP_TIMEOUT = "60000"; claude

Server already exists — remove 또는 다른 이름. 다중 스코프면 remove --scope

연결됐으나 도구 없음 — /mcp 도구 목록. 빈 목록은 보통 필수 env 누락 → --env KEY=value 또는 .mcp.json env

.mcp.json 변경 미반영 — 세션 재시작. /mcp parse 경고. 이전 거절: claude mcp reset-project-choices

OAuth 실패 — /mcp Authenticate 재시도. 브라우저 미개방 시 터미널 URL 수동 오픈

체크리스트

claude mcp add 후 list에서 Connected 확인
세션에서 서버 이름 도구 호출·권한 승인
팀 공유면 project .mcp.json 커밋 + 승인 흐름 안내
실패 시 status 표와 curl/직접 명령으로 원인 분기

다음 단계

기준일

문서 작성·동기화 기준일: 2026-07-26
원문: https://code.claude.com/docs/en/mcp-quickstart

MCP 서버 연결 빠른 시작

기준일: 2026-07-26
공식 기준: Connect to MCP servers

개요

핵심 개념

항목	내용
추가	세션 밖 `claude mcp add` (대화 전 구성)
기본 스코프	`local` — 나 + 현재 프로젝트
검증	`claude mcp list` / 세션 `/mcp`
제거	`claude mcp remove <name>` (컨텍스트 절약)

상세

시작 전

Claude Code 설치·인증
프로젝트 디렉터리에서 터미널 (빈 디렉터리도 OK)

서버 추가 및 검증

예제는 인증 없는 호스팅 Claude Code docs MCP입니다. 다른 서버도 흐름은 동일(로그인형은 추가 단계).

1. 추가

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

claude mcp add — 등록
--transport http — URL 호스팅
claude-code-docs — 임의 이름 (도구 라벨·remove에 사용)
URL — 서버 엔드포인트

확인 출력 예: Added HTTP MCP server ... to local config + File modified:. local config = 이 프로젝트·본인만. 모든 프로젝트면 user scope.

2. 연결 상태

claude mcp list

상태	의미
`✔ Connected`	사용 가능
`! Connected · tools fetch failed`	연결됐으나 도구 목록 실패 → `claude mcp get <name>`
`! Needs authentication`	브라우저 로그인 또는 `--header` 토큰 필요
`✘ Failed to connect` / `Connection error`	트러블슈팅
`⏸ Pending approval`	프로젝트 스코프 미승인 → `claude` 실행 후 승인

구형 Windows 콘솔은 √/×로 표시될 수 있음.

3. 사용

claude

Use the claude-code-docs server to look up what MCP_TIMEOUT does

4. 제거 (선택)

claude mcp remove claude-code-docs

연결 서버마다 도구 설명·서버 지시가 컨텍스트를 쓰므로 안 쓰는 서버는 제거하세요.

저장 위치

Scope	파일	가용 범위
`local` (기본)	`~/.claude.json`의 해당 프로젝트 항목	나, 이 프로젝트
`project`	프로젝트 루트 `.mcp.json`	클론한 전원
`user`	`~/.claude.json` 최상위 `mcpServers`	나, 전 프로젝트

Windows: %USERPROFILE%\.claude.json. CLAUDE_CONFIG_DIR 설정 시 그 안. claude mcp get <name>으로 스코프 확인. 다중 스코프 우선순위: MCP installation scopes.

세션 안 관리는 /mcp. PowerShell/CMD에서도 claude mcp add 동일.

서버 스코프 변경

스코프는 추가 시 고정 → 제거 후 재추가.

claude mcp remove claude-code-docs --scope local

모든 프로젝트 (user):

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

팀 공유 (project):

claude mcp add --scope project --transport http claude-code-docs https://code.claude.com/docs/mcp

.mcp.json을 커밋. 동료는 클론 후 승인 프롬프트.

추가 예제

로컬 stdio (Playwright)

머신 서브프로세스로 실행. Node.js 18+.

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

-- 뒤가 시작 명령. --transport 없음(stdio 기본). 첫 list는 npx 다운로드 중 실패할 수 있음 → 재시도. 사용 예:

Use playwright to open https://example.com and tell me the page title

다른 브라우저: --browser firefox를 명령 뒤에.

로그인 필요 (Sentry OAuth 예)

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

list에 ! Needs authentication → 세션 /mcp → 서버 선택 → Authenticate → 브라우저 승인. 정적 토큰은 --header "Authorization: Bearer <token>" (GitHub 예).

`.mcp.json` 직접 편집

프로젝트 루트 예:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

다른 표면에서 연결

Claude Code Desktop: Connectors UI
Claude Desktop 채팅 앱 (별개): macOS/WSL에서 claude mcp add-from-claude-desktop
VS Code: VS Code MCP
Claude Code on the web: 저장소 .mcp.json
claude.ai connectors: claude.ai/customize/connectors — 동일 계정 CLI 로그인 시 자동 로드

트러블슈팅

/mcp에 서버 없음

다른 프로젝트에서 add한 local 서버 → 현재 프로젝트에서 재추가 또는 --scope user
잘못된 경로: 올바른 것은 ~/.claude.json, <project>/.mcp.json. ~/.claude/.mcp.json 등은 읽지 않음

Failed to connect / Connection error

HTTP 404: v2.1.191+ /mcp에서 MCP endpoint not found at <url> — URL·문서 경로 확인 후 remove/re-add
curl -I <url>: 404/405=살아 있음(POST only 가능), 401/403=인증 필요, 무응답=네트워크
stdio: 명령을 터미널에서 직접 실행. 대기하면 서버 OK → claude mcp get 명령 일치·-- 누락 여부. 에러면 Node/브라우저 등 메시지 확인

시작 타임아웃

MCP_TIMEOUT=60000 claude

PowerShell: $env:MCP_TIMEOUT = "60000"; claude

Server already exists — remove 또는 다른 이름. 다중 스코프면 remove --scope

연결됐으나 도구 없음 — /mcp 도구 목록. 빈 목록은 보통 필수 env 누락 → --env KEY=value 또는 .mcp.json env

.mcp.json 변경 미반영 — 세션 재시작. /mcp parse 경고. 이전 거절: claude mcp reset-project-choices

OAuth 실패 — /mcp Authenticate 재시도. 브라우저 미개방 시 터미널 URL 수동 오픈

MCP 서버 연결 빠른 시작

개요

핵심 개념

상세

시작 전

서버 추가 및 검증

1. 추가

2. 연결 상태

3. 사용

4. 제거 (선택)

저장 위치

서버 스코프 변경

추가 예제

로컬 stdio (Playwright)

로그인 필요 (Sentry OAuth 예)

.mcp.json 직접 편집

다른 표면에서 연결

트러블슈팅

체크리스트

다음 단계

기준일

관련 가이드

MCP 서버 연결 빠른 시작

개요

핵심 개념

상세

시작 전

서버 추가 및 검증

1. 추가

2. 연결 상태

3. 사용

4. 제거 (선택)

저장 위치

서버 스코프 변경

추가 예제

로컬 stdio (Playwright)

로그인 필요 (Sentry OAuth 예)

.mcp.json 직접 편집

다른 표면에서 연결

트러블슈팅

체크리스트

다음 단계

기준일

관련 가이드

`.mcp.json` 직접 편집

`.mcp.json` 직접 편집