MCP 서버 연결하기

MCP 서버 연결하기 (퀵스타트)

MCP 서버 하나를 처음부터 끝까지 Claude Code CLI로 연결해 보는 가이드예요. 서버를 추가하고, 연결 상태를 확인하고, 설정이 어디에 저장되는지 찾아본 뒤 흔한 연결 오류를 고치는 순서로 진행해요. Model Context Protocol(MCP) 덕분에 이슈 트래커 검색, 데이터베이스 조회, 브라우저 제어처럼 빌트인 도구를 넘어서는 작업까지 Claude Code가 할 수 있게 돼요.

출처: 공식문서

본문

시작하기 전에

준비물은 두 가지예요.

  • Claude Code 설치와 인증
  • 프로젝트 디렉토리에서 연 터미널(빈 디렉토리여도 상관없어요)

서버 추가하고 확인하기

아래 예시는 Claude Code 문서 MCP 서버에 연결해요. 이 서버는 Claude Code 문서를 풀텍스트 검색해 주는 호스팅 서버라, 인증이나 특별한 설정이 필요 없어서 첫 연결 테스트로 딱 좋아요.

절차는 어떤 서버든 같아요. 추가 → 연결 상태 확인 → 세션에서 사용, 마지막에 정리하는 단계까지요.

1. MCP 서버 추가하기

Claude Code에 서버를 등록해요. claude 세션 안이 아니라 터미널에서 실행해야 해요. 대화를 시작하기 전에 서버를 설정하는 거예요.

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

명령의 각 부분을 보면:

  • claude mcp add: Claude Code에 서버를 등록해요.
  • --transport http: 서버가 로컬 프로세스가 아니라 URL에 호스팅되어 있어요.
  • claude-code-docs: 사용자가 짓는 이름이에요. 같은 서버를 docs라고 불러도 동일하게 동작해요. 이 이름으로 Claude 출력에서 서버의 도구를 표시하고, claude mcp remove 같은 명령에서 서버를 지칭해요.
  • https://code.claude.com/docs/mcp: 서버가 호스팅된 URL이에요.

명령은 Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config 같은 확인 메시지와 함께, 작성된 설정 파일을 알려주는 File modified: 줄을 출력해요. local config는 이 서버가 이 프로젝트에서만, 사용자에게만 등록됐다는 뜻이에요. 다른 프로젝트에서 Claude Code를 시작하면 이 서버는 활성화되지 않아요. 모든 프로젝트에 한 번만 등록하려면 user 스코프로 추가하면 돼요.

2. 연결 상태 확인하기

서버가 목록에 있는지, 상태가 어떤지 확인해요.

claude mcp list

서버에 상태 표시가 붙어요.

상태 의미
✔ Connected 사용 준비 완료. claude-code-docs에서는 이 상태가 나와야 해요.
! Connected · tools fetch failed 서버는 연결됐지만 도구 목록을 가져오지 못했어요. claude mcp get <name>으로 오류 상세를 확인하세요.
! Needs authentication 서버에 연결은 되지만 브라우저 로그인, 혹은 --header로 전달한 토큰이 필요해요.
✘ Failed to connect 서버가 응답하지 않았어요.
✘ Connection error 연결 시도가 오류를 던졌어요.
⏸ Pending approval (run claude to approve) 아직 승인하지 않은 프로젝트 스코프 서버예요.
⊘ Disabled for this project (re-enable via /mcp) 프로젝트의 disabledMcpServers 목록으로 이 프로젝트에서 꺼 둔 서버예요.

Windows 10 기본 콘솔 같은 일부 레거시 Windows 콘솔은 이런 유니코드 글리프를 지원하지 않아서 ✔와 ✘ 대신 √와 ×로 보여줘요.

3. 서버 사용하기

세션을 시작하고 새 서버를 이름으로 지칭해서 사용하라고 요청해요.

claude

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

보통은 프롬프트에서 서버 이름을 지정할 필요가 없어요. Claude가 관련 도구를 스스로 고르니까요. 여기서 이름을 지정한 건 데모가 꼭 새 서버를 통과하게 하려는 것이에요. 같은 질문에 답할 수 있는 웹 fetch 같은 다른 도구로 빠지지 않게요.

