Claude Code에 MCP Server를 연결하면 무엇이 달라질까요?
프로젝트 파일만 다루던 코딩 에이전트가 이슈 추적기, 문서, 디자인, 데이터베이스 같은 외부 시스템의 도구와 컨텍스트를 사용할 수 있게 됩니다. 이번 글에서는 로컬 stdio 서버와 원격 HTTP 서버를 각각 등록하고, 범위·인증·연결 상태를 확인한 뒤 실제 요청으로 검증하는 과정을 따라갑니다.
명령어는 2026년 9월 공식 Claude Code 문서를 기준으로 정리했습니다. 제품 업데이트에 따라 옵션이 달라질 수 있으므로 설치 전 해당 MCP Server의 공식 설정 안내도 함께 확인하세요.
1. Claude Code와 MCP 연결 구조부터 보기
Claude Code는 MCP Host 역할을 합니다. 등록한 서버마다 MCP Client 연결을 만들고, Server가 공개한 Tool과 Resource를 현재 대화에서 사용할 수 있게 합니다. 로컬 서버는 내 컴퓨터의 프로세스로 실행되고, 원격 서버는 네트워크의 HTTP 엔드포인트에 연결됩니다.
서버가 별도 API 토큰, 데이터베이스 계정 또는 클라우드 권한을 사용하면 그 범위까지 접근할 수 있습니다. 연결 전 서버의 출처, 코드 또는 운영 주체, 요청 권한과 전송 데이터를 확인하세요.
2. 시작 전 설치와 실행 환경 확인하기
먼저 Claude Code가 실행되는지 확인합니다. 이미 설치했다면 버전과 상태를 점검하고, 새 옵션이 필요하거나 동작이 문서와 다를 때는 업데이트 후 다시 확인합니다.
claude 명령이 실행되는가?Claude Code가 정상이어도 MCP Server의 실행 환경이 없으면 연결은 실패합니다. 예를 들어 npx 기반 서버라면 Node.js와 npm이 필요하고, Python 기반 서버라면 서버가 지정한 Python 버전과 패키지 관리 도구가 필요할 수 있습니다.
3. 로컬 stdio MCP Server 추가하기
로컬 stdio 서버는 내 컴퓨터에서 명령어로 실행됩니다. 파일 시스템, 로컬 개발 도구 또는 사내 스크립트처럼 컴퓨터에 직접 접근해야 하는 기능에 적합합니다. 기본 문법은 다음과 같습니다.
예를 들어 서버 제작자가 npx -y @example/mcp-server라는 실행 명령을 안내했다면 다음처럼 등록합니다. 아래 패키지명은 문법을 보여 주기 위한 예시이므로 실제 설치에는 서버 공식 문서의 명령을 사용하세요.
--를 꼭 확인하세요.앞쪽의
--transport, --scope, --env는 Claude Code 옵션이고, -- 뒤의 내용은 MCP Server를 실행할 명령과 인수입니다. 구분자를 빼면 서버 옵션을 Claude Code 옵션으로 잘못 해석할 수 있습니다.환경 변수가 필요한 서버는 서버 이름 뒤, 실행 명령 앞에 추가합니다.
위 명령의
YOUR_KEY는 자리 표시자입니다. 팀이 공유하는 .mcp.json에는 비밀값을 직접 기록하지 말고, 환경 변수 참조 또는 조직의 비밀 관리 방식을 사용하세요. 가능하면 읽기 전용·최소 권한 키를 발급합니다.4. 원격 HTTP MCP Server 추가하기
클라우드 서비스가 MCP 엔드포인트를 제공한다면 원격 HTTP 방식으로 연결할 수 있습니다. 공식 문서는 원격 MCP Server에 HTTP 전송을 우선 권장하며, 기본 형식은 간단합니다.
공식 문서에 소개된 Notion 원격 서버 예시는 다음과 같습니다.
등록 후 인증이 필요하다고 표시되면 Claude Code 세션에서 /mcp를 실행해 서버를 선택하고 브라우저 로그인을 진행합니다. 최신 버전에서는 셸에서 claude mcp login <서버이름>으로 OAuth 로그인을 시작할 수도 있습니다.
/mcp 또는 claude mcp login으로 OAuth 흐름을 시작합니다.5. local·project·user 범위 선택하기
MCP Server를 어디에서 사용할지 결정하는 옵션이 scope입니다. 기본값인 local과 팀 공유용 project, 여러 프로젝트에서 재사용하는 user를 구분해야 “내 컴퓨터에서는 되는데 동료에게는 보이지 않는” 문제를 줄일 수 있습니다.
| 범위 | 명령 옵션 | 적합한 상황 | 주의점 |
|---|---|---|---|
| local | 기본값 또는 --scope local |
현재 프로젝트에서 나만 쓰는 서버 | 개인별 프로젝트 설정이며 팀에 공유되지 않습니다. |
| project | --scope project |
팀이 같은 연결 정의를 공유 | 루트의 .mcp.json을 버전 관리할 수 있지만 비밀값은 넣지 않습니다. |
| user | --scope user |
내 여러 프로젝트에서 공통 사용 | 개인 사용자 설정에 저장되며 동료에게 전달되지 않습니다. |
같은 이름의 서버가 여러 범위에 있으면 Claude Code는 하나만 사용합니다. 공식 문서의 일반 설정 기준 우선순위는 local → project → user입니다. 조직 관리 설정은 이보다 높은 우선순위를 가질 수 있으므로 회사 환경에서는 관리자 정책도 확인하세요.
6. 연결 상태와 인증 확인하기
등록 명령이 성공했다는 메시지는 “설정이 저장되었다”는 뜻입니다. 실제 서버가 시작되고 인증까지 완료됐는지는 별도로 확인해야 합니다.
project 범위의 .mcp.json은 저장소에 포함될 수 있으므로 Claude Code가 신뢰와 승인을 요청할 수 있습니다. 낯선 저장소를 열었을 때 자동으로 외부 명령이 실행되지 않도록 하는 안전장치입니다. 서버 이름과 실행 명령, URL을 검토한 뒤 필요한 항목만 승인하세요.
7. 실제 요청으로 Tool 호출 검증하기
상태가 Connected라고 표시되어도 끝이 아닙니다. 읽기 작업부터 작은 테스트를 실행해 Claude Code가 올바른 Tool을 선택하고, 서버가 기대한 범위의 결과만 반환하는지 확인합니다.
문서 검색 서버를 연결했다면 다음처럼 범위를 좁힌 요청이 좋습니다.
8. 자주 발생하는 오류 해결하기
| 증상 | 가능한 원인 | 확인 순서 |
|---|---|---|
| Failed to connect | 실행 명령·URL 오류, 런타임 누락, 네트워크 차단 | claude mcp get 이름의 Issue를 확인하고 서버 명령을 터미널에서 별도 실행해 봅니다. |
| Needs authentication | OAuth 로그인 미완료 또는 권한 취소 | /mcp 또는 claude mcp login 이름으로 다시 로그인합니다. |
| Pending approval | project 범위 서버가 아직 승인되지 않음 | 해당 프로젝트에서 claude를 실행하고 서버 정의를 검토해 승인합니다. |
| 로컬 서버가 바로 종료 | -- 누락, 패키지·바이너리 없음, 필수 환경 변수 누락 |
등록 명령의 구분자와 실행 인수, 런타임 버전, 환경 변수를 확인합니다. |
| 도구 출력이 잘림 | 결과가 출력 제한을 초과 | 질의 범위를 줄이고 페이지네이션을 사용합니다. 필요한 경우에만 출력 제한 설정을 검토합니다. |
| 팀원에게 서버가 안 보임 | local 또는 user 범위로 등록 | 공유가 필요하면 project 범위와 .mcp.json을 사용하고 비밀값은 분리합니다. |
공식 문서는 서버 시작 제한을
MCP_TIMEOUT 환경 변수로 조정할 수 있다고 안내합니다. 다만 무작정 시간을 늘리기 전에 패키지 설치, 네트워크 프록시, 필수 환경 변수와 서버 자체 로그를 먼저 확인하세요.터미널 로그나 이슈 보고서에는 API 키, Authorization 헤더, 데이터베이스 연결 문자열이 포함되지 않도록 가립니다. 노출이 의심되면 해당 비밀값을 즉시 폐기하고 새로 발급하세요.
9. 핵심 정리
환경 확인 서버 등록 범위 선택 인증·상태 확인 읽기부터 검증
로컬 서버는
stdio와 실행 명령으로, 원격 서버는 http와 URL로 등록합니다. 개인 프로젝트용 local, 팀 공유용 project, 여러 프로젝트에서 쓰는 user 범위를 목적에 맞게 선택하고, claude mcp list, claude mcp get, /mcp로 실제 연결과 인증 상태를 확인합니다.연결이 성공했더라도 권한과 결과 검증은 사용자의 책임입니다. 처음에는 읽기 전용·최소 범위로 시험하고, 삭제·발송·수정처럼 되돌리기 어려운 작업은 실행 전 대상을 다시 확인하세요.
다음 글에서는 Cursor에 MCP Server를 등록하고 프로젝트 설정과 사용자 설정을 나누는 방법을 살펴봅니다.
🔗 MCP 완전정복 시리즈
참고: Claude Code 공식 MCP 문서, Claude Code 공식 설치·설정 문서, MCP 공식 Architecture overview
확인일: 2026-09-19 · CLI 옵션과 인증 방식은 변경될 수 있으므로 실제 연결 전 Claude Code 및 MCP Server의 최신 공식 문서를 확인하세요.