MCP 서버 사용법: Claude Code 연결 가이드

mcp 서버 사용법 한 줄 요약

claude mcp add로 서버를 붙이고 /mcp에서 상태를 본 뒤, 실제 도구 호출 한 번까지 해보세요. 로컬 프로세스를 바로 띄우는 stdio는 개인 도구에 잘 맞고, 원격 URL로 붙는 HTTP 방식은 팀 공유나 SaaS 연동에 편해요. 처음부터 서버를 많이 켜지 말고 하나씩 붙여야 컨텍스트 낭비도 덜해요.

처음 MCP 서버 붙이려고 공식 문서 열었는데, local이랑 project가 뭐가 다른지부터 막혔어요. claude mcp add 한 줄이면 끝날 줄 알았는데, 실제로는 전송 방식 고르는 데서 한 번, /mcp에 failed가 떠서 또 한 번 멈추더라고요. mcp 서버 사용법이 어려운 이유는 명령이 길어서가 아니에요. 처음 보는 단어가 한꺼번에 몰려와서 순서가 꼬이기 쉬운 거죠. 직접 삽질해보니 mcp 서버 사용법의 핵심은 딱 세 가지 — 전송 방식, scope, 컨텍스트 관리 — 만 잡으면 나머지는 따라와요.

이 글은 mcp 서버 사용법을 Claude Code 기준으로, 가장 많이 막히는 순서대로 짰어요. 어디서 MCP를 쓰는지, 첫 서버를 어떻게 붙이는지, stdio와 HTTP 가운데 뭘 먼저 골라야 하는지, .mcp.json을 팀에 어떻게 나눌지까지 한 흐름으로 묶었어요. 중간중간 실제 명령 예제, 체크리스트, 스크린샷 자리도 같이 넣어뒀거든요. 기본 설치가 아직이면 Claude Code 사용법: 설치부터 첫 실행까지 5분 가이드부터 보고 오는 게 덜 헷갈릴 거예요. 서버 몇 개 붙인 뒤 컨텍스트가 빨리 부푸는 문제, 윈도우에서 npx가 바로 안 도는 문제, failed 표시가 거슬리는 문제까지 같이 잡아보죠.

Claude Code에서 MCP를 어디서 쓰나

Claude Code는 터미널 하나만 보는 도구가 아니에요. 2026년 4월 14일 기준으로 터미널, VS Code 계열 편집기, 데스크톱 앱, 웹, JetBrains IDE까지 같은 엔진으로 이어져요.
터미널만 알면 끝일까요?

사용 환경	어디서 여나	MCP를 붙일 때 메모	추천 상황
터미널 CLI, 명령줄 환경	claude	claude mcp add, .mcp.json 중심	처음 세팅할 때
VS Code / Cursor 확장	명령 팔레트	같은 Claude Code 엔진을 써서 설정과 MCP가 이어져요	에디터 안에서 바로 쓰고 싶을 때
데스크톱 앱	Claude 앱의 Code 탭	시각적 diff 확인이 편해요	터미널이 답답할 때
Web / iOS	claude.ai/code	로컬 없는 리포를 볼 때 좋아요	외부에서 이어서 볼 때
JetBrains IDE, IntelliJ·PyCharm 계열	플러그인	선택 컨텍스트 공유가 편해요	JetBrains가 주 작업 환경일 때

헷갈리기 쉬운 포인트가 하나 있어요. 2026년 4월 14일 기준으로 Free 요금제 표에는 웹앱용 remote MCP와 connector 항목이 보이는데, Claude Code 자체는 Pro부터 들어가요. 이 글은 Claude Code 기준이라서 Pro 이상 흐름으로 보면 돼요. 공식 기준은 Claude Code 개요 문서와 Claude 요금제에서 다시 볼 수 있어요.

기본 세팅 흐름이 아직 낯설면 Claude Code 시작하기를 먼저 훑고 오는 편이 덜 꼬여요.

Claude Code에 MCP 서버 연결하기

