Claude Code MCP 서버 설정: 외부 도구 연결하는 방법

Claude Code MCP 서버를 연결하면 이슈 관리, 문서, 소스 저장소, 모니터링과 데이터베이스 같은 외부 시스템을 대화 안에서 조회하거나 작업에 활용할 수 있습니다. 연결 자체보다 중요한 것은 어떤 서버를 신뢰할지, 어느 프로젝트에서 사용할지, 어떤 읽기·쓰기 권한을 줄지 결정하는 일입니다. 처음에는 테스트 프로젝트와 읽기 전용 계정으로 연결 상태와 도구 목록부터 확인하세요.

Claude Code MCP란 무엇인가

MCP(Model Context Protocol)는 AI 애플리케이션이 외부 도구와 데이터 소스에 연결하는 표준입니다. Claude Code에 MCP 서버를 추가하면 서버가 공개한 tools, resources와 prompts를 현재 개발 작업에서 사용할 수 있습니다. 예를 들어 이슈 내용을 읽어 구현 범위를 찾거나 오류 추적 시스템의 이벤트를 조사하고 내부 문서에서 API 규칙을 확인할 수 있습니다.

MCP는 단순한 검색 플러그인이 아닙니다. 서버가 쓰기 도구를 제공하고 사용자가 권한을 허용하면 외부 시스템의 이슈, 메시지와 데이터가 바뀔 수 있습니다. 연결 이름보다 서버 코드, 운영 주체, 인증 범위와 제공 도구를 먼저 확인해야 합니다.

MCP로 연결하기 좋은 외부 도구

• 이슈 관리: 요구사항과 버그 문맥을 읽고 상태 변경 초안을 만듭니다.
• 소스 저장소: PR, 이슈, 브랜치와 리뷰 정보를 조회합니다.
• 문서 시스템: 사내 개발 표준과 제품 요구사항을 검색합니다.
• 모니터링: 오류 이벤트와 배포 전후 지표를 조사합니다.
• 데이터베이스: 스키마와 제한된 분석 데이터를 읽습니다.
• 디자인·협업: 디자인 문맥과 팀 대화를 개발 작업에 연결합니다.

운영 데이터베이스에 바로 쓰기 권한을 주거나 메시지를 자동 발송하는 작업부터 시작하면 위험합니다. 첫 단계는 조회 전용 연결과 결과 검증이며, 쓰기 동작은 별도 계정·승인·감사 로그가 준비된 뒤 추가하세요.

HTTP·stdio·SSE 전송 방식 차이

새 원격 연결은 HTTP를 우선하고 로컬 파일·도구에 직접 접근해야 할 때 stdio를 선택하세요. 인터넷에서 본 npx -y 명령을 검토 없이 실행하면 설치 패키지와 공급망 위험까지 함께 허용하게 됩니다.

설치 전 확인할 체크리스트

1. 서버 URL이나 패키지가 공식 공급자 문서와 일치하는지 확인합니다.
2. 읽기·쓰기·삭제 중 어떤 도구를 제공하는지 목록을 봅니다.
3. 필요한 OAuth scope나 API 권한을 최소 범위로 정합니다.
4. 토큰 저장 위치, 만료, 폐기와 감사 로그 정책을 확인합니다.
5. local·project·user 중 설정 범위를 결정합니다.
6. 운영 데이터가 아닌 테스트 계정과 샘플 프로젝트를 준비합니다.
7. 서버 장애 시 Claude Code 작업이 어떻게 실패하는지 확인합니다.

원격 HTTP MCP 서버 추가하기

원격 MCP 서버의 기본 명령은 다음과 같습니다. 아래 URL은 형식 설명용이므로 실제 공급자가 안내하는 HTTPS 주소로 바꿔야 합니다.

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

추가한 뒤 목록과 세부 설정을 확인합니다.

claude mcp list
claude mcp get team-docs

인증이 필요한 서버는 Claude Code 안에서 /mcp를 열어 연결 상태와 로그인 항목을 확인하세요. 401 또는 403 응답을 받은 지원 서버는 OAuth 인증이 필요한 상태로 표시될 수 있습니다.

로컬 stdio MCP 서버 추가하기

stdio 서버는 Claude Code가 로컬 프로세스를 시작하고 표준 입출력으로 통신합니다. 모든 Claude 옵션은 서버 이름 앞에 두고, -- 뒤에는 실제 서버 명령과 인자를 적습니다.

