Claude 심화 3단계 MCP 이해하고 연결하기
심화 3단계 MCP 이해하고 연결하기
Claude에게 "손과 발"을 달아 주는 표준 규격 — 클릭으로 연결하는 커넥터부터 claude mcp add 까지
· MCP가 무엇이고, 어떤 구조로 Claude에게 도구를 빌려주는지
· 방법① claude.ai·데스크톱 앱에서 커넥터로 클릭 연결하기 ★ (비개발자는 여기까지)
· 방법② Claude Code에서
claude mcp add 로 연결하고 스코프로 팀과 공유하기· 연결 확인 방법과 꼭 지켜야 할 보안 기본기
1 MCP란? — AI용 USB-C 규격
MCP(Model Context Protocol)는 AI가 외부 도구와 데이터에 연결하는 표준 규격입니다.
예전에는 기기마다 충전 단자가 달라서 서랍에 케이블이 가득했죠. USB-C로 규격이 통일되자 케이블 하나로 노트북·휴대폰·모니터를 다 연결합니다. MCP도 같습니다. 구글 드라이브든, 깃허브든, 사내 DB든 MCP 규격에 맞춰 만든 "서버"만 있으면 Claude는 같은 방식으로 꽂아서 쓸 수 있습니다.
나 "지난주 노션 회의록 요약해줘" → Claude(클라이언트) 노션 도구가 필요하다고 판단 → 노션 MCP 서버 페이지 검색·읽기 → Claude 결과를 받아 요약 → 나
원격 서버 vs 로컬 서버
https://mcp.notion.com/mcp claude.ai 커넥터와 Claude Code 모두 사용npx 같은 명령으로 실행합니다. Claude Code, 데스크톱 확장(.mcpb)2 방법① claude.ai·데스크톱 커넥터로 연결하기 ★ 따라하기
커넥터는 MCP를 클릭 몇 번으로 연결하게 만든 기능입니다. 모든 요금제에서 쓸 수 있고, 터미널이 필요 없습니다.
1. 왼쪽 사이드바의 Customize > Connectors로 들어갑니다. (예전 화면이나 옛 안내 글에서는 Settings > Connectors)
2. + 버튼을 눌러 디렉터리(목록)를 엽니다. Google Drive, Gmail, Google Calendar, Google Docs, Slack, Linear, Asana 같은 커넥터가 보입니다. 노션·깃허브 등도 디렉터리에서 찾아볼 수 있습니다(시점에 따라 다름).
3. 원하는 서비스를 골라 연결을 누르면 해당 서비스의 로그인·권한 동의 화면이 뜹니다. 요청하는 권한 범위를 읽어 보고 승인합니다.
4. 대화창으로 돌아와 + 메뉴(또는 /)에서 Connectors를 열면, 이번 대화에서 쓸 커넥터를 켜고 끌 수 있습니다. "Manage connectors"로 관리 화면에 바로 갈 수도 있습니다.
5. 첫 부탁을 해 봅니다.
구글 캘린더에서 이번 주 내 일정을 요일별로 정리해줘.
회의가 3개 이상인 날은 따로 표시해줘.커스텀 커넥터 — 목록에 없는 서버 연결
디렉터리에 없는 서비스라도 원격 MCP 서버 주소(URL)가 있다면 직접 추가할 수 있습니다.
1. Customize > Connectors → + → Add custom connector
2. 원격 MCP 서버 URL을 붙여넣습니다. 서버가 OAuth 정보를 요구하면 Advanced settings에 입력합니다.
3. Add를 누르고, 로그인 절차가 나오면 진행합니다.
데스크톱 확장(.mcpb) — 로컬 서버를 클릭 한 번으로
Claude 데스크톱 앱에서는 로컬 MCP 서버를 .mcpb 라는 원클릭 설치 파일로 설치할 수 있습니다. macOS·Windows·Linux를 지원하고 Node.js가 앱에 내장되어 있어 따로 설치할 필요가 없습니다.
.mcpb 파일 선택3 방법② Claude Code에서 claude mcp add
Claude Code에서는 터미널 명령 한 줄로 MCP 서버를 추가합니다. 기본 모양은 원격과 로컬이 조금 다릅니다.
# 원격(HTTP) 서버
claude mcp add --transport http <이름> <URL>
# 로컬(stdio) 서버 — 옵션은 모두 이름 앞에, 실행 명령은 -- 뒤에
claude mcp add [옵션] <이름> -- <실행명령> [인자...]--transport -thttp 또는 stdio--env -e--header -H--scope -slocal(기본) · project · user → 4절--예시 ① 노션 — 원격, OAuth 로그인
claude mcp add --transport http notion https://mcp.notion.com/mcp추가한 뒤 Claude Code 세션에서 /mcp 를 입력하면 로그인이 필요한 서버가 보이고, 거기서 브라우저 로그인을 진행합니다. Sentry(https://mcp.sentry.dev/mcp)도 같은 방식입니다.
예시 ② 깃허브 — 원격, 헤더로 토큰 전달
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
--header "Authorization: Bearer YOUR_GITHUB_PAT"YOUR_GITHUB_PAT 자리에 깃허브에서 발급한 개인 액세스 토큰을 넣습니다. 토큰 권한은 필요한 저장소·기능만 최소로 주세요.
예시 ③ Airtable — 로컬, 환경변수로 키 전달
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
-- npx -y airtable-mcp-server예시 ④ 데이터베이스 — 로컬, 읽기 전용 계정으로
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
--dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"DBHub는 여러 DB에 연결하는 MCP 서버입니다. 예시에서 사용자 이름이 readonly 인 점에 주목하세요. 회사에서 Oracle 등 운영 DB에 붙일 때도 조회 전용 계정을 따로 만들어 연결하는 것이 기본입니다. 실제 연결 문자열 형식은 DB 종류에 따라 다르니 서버 안내 문서를 확인하세요.
claude mcp add playwright -- npx @playwright/mcp@latest 로 추가하는 경우가 많습니다. 공식 문서 예시는 아니므로 4단계 실전편에서 자세히 다룹니다.4 스코프 3가지와 .mcp.json
같은 서버라도 "나만 이 프로젝트에서 쓸지", "팀 전체가 쓸지", "내 모든 프로젝트에서 쓸지"를 정할 수 있습니다.
local (기본값)~/.claude.json 안에 해당 프로젝트 항목으로 저장됩니다. 개인 토큰이 들어간 서버, 시험 삼아 붙여 보는 서버에 적합.project.mcp.json 파일에 저장되어 git에 커밋할 수 있습니다. 팀원이 처음 쓸 때는 승인을 묻습니다.user~/.claude.json 에 전역으로 저장. 어디서든 쓰는 개인 도구(예: 노션)에 적합.# 팀 공유용으로 추가 → 프로젝트 루트에 .mcp.json 생성
claude mcp add --scope project --transport http notion https://mcp.notion.com/mcp
# 내 모든 프로젝트에서 쓰기
claude mcp add --scope user --transport http notion https://mcp.notion.com/mcp.mcp.json 과 환경변수 확장 — 토큰은 파일에 쓰지 않기
팀과 공유하는 .mcp.json 에 토큰을 그대로 적으면 git 기록에 비밀이 남습니다. 대신 ${변수} 로 적어 두면 각자 자기 컴퓨터의 환경변수 값이 채워집니다. ${변수:-기본값} 은 변수가 없을 때 기본값을 씁니다.
{
"mcpServers": {
"api-server": {
"type": "http",
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": {
"Authorization": "Bearer ${API_KEY}"
}
}
}
}# 각 팀원은 자기 셸 설정(~/.zshrc 등)에 값을 넣어 둠
export API_KEY="각자_발급받은_키"5 관리 명령과 /mcp
연결한 서버는 터미널 명령으로 보고, 지우고, JSON으로 한 번에 추가할 수 있습니다.
claude mcp listclaude mcp get <이름>claude mcp remove <이름>claude mcp add-json/mcp (세션 안)claude mcp add-json weather '{"type":"http","url":"https://api.example.com/mcp"}'MAX_MCP_OUTPUT_TOKENS 로 조정).6 따라해 보기 — 연결 확인 테스트
연결 화면에 "Connected"가 떠도 실제로 도구가 동작하는지는 부탁해 봐야 압니다. 가벼운 조회부터 시작하세요.
1단계 — 도구 목록 확인
지금 연결된 MCP 서버(커넥터)와 각각 쓸 수 있는 도구를 목록으로 보여줘.
도구마다 "읽기"인지 "쓰기/수정"인지도 표시해줘.2단계 — 읽기 전용 테스트
노션에서 "회의록"이 제목에 들어간 페이지를 최근 것부터 5개만 찾아서
제목과 마지막 수정일만 알려줘. 아무것도 수정하지 마.깃허브 [내 저장소]에서 열려 있는 이슈 목록을 가져와서
라벨별로 몇 개씩 있는지 표로 보여줘. 이슈를 닫거나 댓글을 달지는 마.db 서버에 연결해서 테이블 목록과 각 테이블의 대략적인 행 수만 보여줘.
SELECT 외의 쿼리는 실행하지 마.3단계 — 문제가 생기면
/mcp 에서 해당 서버를 골라 로그인. claude.ai라면 커넥터 관리 화면에서 다시 연결.claude mcp get <이름> 으로 설정 확인. stdio라면 -- 위치, 환경변수 이름, npx 실행 가능 여부(Node.js 설치)를 먼저 점검.7 보안 기본기 — 연결은 곧 권한 위임
MCP는 Claude에게 집 열쇠를 복사해 주는 일과 같습니다. 편리함만큼 조심할 부분도 분명합니다.
.mcp.json 에 직접 쓰지 말고 ${API_KEY} 처럼 환경변수로. 대화창에 토큰을 붙여넣지도 마세요.claude mcp remove 로 정리합니다./permissions, 훅)은 8단계와 12단계에서 다룹니다.8 정리 & 체크리스트
연결까지 끝났다면, 4단계에서 실제 업무 시나리오로 손에 익힙니다.
.mcpb)이 각각 언제 필요한지 안다claude mcp add.mcp.json 에 토큰 대신 환경변수를 썼다/mcp 와 claude mcp list 로 연결 상태를 확인하고, 테스트 프롬프트로 조회에 성공했다공식 문서: Claude Code MCP · 커넥터 · 커스텀 커넥터