처음 하나 붙일 때는 추가, 상태 확인, 실제 호출 이 세 단계만 끝내면 돼요. 추가만 해두고 도구 호출을 안 해보면 인증이나 권한 문제가 뒤늦게 터지거든요. 실제로 처음 붙일 때 Connected 떠서 안심했다가 도구 호출에서 403 맞은 적 있어요.
추가만 해두고 안 써보면 진짜 연결된 건지 어떻게 알까요?

아래 순서대로 가면 돼요.

1단계: GitHub MCP 서버 추가

# GitHub 토큰 준비
export GITHUB_TOKEN="your-token"

# GitHub MCP 서버 추가
claude mcp add --transport stdio --env GITHUB_TOKEN=$GITHUB_TOKEN github -- npx -y @modelcontextprotocol/server-github

결과: 설정 파일에 github 서버가 추가돼요.

2단계: Claude Code 안에서 상태 보기

/mcp

결과: 서버 목록에 github가 보이고 상태가 Connected로 떠야 해요.

3단계: 실제 도구 호출로 확인

이 저장소의 열린 이슈를 5개만 번호와 제목으로 정리해줘

결과:
– 도구 호출 로그가 한 번 이상 찍혀요
– 응답에 이슈 목록이 구조적으로 나와요
– 권한이 없으면 인증이나 접근 오류가 바로 보여요

참고로 HTTP 방식부터 가고 싶으면 원격 주소를 붙이면 돼요.

# 원격 HTTP 서버 예시
claude mcp add --transport http team-docs https://mcp.example.com/mcp

도구가 붙은 뒤 질문을 어떻게 던질지 막히면 AI 프롬프트 엔지니어링: 블로거가 바로 쓸 수 있는 7가지 실전 기법에서 질문 구조만 먼저 훑어보세요.

stdio와 HTTP 중 뭘 고르면 되나

mcp 서버 사용법에서 첫 갈림길이 전송 방식이에요. stdio는 로컬 프로세스를 바로 띄우는 방식이고, HTTP는 원격 URL로 붙는 방식이에요. 실제로 써보니 뭘 먼저 고를지만 정하면 설치 난도 절반은 정리되더라고요.
굳이 어려운 쪽을 먼저 고를 필요 있을까요?

항목	stdio	HTTP
서버가 도는 위치	내 컴퓨터	원격 주소
시작 난도	낮은 편	인증과 URL 구조를 봐야 해요
잘 맞는 경우	개인 도구, 로컬 스크립트, 실험	팀 공유, SaaS 연동, 중앙 관리
인증 흐름	환경 변수 중심	브라우저 로그인, 헤더, OAuth 2.0 같은 방식
장점	빠르고 단순해요	팀이 같은 엔드포인트를 같이 쓸 수 있어요
주의점	경로, PATH, OS 차이	인증 실패가 조용히 날 수 있어요

새로 잡는다면 원격 쪽은 Streamable HTTP 쪽으로 가는 게 안전해요. 예전 HTTP+SSE 조합을 최신 스펙에서 Streamable HTTP로 바꿨거든요. 여기서 SSE는 서버가 이벤트를 한 방향으로 밀어주는 예전 방식이라고 보면 돼요. 전송 방식 차이는 Claude Code MCP 공식 문서랑 MCP 전송 스펙만 봐도 충분해요.

에디터 안에서 MCP 흐름을 얼마나 자주 볼지 고민 중이면 Claude Code vs Cursor: 가격과 워크플로우 비교도 같이 보면 선택이 쉬워져요.

mcp 서버 설정 방법: local project user

mcp 서버 사용법에서 두 번째로 막히는 지점이 scope예요. mcp 서버 설정 방법이 헷갈리는 이유는 local, project, user가 다 비슷해 보여서거든요. 기준은 하나예요. 나만 잠깐 쓸 건지, 팀이 같이 쓸 건지, 여러 프로젝트에서 계속 쓸 건지.
같은 서버인데 왜 굳이 저장 범위를 나눌까요?

