가이드

Claude Code MCP 설정: MCP 서버 추가, 공유, 문제 해결

게시일 2026년 10월 30일 · 최종 확인 2026년 10월 30일

MCP(Model Context Protocol)는 AI 도구를 연결하기 위한 개방형 표준입니다. MCP 서버를 연결하면 Claude Code가 내 도구, 데이터베이스, API에 직접 접근하므로 데이터를 채팅창에 복사해 붙여 넣을 필요가 없어집니다. 이 글은 단계별 안내입니다. 세 가지 transport가 각각 어떤 명령을 쓰는지, 설정이 어디에 저장되는지, 팀과 어떻게 공유하는지, 인증은 어떻게 하는지, 실패하면 무엇을 확인하는지를 다룹니다. Anthropic의 Connect Claude Code to tools via MCP를 따랐으며, 2026년 10월 30일에 해당 페이지와 대조해 확인했습니다.

MCP란 무엇이고 언제 서버를 연결하는가

MCP 서버는 Claude Code가 내 도구, 데이터베이스, API에 접근하게 해 줍니다. 이슈 트래커나 모니터링 대시보드 같은 다른 도구에서 데이터를 채팅창에 복사해 붙여 넣고 있다면 서버를 연결할 때입니다. 연결하고 나면 Claude는 붙여 넣은 내용에 의존하지 않고 해당 시스템을 직접 읽고 조작할 수 있습니다.

보안: 서버를 연결하기 전에 각 서버를 신뢰할 수 있는지 확인하세요. 외부 콘텐츠를 가져오는 서버는 프롬프트 인젝션 위험에 노출될 수 있습니다.

transport별 서버 추가 방법

모든 방법은 claude mcp add를 씁니다. 서버가 제공하는 정보에서 출발하세요. https:// 주소는 원격 서버이고, npx 같은 실행 명령은 내 컴퓨터에서 실행되는 서버입니다.

원격 HTTP 서버

# Basic syntax
claude mcp add --transport http <name> <url>

# Real example: Connect to Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

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

JSON 설정에서 type 필드는 http의 별칭으로 streamable-http도 받습니다. url은 있고 type이 없는 JSON 항목은 설정 오류입니다. Claude Code는 type이 없는 항목을 stdio 서버로 읽고 건너뜁니다.

원격 SSE 서버

SSE(Server-Sent Events) transport는 deprecated이므로 가능하면 HTTP를 쓰세요. 일부 서비스는 아직 SSE 엔드포인트만 제공합니다. 그런 서비스도 같은 claude mcp add --transport http <name> <url> 명령으로 추가할 수 있습니다. Claude Code가 먼저 HTTP를 시도하고, 서버가 받아들이지 않으면 SSE로 전환합니다. 이 자동 전환에는 Claude Code v2.1.265 이상이 필요합니다. 이전 버전이거나 SSE로 직접 연결하려면 --transport sse를 지정하세요.

# Basic syntax
claude mcp add --transport sse <name> <url>

# Real example: Connect to Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Example with authentication header
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

로컬 stdio 서버

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

# Basic syntax
claude mcp add [options] <name> -- <command> [args...]

# Real example: Add Airtable server
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

• --(대시 두 개)는 --transport, --env, --scope 같은 Claude 자체 옵션과 서버를 실행하는 명령 및 인자를 구분합니다. -- 뒤의 모든 내용은 그대로 서버에 전달됩니다. 이것이 없으면 Claude Code가 --port 같은 서버의 플래그를 자신의 옵션으로 해석하려 합니다.
• claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080은 환경 변수에 KEY=value를 넣고 python server.py --port 8080을 실행합니다.
• --env는 KEY=value 쌍을 여러 개 받습니다. 서버 이름이 --env 바로 뒤에 오면 CLI는 그 이름을 또 하나의 쌍으로 읽고 거부하므로, --env와 서버 이름 사이에 --transport stdio 같은 다른 옵션을 하나 이상 두세요.

다른 클라이언트용으로 작성된 안내 변환하기

서버의 설치 안내가 Claude Desktop, Cursor 등 다른 MCP 클라이언트용으로 작성되어 claude mcp add 명령이 없을 수 있습니다. 그 안에서 URL, 실행 명령, JSON 블록을 찾아보세요.