Claude가 서버를 처음 호출할 때 권한을 물으면 승인해요. Claude 출력의 도구 호출에 서버 이름이 붙는데, 이걸로 답이 Claude 빌트인 지식이 아니라 MCP 서버에서 왔음을 확인할 수 있어요.

4. 서버 제거하기 (선택)

claude mcp remove claude-code-docs

명령은 Removed MCP server "claude-code-docs" from local config와 함께 갱신된 파일을 알려주는 File modified: 줄을 출력해요. 연결된 서버는 각각 Claude의 컨텍스트 윈도우 공간을 차지해요(도구 이름과 서버 지시가 매 세션에 로드되니까요). 더 안 쓰는 서버는 제거해 두면 그 공간이 비어요.

서버가 저장되는 위치

claude mcp add 명령은 서버 정보를 설정 파일에 써요. 기본적으로 local 스코프로 등록돼요. 사용자에게만, 현재 프로젝트에서만 활성화되죠. --scope user를 주면 모든 프로젝트에 한 번 등록되고, --scope project를 주면 팀원과 공유돼요.

claude mcp add는 PowerShell을 포함한 모든 셸에서 똑같이 동작해요. claude 세션 안에서는 /mcp 명령으로 이미 추가한 서버를 확인·관리하면 돼요.

서버를 추가하는 다른 방법은 이 페이지 뒤에서 각각 다뤄요.

디스크에서 설정 찾기

claude mcp add는 --scope 플래그에 따라 두 파일에 걸쳐 세 가지 스코프 중 하나로 서버를 기록해요. 이 파일을 직접 편집할 필요는 없지만, 위치를 알면 디버깅과 버전 관리에 도움돼요.

스코프 파일 사용 가능 범위
local ~/.claude.json, 이 프로젝트 항목 아래 나만, 이 프로젝트에서만. 기본값
project 프로젝트 루트의 .mcp.json 프로젝트를 클론하는 모두
user ~/.claude.json, 최상위 mcpServers 키 아래 나만, 모든 프로젝트

Windows에서 ~/.claude.json은 %USERPROFILE%\.claude.json, 보통은 C:\Users\YourName\.claude.json으로 해석돼요. CLAUDE_CONFIG_DIR을 설정했다면 Claude Code는 그 디렉토리 안에서 .claude.json을 읽어요.

claude mcp get claude-code-docs로 어떤 스코프가 서버 정의를 들고 있는지 알 수 있어요.

서버 스코프 바꾸기

서버 스코프는 추가할 때 고정되므로, 스코프를 바꾸려면 항목을 제거하고 새 스코프로 다시 추가해야 해요.

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

위는 첫 번째 워크스루에서 추가한 local 항목(만약 제거하지 않았다면)을 없애는 명령이에요.

모든 프로젝트에서 쓰기

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

user 스코프로 다시 추가하면 열어 본 모든 프로젝트에서 활성화되면서도 사용자에게만 비공개로 유지돼요.

팀과 공유하기

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

project 스코프로 다시 추가하면 프로젝트 루트의 .mcp.json에 기록돼요. .mcp.json을 버전 관리에 커밋해 두면, 리포지토리를 클론하고 Claude Code를 시작한 팀원은 서버 승인 프롬프트를 보고 나서 서버를 연결하게 돼요.

추가 MCP 서버 예시

첫 워크스루는 로그인 없이 연결되는 호스팅 서버였어요. 아래는 흔한 두 가지 형태를 추가·확인·사용 흐름으로 다뤄요.

로컬 서버 추가하기

로컬 stdio 서버는 Claude Code가 URL로 접근하는 서비스가 아니라, 사용자 머신에서 서브프로세스로 시작하는 프로그램이에요. 브라우저, 파일시스템, 데이터베이스 소켓 같은 로컬 리소스에 접근해야 하는 도구에 쓰죠.

Playwright MCP 서버가 시도해 볼 만해요. Claude에게 탐색·클릭·읽기가 가능한 브라우저를 주고, 계정이 필요 없어요. npx로 실행되므로 Node.js 18 이상이 필요해요.

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

이 명령은 호스팅 예시와 세 가지가 달라요. --transport 플래그가 없고(로컬 서버는 기본 stdio 트랜스포트를 쓰니까), -- 구분자 뒤의 전부가 Claude Code가 실행할 서버 시작 명령이고, -y는 npx가 물어보지 않고 패키지를 설치하게 해요.