먼저 이 표부터 보세요.

범위	저장 위치	언제 쓰나	메모
local	~/.claude.json 안의 현재 프로젝트 경로 아래	지금 프로젝트에서 나만 쓸 때	기본값이에요
project	프로젝트 루트의 .mcp.json	팀과 공유할 때	승인 절차가 한 번 떠요
user	~/.claude.json	여러 프로젝트에서 계속 쓸 때	개인 공용 도구용

우선순위도 기억해두면 좋아요. 같은 이름이면 local이 먼저, 그다음 project, 마지막이 user예요. 팀에서 같은 이름으로 덮어쓸 때 여기서 많이 꼬이더라고요. 저도 처음에 project로 공유한 서버를 local에서 같은 이름으로 덮어써서 30분 삽질한 적 있어요.

프로젝트 공유 예시는 보통 이런 모양이에요.

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "team-docs": {
      "type": "http",
      "url": "${TEAM_MCP_URL:-https://mcp.example.com}/mcp"
    }
  }
}

체크 포인트는 간단해요.

• 나만 쓰는 토큰이면 local
• 팀 공용 엔드포인트면 project
• 어디서나 꺼내 쓰는 개인 도구면 user
• 민감한 값은 파일에 박지 말고 환경 변수로 빼기
• 팀 저장소에는 .mcp.json만 올리고 키는 각자 넣기

터미널에서 파일 기반 설정을 다루는 흐름이 아직 낯설다면 Codex CLI 사용법: 설치부터 첫 코드 생성까지도 같이 보면 손이 빨리 익어요.

컨텍스트 안 터지게 관리하는 법

서버를 많이 붙인다고 바로 좋아지진 않아요. 처음에 서버 8개 한꺼번에 켜봤는데, 세션 시작만 느려지고 실제로 쓰는 건 2-3개뿐이었어요. 도구 설명이 길면 세션 시작 전에 맥락이 불어나고, 큰 출력이 한 번 나오면 대화가 금방 답답해지거든요.
도구를 열 개 켜두는 게 진짜 이득일까요?

여기서는 Tool Search, 도구 정의를 필요할 때만 불러오는 기능이 핵심이에요. 2026년 4월 기준 공식 문서에서는 기본 활성화 상태라고 안내해요. 괜히 먼저 끄지 마세요.

먼저 해볼 건 이 다섯 가지예요.

• 세션 안에서 /context로 지금 어디서 토큰을 먹는지 보기
• Tool Search를 끄지 않기
• 자주 안 쓰는 서버는 빼고 5~6개 안쪽으로 운영하기
• 결과가 큰 도구는 페이지 단위나 필터 옵션부터 주기
• 출력 상한은 마지막에만 올리기

# 임계값을 더 빡빡하게 잡고 싶을 때
ENABLE_TOOL_SEARCH=auto:5 claude

# 큰 출력이 꼭 필요할 때만 상한 올리기
export MAX_MCP_OUTPUT_TOKENS=50000
claude

큰 출력이 반복되면 원인을 두 갈래로 보면 빨라요. 도구 정의가 많은 건지, 도구 결과가 큰 건지. 전자는 Tool Search 쪽이고, 후자는 응답 필터링이나 출력 상한 쪽이에요.

도구를 많이 붙이는 방식보다 터미널 명령과 섞어 쓰는 편이 나을 때도 있어요. 그 기준은 Claude Code vs Codex: 직접 비교하고 정리한 선택 기준에서 같이 보면 선택이 쉬워져요.

연결 안 될 때 보는 체크리스트

mcp 서버 사용법을 따라 하다 보면 연결 에러를 한 번은 만나요. 대부분 경로, 인증, 재시작, 출력 이 네 군데에서 걸려요. 에러 한 줄만 보고 패키지를 갈아엎지 말고 순서를 고정해서 보는 편이 훨씬 빨라요.
failed 한 줄 떴다고 바로 지워버릴 건 아니죠?