claude mcp add --transport stdio local-tools -- node ./tools/mcp-server.js

실행 파일이 PATH에 없으면 절대 경로가 필요할 수 있습니다. 상대 경로, 현재 작업 디렉터리와 패키지 설치 위치가 팀원마다 다르면 연결 실패가 반복되므로 프로젝트 기준 경로와 준비 절차를 문서화하세요.

local·project·user 범위 선택하기

기본 범위는 local입니다. 팀에 공유할 서버는 다음처럼 project 범위를 명시합니다.

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

.mcp.json은 커밋할 수 있지만 토큰, 개인 경로와 운영 비밀값은 넣으면 안 됩니다. 프로젝트 범위 서버는 처음 사용할 때 신뢰 여부를 확인하는 승인 절차가 나타날 수 있습니다.

.mcp.json 직접 작성하는 방법

팀에서 동일한 원격 서버를 사용하면서 URL과 인증값을 환경에 따라 바꿔야 한다면 환경 변수 확장을 사용할 수 있습니다.

{
  "mcpServers": {
    "team-docs": {
      "type": "http",
      "url": "${TEAM_MCP_URL:-https://mcp.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${TEAM_MCP_TOKEN}"
      }
    }
  }
}

TEAM_MCP_TOKEN은 파일에 실제 값으로 넣지 말고 운영체제나 조직의 비밀 관리 도구에서 제공합니다. 기본값이 없는 필수 환경 변수가 설정되지 않으면 Claude Code가 설정을 파싱하지 못할 수 있습니다.

환경 변수와 API 키 안전하게 전달하기

CLI의 --env로 stdio 서버에 환경 변수를 전달할 수 있지만 터미널 기록과 프로세스 목록, 화면 공유에 값이 노출될 수 있습니다. 실제 키를 명령 예제에 직접 붙이는 방식보다 비밀 관리 도구에서 프로세스 환경으로 주입하는 편이 안전합니다.

• 개인 키와 조직 공용 키를 구분합니다.
• 읽기 전용·개발 환경용 자격 증명부터 사용합니다.
• 키에 만료 기간과 서비스별 최소 scope를 설정합니다.
• 로그, 오류 메시지와 Hook 출력에서 헤더를 제거합니다.
• 퇴사·역할 변경과 서버 제거 시 토큰도 함께 폐기합니다.

OAuth로 원격 서버 인증하기

1. 공급자가 안내한 HTTP MCP URL을 추가합니다.
2. Claude Code에서 /mcp를 실행합니다.
3. 인증이 필요한 서버를 선택합니다.
4. 브라우저에서 계정과 요청 권한을 확인합니다.
5. 로그인 후 연결 상태와 공개된 도구 수를 확인합니다.

OAuth 토큰은 자동 갱신될 수 있으며 /mcp의 인증 해제 기능으로 접근을 폐기할 수 있습니다. 브라우저 리디렉션이 실패하면 Claude Code가 안내하는 콜백 URL 절차를 따르세요. 고정 포트나 제한된 scope가 필요한 조직은 공급자 등록 정보와 oauth.scopes 설정을 함께 검토해야 합니다.

/mcp에서 연결 상태 확인하기

Claude Code 안에서 /mcp를 열면 서버별 연결 상태, 인증 여부와 제공 도구를 확인할 수 있습니다. 서버가 tools 기능을 광고하지만 실제 도구가 없으면 별도 경고가 나타날 수 있습니다.

MCP 도구를 실제로 호출하는 방법

연결 후에는 자연어로 서버와 목적을 명확히 지정할 수 있습니다.

team-docs MCP에서 결제 API의 오류 응답 규칙을 찾아줘.
문서 제목과 원문 위치를 근거로 요약하고 파일은 수정하지 마.

issue-tracker MCP에서 현재 브랜치와 관련된 열린 이슈를 읽어줘.
상태를 변경하거나 댓글을 작성하지 말고 요구사항만 정리해줘.

처음부터 “알아서 처리해줘”라고 요청하기보다 읽기 전용, 대상 서버, 허용 작업, 금지 동작과 반환 근거를 함께 적으면 예상하지 않은 외부 변경을 줄일 수 있습니다.

MCP 도구 권한 제한하기

Claude Code 권한 규칙에서 MCP 도구의 허용·질문·거부 범위를 관리할 수 있습니다. 서버 전체를 자동 허용하기보다 읽기 도구와 쓰기 도구를 나누고, 이슈 생성·댓글·배포·데이터 변경은 사용자 확인을 유지하세요.