연결 확인은 claude mcp list로 해요. 첫 확인은 npx가 패키지를 다운로드하는 동안 ✘ Failed to connect로 보일 수 있으니 잠시 기다렸다 다시 실행해요. 다운로드가 끝나면 ✔ Connected로 바뀌어요.

브라우저가 필요하도록 요청해 보세요.

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

브라우저 창이 열리고 작업을 지켜볼 수 있어요. Claude 출력의 도구 호출에는 playwright 서버 이름과 browser_navigate 같은 동작이 붙어요.

로그인이 필요한 서버 연결하기

Sentry, Linear, Notion 같은 호스팅 서비스는 OAuth 뒤에서 MCP 서버를 운영해요. 서버 URL을 추가한 뒤 브라우저로 로그인하면 되죠. Sentry를 예로 들면:

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

추가 후 claude mcp list는 ! Needs authentication 상태를 보여줘요. 그다음 세션에서 /mcp를 열고, sentry를 골라 Enter, Authenticate를 선택하면 브라우저가 Sentry 로그인 페이지로 열려요. 승인하면 서버 상태가 connected로 바뀌어요.

정적 토큰으로 인증하는 서버는 추가할 때 --header "Authorization: Bearer ***"로 토큰을 받아요.

.mcp.json 직접 편집하기

스코프 표의 모든 파일은 서버 항목에 같은 JSON 형식을 써요. 이 섹션은 프로젝트 스코프 파일인 .mcp.json을 편집해요. 리포지토리에 커밋되어 팀의 configuration-as-code 역할을 하기 때문에 손으로 쓸 가치가 가장 큰 파일이죠.

프로젝트 루트에 .mcp.json을 만들어요. 아래 예시는 이 가이드의 두 서버, HTTP로 접근하는 호스팅 docs 서버와 로컬 stdio 프로세스인 Playwright 서버를 정의해요.