증상	먼저 볼 것	바로 해볼 조치
spawn ENOENT	실행 파일 경로, PATH	실행 파일 절대 경로로 바꾸기
Windows에서 Connection closed	npx 실행 방식	cmd /c npx ... 래퍼로 다시 추가
서버를 추가했는데 안 보임	실행 중 세션, scope 파일	세션 다시 열고 /mcp 확인
OAuth 로그인 후 도구가 안 뜸	인증 완료 여부, 서버 쪽 요구사항	/mcp로 다시 보고 브라우저 인증 재시도
N MCP servers failed만 뜸	서버 stderr 출력, 실제 도구 호출	라벨보다 실제 호출 성공 여부 먼저 보기
토큰은 넣었는데 권한 오류	환경 변수 전달 여부	셸에서 값 확인하고 claude mcp get <name>으로 설정 다시 보기

윈도우 쪽은 특히 주의할 게 있어요. 기본 Windows 환경에서는 npx 로컬 서버를 바로 못 띄우는 경우가 있어서 cmd /c 래퍼를 붙여야 해요.

# Windows 기본 환경 예시
claude mcp add --transport stdio github -- cmd /c npx -y @modelcontextprotocol/server-github

기본 설치나 PATH부터 다시 봐야 할 때는 Claude Code 공식 설치 가이드도 같이 열어두세요. 설치 문제랑 MCP 문제를 헷갈리면 시간만 더 먹어요.

자주 묻는 질문

실제로 자주 막히는 질문만 골랐어요. 프롬프트 쪽까지 같이 다듬고 싶으면 AI 프롬프트 엔지니어링: 블로거가 바로 쓸 수 있는 7가지 실전 기법도 이어서 보면 좋아요.

Q1. MCP 서버를 추가했는데 Claude Code에서 안 보여요. 재시작해야 하나요?

A: 먼저 /mcp부터 보세요. 거기서도 안 보이면 세션을 다시 여는 쪽이 안전해요. 설정 파일만 바꾸고 같은 세션을 계속 잡고 있으면 바로 반영 안 되는 경우가 있거든요.

Q2. stdio와 HTTP 가운데 뭘 먼저 써야 하나요?

A: 내 컴퓨터에서 같이 띄우는 도구면 stdio부터 가세요. 팀이 같이 쓰는 원격 엔드포인트나 SaaS 연동이면 HTTP가 편해요. 처음엔 둘 다 하려 하지 말고 하나만 고르는 게 덜 꼬여요.

Q3. MCP 서버를 켜니까 컨텍스트가 빨리 차요. 뭐부터 줄이면 되죠?

A: Tool Search를 끄지 않았는지 먼저 보세요. 그다음 /context로 어떤 서버가 많이 먹는지 보고, 안 쓰는 서버부터 빼면 돼요. 출력이 큰 도구는 필터를 주는 게 상한 올리는 것보다 먼저예요.

Q4. /mcp에 failed가 뜨는데 실제 호출은 돼요. 무시해도 되나요?

A: 바로 지우진 마세요. 서버가 시작할 때 stderr로 배너나 경고를 찍으면 failed처럼 보일 수 있어요. 실제 도구 호출이 되는지 한 번 더 테스트한 뒤 판단하는 편이 나아요.

Q5. 팀원들이랑 같은 MCP 설정을 공유하려면 어떻게 하나요?

A: project 범위로 넣고 .mcp.json을 같이 관리하면 돼요. 키는 환경 변수로 빼고, 파일에는 ${VAR}나 ${VAR:-default} 같은 형태만 남겨두는 게 덜 위험해요.

다음 단계

여기까지 읽었으면 mcp 서버 사용법의 큰 그림은 잡힌 셈이에요. 지금 claude mcp add로 서버 하나만 붙여보세요. 붙인 뒤엔 /mcp만 보지 말고 실제 도구 호출 한 번까지 해보는 게 핵심이에요.