• 검색·조회 도구부터 허용하고 쓰기 도구는 ask 또는 deny로 둡니다.
• 운영·개발 서버를 다른 이름과 자격 증명으로 분리합니다.
• Subagent에는 해당 역할에 필요한 MCP 서버와 도구만 제공합니다.
• Hooks가 MCP 결과를 외부로 다시 전송하지 않는지 확인합니다.
• 관리형 설정이 있는 조직은 개인 설정보다 조직 정책을 우선합니다.

MCP와 Hooks·Subagent 함께 사용하기

Claude Code Subagent에 문서 검색이나 이슈 조회용 MCP 도구만 제공하면 대량 조사 결과를 별도 문맥에서 처리할 수 있습니다. 하지만 Subagent가 읽은 외부 콘텐츠에도 프롬프트 인젝션이 포함될 수 있으므로 반환된 명령과 결론을 그대로 실행해서는 안 됩니다.

Claude Code Hooks는 도구 호출 전후의 검사나 감사 기록에 사용할 수 있습니다. 외부 시스템 쓰기를 자동 승인하는 Hook은 위험하므로 도구 이름, 입력값, 대상 환경과 사람 승인 규칙을 함께 적용하세요.

서버가 연결되지 않을 때 확인할 순서

같은 이름의 서버가 충돌할 때

동일한 이름이 여러 범위에 있으면 공식 문서 기준 local, project, user 순서의 우선순위가 적용됩니다. 팀의 .mcp.json을 수정했는데 변화가 없다면 개인 local 설정에 같은 이름이 있는지 확인하세요.

claude mcp list
claude mcp get team-docs

서버 이름을 용도와 환경이 드러나도록 docs-readonly, issues-dev처럼 구분하면 잘못된 연결을 줄일 수 있습니다. 공식적으로 예약된 이름은 피하고 조직 명명 규칙도 문서화하세요.

서버 제거와 인증 초기화

claude mcp remove team-docs

서버 설정을 지워도 공급자 측 OAuth 승인이나 발급한 API 키가 자동 폐기된다고 가정하면 안 됩니다. 공급자 보안 설정에서 연결 앱과 토큰을 함께 해제하세요. 프로젝트 범위 서버의 신뢰 선택을 초기화해야 한다면 claude mcp reset-project-choices를 사용할 수 있습니다.

대용량 MCP 출력 관리하기

MCP 도구가 긴 로그, 문서와 데이터 행을 한 번에 반환하면 주 대화의 문맥을 빠르게 소비합니다. 서버가 필터·페이지·limit 인자를 지원하면 필요한 범위를 먼저 줄이고, 요약 전 원문 근거 위치를 남기세요.

• 기간, 프로젝트, 상태와 필드를 요청 단계에서 제한합니다.
• 데이터베이스는 전체 행보다 집계와 샘플을 우선합니다.
• 긴 로그는 오류 전후 범위와 최초 실패를 요청합니다.
• 대량 조사는 Subagent에 맡기고 핵심 근거만 반환하게 합니다.
• 출력 한도를 무작정 높이기 전에 서버 쿼리를 개선합니다.

외부 MCP 서버 보안 체크리스트

• 공식 공급자 또는 내부에서 검토한 서버인가
• 서버 코드·패키지·도메인의 소유자가 확인되는가
• 요청하는 OAuth scope와 API 권한이 업무에 필요한 최소 범위인가
• 읽기와 쓰기 도구를 분리하고 고위험 작업에 승인을 유지했는가
• 전송 데이터, 로그와 보존 위치가 조직 정책에 맞는가
• 외부 콘텐츠의 프롬프트 인젝션을 전제로 결과를 재검토하는가
• 토큰 회전·폐기와 서버 제거 절차가 마련됐는가
• 운영 데이터 전 테스트 계정에서 실패 동작까지 검증했는가

Anthropic은 Directory 등록 서버를 자체 기준으로 검토하지만 모든 MCP 서버를 보안 감사하거나 운영하지는 않는다고 안내합니다. 목록에 있다는 사실만으로 신뢰하지 말고 공급자와 조직의 보안 검토를 별도로 진행해야 합니다.

팀 도입 순서