{
  "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 Code 세션을 시작하면 시작 시 .mcp.json을 읽어요.

Claude Code가 프로젝트 스코프 서버를 처음 보면 승인을 물어요. 클론한 리포지토리가 사용자 모르게 사용자 머신에서 프로세스를 실행하지 못하게 하는 프롬프트예요. 승인하거나, 놓쳤다면 나중에 /mcp에서 승인하면 돼요.

다른 화면에서 연결하기

이 가이드는 claude mcp CLI 명령을 썼지만, 모든 Claude Code 화면이 MCP 서버에 연결할 수 있어요.

  • Claude Code 데스크톱 앱: Connectors UI로 서버를 추가해요.
  • Claude Desktop 채팅 앱: Claude Code와는 별개 앱이에요. claude_desktop_config.json의 서버를 CLI로 복사하려면 macOS나 WSL에서 claude mcp add-from-claude-desktop를 실행해요.
  • VS Code: MCP로 외부 도구 연결을 참고하세요.
  • 웹의 Claude Code: 리포지토리의 .mcp.json을 읽어요.
  • Claude.ai: claude.ai/customize/connectors에서 추가한 커넥터는 그 계정으로 로그인하면 CLI에 자동으로 로드돼요.

문제 해결

서버가 연결되지 않으면 세션 안에서 /mcp, 셸에서 claude mcp list로 상태를 확인하고 아래 증상을 짝지어 보세요. /mcp 패널에서도 세션을 떠나지 않고 재연결하거나 인증할 수 있어요.

/mcp가 "No MCP servers configured"를 보여줌

Claude Code가 현재 디렉토리에서 찾은 서버가 없어요. 흔한 원인은:

  • 다른 프로젝트에서 claude mcp add를 실행했어요. local 스코프 서버는 추가한 프로젝트에 묶여요. 지금 있는 프로젝트에서 다시 추가하거나, --scope user로 추가해서 프로젝트에 묶이지 않게 해요.
  • 잘못된 경로의 설정 파일을 편집했어요. 올바른 파일은 ~/.claude.json과 <project>/.mcp.json이에요. Claude Code는 ~/.claude/.mcp.json, ~/.claude/config/mcp.json, ~/.claude/mcp.json, %APPDATA%\Claude\mcp.json 같은 경로는 읽지 않아요. user 스코프 서버는 claude mcp add --scope user(이것은 ~/.claude.json의 mcpServers 키에 기록), project 스코프 서버는 프로젝트 루트 .mcp.json을 편집해요.
  • .mcp.json에 잘못된 항목을 썼어요. Claude Code는 그 항목을 건너뛰고 나머지는 로드해요. 셸에서 claude mcp list를 실행해 범인 필드를 짚는 파싱 경고를 찾아보세요.

상태가 "Failed to connect" 또는 "Connection error"

두 상태 모두 서버가 시작되지 않았거나 URL이 응답하지 않았다는 뜻이에요. headers.Authorization에 설정한 토큰을 거부하는 HTTP 서버에서도 나타날 수 있어요.

먼저 보이는 상태에 따라 다르게 대응해요. Failed to connect면 상태 자체의 실패 상세로 시작해요. claude mcp list와 claude mcp get <name>이 HTTP 상태/에러 코드와 서버가 반환한 에러 텍스트를 보여주고, 대개 누락된 헤더나 거부된 토큰 같은 문제를 직접 짚어줘요. Connection error면 이 상태에는 상세가 붙지 않으니 아래의 curl·명령 확인으로 바로 가요.

HTTP 서버면 URL에 연결 가능한지 확인해요.

curl -I https://mcp.sentry.dev/mcp

PowerShell에서는 curl 대신 curl.exe를 써서 Invoke-WebRequest 별칭이 아니라 실제 curl 바이너리로 요청이 가게 해요. 응답이 문제 종류를 알려줘요. 404나 405면 서버는 떠 있는 것(MCP 엔드포인트는 POST만 답하는 경우가 많아서), 401/403이면 서버는 있고 인증이 필요하며, 응답이 전혀 없으면 URL과 네트워크를 확인하세요.

stdio 서버면 설정된 명령을 터미널에서 직접 실행해서 밑바닥 오류를 보세요.

npx -y @playwright/mcp@latest

명령이 시작되고 입력을 기다리면 서버 자체는 동작하는 것. claude mcp get <name>으로 표시된 명령이 방금 실행한 것과 같은지 확인해요. 다르다면 서버 명령 앞의 -- 구분자를 빼먹었을 가능성이 커요. 명령이 오류를 내면 그 메시지가 Node.js나 브라우저 같은 빠진 것을 짚어줘요.

시작 시 연결 타임아웃

서버가 기본 30초 시작 타임아웃보다 오래 걸렸어요. stdio 서버의 첫 실행은 npx가 패키지를 내려받느라 느릴 수 있어요. ms 단위의 MCP_TIMEOUT 환경변수로 늘려요.

MCP_TIMEOUT=60000 claude

PowerShell에서는 같은 줄에서 명령 앞에 변수를 설정해요.

$env:MCP_TIMEOUT = "60000"; claude

서버가 이미 존재함

같은 스코프에 같은 이름의 서버를 이미 추가했어요. 기존 항목을 먼저 제거하거나 다른 이름을 쓰세요.

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

이름이 여러 스코프에 존재하면 remove가 exists in multiple scopes라고 보고해요. --scope를 넘겨 삭제할 복사본을 정하세요.

서버는 연결되는데 도구가 안 보임

세션 안에서 /mcp를 실행하고 서버를 선택해 도구 목록을 보세요. 비어 있다면 서버가 시작은 됐지만 어떤 도구도 등록하지 않은 것으로, 보통 API 키 같은 필수 환경변수가 빠진 경우예요. claude mcp add의 --env KEY=value 또는 서버 .mcp.json 항목의 env 필드로 변수를 넘겨요.

.mcp.json 변경이 반영되지 않음

Claude Code는 세션 시작 시 .mcp.json을 읽어요. 파일을 편집한 뒤 세션을 종료하고 다시 시작하세요. 여전히 안 보이면 claude mcp list로 파싱 경고를 찾아보세요. 이전에 승인 프롬프트에서 거부했다면 claude mcp reset-project-choices로 프로젝트 승인을 초기화해요.

OAuth 로그인 실패 또는 브라우저 미열림

/mcp에서 서버를 선택하고 Authenticate를 다시 선택해요. 브라우저가 자동으로 안 열리면 터미널에 보이는 URL을 복사해 직접 열어요.

다음 단계

서버 하나를 연결했으니 MCP가 열어 주는 것들을 더 탐색해 보세요.

더 알아보기