• URL(예: https://mcp.example.com/mcp): 원격 서버입니다. claude mcp add --transport http example https://mcp.example.com/mcp를 쓰세요.
• 실행 명령(예: npx -y @example/mcp-server): 내 컴퓨터에서 실행되는 서버입니다. 명령 전체를 -- 뒤에 넣으세요. claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server.
• mcpServers JSON 블록: 바깥 래퍼가 아니라 mcpServers 안쪽 객체를 claude mcp add-json에 넘기세요.

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

add-json에서 type이 없는 url 항목에는 먼저 "type": "http", "type": "sse", "type": "ws" 중 하나를 추가해야 합니다. claude mcp add --transport는 ws를 받지 않으므로 WebSocket 서버는 .mcp.json이나 claude mcp add-json으로 설정합니다. 서버 이름에는 문자, 숫자, 하이픈, 밑줄만 쓸 수 있습니다.

범위(scope): 설정이 저장되는 위치

MCP 서버는 세 가지 범위로 설정할 수 있습니다. 범위는 서버가 어느 프로젝트에서 로드되는지, 설정을 팀과 공유하는지를 결정합니다. -s 또는 --scope로 고르며 기본값은 local입니다.

# Local scope
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

# Project scope
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# User scope
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

local 범위 서버는 ~/.claude.json 안에서 해당 프로젝트 경로 아래에 저장되므로 다른 프로젝트에는 나타나지 않습니다. 개인 개발용 서버, 실험적 설정, 버전 관리에 올리고 싶지 않은 자격 증명이 있는 서버에 쓰세요. MCP 서버의 "local 범위"는 일반 로컬 설정 파일인 .claude/settings.local.json과는 다르다는 점에 유의하세요.

같은 서버가 여러 곳에 정의되어 있으면 Claude Code는 우선순위가 가장 높은 출처의 정의를 사용해 한 번만 연결합니다. 항목 전체가 사용되며, 범위 간에 필드를 병합하지 않습니다. 우선순위는 높은 쪽부터 local 범위, project 범위, user 범위, 플러그인이 제공하는 서버, claude.ai 커넥터 순입니다.

.mcp.json으로 팀과 서버 공유하기

project 범위는 설정을 프로젝트 루트의 .mcp.json 파일에 저장합니다. project 범위 서버를 추가하면 Claude Code가 이 파일을 만들거나 갱신해 줍니다. 버전 관리에 넣으면 팀원 모두가 같은 MCP 도구를 쓸 수 있습니다.

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

보안상의 이유로, Claude Code는 대화형 세션에서 .mcp.json 파일의 project 범위 서버를 사용하기 전에 승인을 요청합니다. 승인 선택을 초기화하려면 claude mcp reset-project-choices를 실행하세요.

.mcp.json의 환경 변수

.mcp.json은 환경 변수 확장을 지원하므로, 팀은 하나의 설정을 공유하고 컴퓨터별 경로나 API 키 같은 민감한 값은 각자의 환경에 둘 수 있습니다. 서버의 command, args, env, url, headers 값에서 변수를 참조할 수 있습니다.

• ${VAR}: 환경 변수 VAR의 값으로 확장됩니다.
• ${VAR:-default}: VAR가 설정되어 있으면 그 값으로, 설정되지 않았으면 default로 확장됩니다.

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

참조한 변수가 설정되어 있지 않고 기본값도 없어도 설정은 로드됩니다. Claude Code는 claude mcp list에 변수 누락 경고를 표시하고 확장되지 않은 ${VAR} 텍스트를 그대로 사용합니다. 원격 서버의 url과 headers에서 ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN 같은 자격 증명 변수는 확장되지 않고 빈 값으로 읽힙니다. 서버에 그런 자격 증명을 주려면 직접 지은 이름의 변수에 복사해 그 이름을 참조하세요.

서버 목록 보기, 확인, 삭제

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get notion

# Remove a server
claude mcp remove notion

# (within Claude Code) Check server status
/mcp

성공하면 claude mcp add는 Added ... 줄을 출력하며, 이는 설정이 기록되었다는 뜻입니다. 자격 증명은 검증하지 않으므로 임시 토큰도 받아들여지고 서버는 나중에 연결에 실패합니다. Claude Code가 실제로 연결했는지 확인하려면 claude mcp get <name>을 실행하거나, Claude Code에서 /mcp를 실행해 서버 행에 체크 표시가 있는지 보세요.

claude mcp list는 각 서버 옆에 상태를 표시합니다.

원격 서버를 삭제하면 Claude Code는 그 서버용으로 저장한 OAuth 토큰과 클라이언트 등록도 함께 지우지만, 인증 서버에서 토큰을 폐기하지는 않습니다. 인증 서버가 폐기를 지원한다면 claude mcp remove <name> 전에 셸에서 claude mcp logout <name>을 실행하세요.

설정을 잃지 않고 서버 사용만 멈추려면 /mcp 패널에서 끄세요. Claude Code는 연결을 멈추고 설정은 그대로 둡니다.

원격 서버 인증

많은 클라우드 기반 MCP 서버가 인증을 요구하며, Claude Code는 OAuth 2.0을 지원합니다. 원격 서버가 401 Unauthorized 또는 403 Forbidden으로 응답하면 인증이 필요한 서버로 표시합니다.

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

그런 다음 Claude Code 안에서 /mcp를 실행하고 브라우저의 안내에 따라 로그인하세요.

• 인증 토큰은 안전하게 저장되고 자동으로 갱신됩니다.
• 접근 권한을 폐기하려면 /mcp 메뉴의 "Clear authentication"을 사용하세요.
• 브라우저가 자동으로 열리지 않으면 표시된 URL을 복사해 직접 여세요.
• 인증 후 브라우저 리디렉션이 연결 오류로 실패하면, 브라우저 주소 표시줄의 전체 콜백 URL을 Claude Code에 나타난 URL 프롬프트에 붙여 넣으세요.
• OAuth 인증은 HTTP 서버에서 동작합니다.

세션을 열지 않고 로그인하려면 셸에서 이 절차를 실행하세요.

claude mcp login sentry

저장된 자격 증명을 나중에 지우려면 claude mcp logout <name>을 실행하세요. SSH 세션이나 디스플레이 서버가 없는 Linux에서는 claude mcp login이 로컬 브라우저가 없음을 감지하고 브라우저를 여는 대신 인증 URL을 출력합니다. 그 URL을 내 로컬 컴퓨터에서 열고, 브라우저 주소 표시줄의 전체 리디렉션 URL을 프롬프트에 다시 붙여 넣으세요. 이 단계에는 대화형 터미널이 필요하므로 ssh -t로 접속하세요. 로컬 브라우저가 감지되더라도 URL 프롬프트를 강제로 쓰려면 --no-browser를 지정하세요.

서버에 headers.Authorization을 설정했는데 서버가 이를 거부하면, Claude Code는 OAuth로 대체하지 않고 연결 실패로 보고합니다. 토큰이 해당 MCP 엔드포인트에서 유효한지 확인하거나, 헤더를 지워 OAuth 흐름을 쓰세요. claude -p나 Agent SDK 실행에는 /mcp 패널이 없으므로, 먼저 대화형 세션에서 로그인하거나 claude mcp login <name>으로 로그인하세요.

타임아웃과 출력 제한

• 시작 타임아웃은 MCP_TIMEOUT 환경 변수로 지정합니다. 예를 들어 MCP_TIMEOUT=10000 claude는 10초로 설정합니다.
• 한 서버의 도구 호출 시간을 제한하려면 해당 서버의 .mcp.json 항목에 밀리초 단위의 timeout 필드를 추가하세요. 예를 들어 10분이면 "timeout": 600000입니다. 이 값은 그 서버에 한해 MCP_TOOL_TIMEOUT 환경 변수보다 우선합니다.
• Claude Code는 MCP 도구 출력이 10,000 토큰을 넘으면 경고를 표시하고, 기본적으로 출력을 25,000 토큰으로 제한합니다. 제한을 올리려면 Claude Code를 시작하기 전에 셸에서 MAX_MCP_OUTPUT_TOKENS를 설정하세요.

export MAX_MCP_OUTPUT_TOKENS=50000
claude

경고 임계값은 고정입니다. 서버가 도구 자체의 한도를 올리지 않는 한, 50,000자를 넘는 성공한 텍스트 결과는 이 변수와 관계없이 파일로 저장됩니다.

문제 해결

FAQ

출처

• Claude Code: Connect Claude Code to tools via MCP (claude mcp add, 범위, .mcp.json, 인증, 출력 제한. 2026년 10월 30일 확인)