1. 복사·붙여넣기가 반복되는 읽기 중심 업무 하나를 고릅니다.
2. 개인 local 범위와 테스트 계정으로 서버를 연결합니다.
3. 예상 도구, 권한 질문, 실패와 로그 노출을 확인합니다.
4. 효과가 확인되면 비밀값을 제거한 project 설정으로 전환합니다.
5. .mcp.json과 관련 스크립트를 코드 리뷰합니다.
6. 팀원별 환경 변수·OAuth·폐기 절차를 문서화합니다.
7. 쓰기 도구는 별도 승인과 감사 체계를 갖춘 뒤 단계적으로 엽니다.

MCP 연결 검증 기록표

서버를 추가할 때마다 아래 정보를 남기면 “연결됨”과 “운영 가능한 상태”를 구분할 수 있습니다. 실제 토큰과 고객 데이터는 기록하지 마세요.

편집부 결론

Claude Code MCP 서버 설정은 외부 도구를 많이 연결하는 것이 목표가 아닙니다. 개발자가 반복해서 복사하던 신뢰 가능한 문맥을 필요한 범위로 가져오고, 읽기·쓰기 권한과 근거를 추적할 수 있게 만드는 것이 핵심입니다. 원격 서비스는 HTTP, 로컬 도구는 stdio를 우선 검토하고 local 범위의 읽기 전용 연결부터 시작하세요.

이 글은 2026년 9월 6일 Anthropic 공식 문서를 분석해 작성했으며 특정 MCP 공급자의 보안이나 가용성을 직접 보증하지 않습니다. 서버 명령, URL, 인증 scope와 제공 도구는 변경될 수 있으므로 설치 직전 공급자 공식 문서와 현재 Claude Code의 /mcp 상태를 확인하세요.

공식 문서와 함께 읽을 글

Claude Code MCP 연결 공식 문서 보기

Claude Code MCP 보안 원칙 확인하기

Claude Code 도구 권한 설정하기

MCP 도구 호출을 Hooks로 검사하고 자동화하기

MCP·Skills·Hooks를 Claude Code Plugin으로 배포하기

Claude Code Hooks로 외부 도구 호출 검사하기

Claude Code Subagent에 MCP 도구 제한하기

Codex MCP 서버 연결 방식과 비교하기

Codex와 Claude Code 개발 흐름 비교하기

자주 묻는 질문

Claude Code에 MCP 서버를 어떻게 추가하나요?

원격 서버는 claude mcp add --transport http 이름 URL, 로컬 프로세스는 claude mcp add --transport stdio 이름 -- 명령 인자 형식으로 추가할 수 있습니다.

MCP 서버 연결 상태는 어디에서 확인하나요?

터미널에서 claude mcp list와 claude mcp get 이름을 사용하고 Claude Code 안에서는 /mcp를 열어 상태, 도구와 인증을 확인합니다.

팀과 MCP 설정을 공유하려면 어떻게 하나요?

--scope project를 사용하면 프로젝트 루트의 .mcp.json으로 공유할 수 있습니다. 토큰과 개인 경로는 커밋하지 말고 환경 변수로 분리하세요.

local과 project 범위는 무엇이 다른가요?

local은 현재 프로젝트의 현재 사용자에게만 적용되고 ~/.claude.json에 저장됩니다. project는 팀과 공유할 설정으로 프로젝트 루트의 .mcp.json에 저장됩니다.

Claude Code MCP에서 OAuth 로그인을 할 수 있나요?

OAuth를 지원하는 HTTP 서버는 /mcp에서 브라우저 인증을 진행할 수 있습니다. 로그인 화면에서 요청 scope를 확인하고 필요하면 인증 해제로 접근을 폐기하세요.

stdio MCP 서버에서 spawn ENOENT가 나오는 이유는 무엇인가요?

설정한 실행 파일이 설치되지 않았거나 Claude Code의 PATH에서 찾을 수 없는 경우가 많습니다. 터미널에서 실행 파일 위치를 확인하고 필요한 경우 검증된 절대 경로를 사용하세요.

MCP 서버를 연결하면 모든 도구가 자동으로 안전한가요?

아닙니다. 서버가 제공하는 쓰기·삭제 도구, 외부 콘텐츠와 패키지 자체를 검토해야 합니다. 최소 권한, 테스트 계정, 사용자 승인과 감사 기록을 함께 적용하세요.

SSE MCP 서버를 새로 사용해도 되나요?

Claude Code 공식 문서는 SSE 전송을 deprecated로 안내합니다. 공급자가 지원한다면 새 연결은 HTTP 전송을 우선 선택하는 편이 좋습니다.