Claude Code에 MCP 서버 연동하기 — 노션·GitHub·Sentry 붙이는 법

노션 문서·GitHub 이슈·에러 로그를 Claude Code 채팅에 계속 복사해 붙여넣고 있을 겁니다. 그럴 때마다 맥락이 끊기고, 매번 어디서 뭘 가져올지 찾느라 시간이 새 나갑니다.

여러 외부 서비스를 Claude Code에 연결해 써온 관점에서, 헷갈리기 쉬운 지점만 골라 정리했습니다. 이 순서대로 가면 노션·GitHub·DB를 명령 한 줄로 붙여 Claude가 직접 읽고 조작하는 것까지 끝납니다.

1. MCP 연동이 뭔가 — 연결과 제작은 다릅니다

MCP(Model Context Protocol)는 AI 클라이언트와 외부 도구를 잇는 USB-C 같은 개방형 표준입니다. 노션·GitHub·구글 커넥터가 바로 그 회사나 앤스로픽이 미리 만들어 둔 MCP 서버예요. 그러니까 대부분의 사람이 할 일은 서버를 만드는 게 아니라, 이미 있는 서버에 연결(연동) 하는 것입니다.

 

혼동 지점이 여기입니다. 연동은 claude mcp add로 기존 서버에 붙이는 일이고, 커넥터가 없는 내 도구를 직접 만드는 제작은 완전히 다른 작업입니다. 이 글이 다루는 건 연동뿐, 제작은 별도 글에서 SDK 코드와 함께 정리했습니다.

 

언제 붙이나. 이슈 트래커·모니터링·DB 데이터를 채팅에 계속 복붙하고 있다면 그때가 MCP 서버 연동을 할 때입니다. 붙이고 나면 Claude가 그 데이터를 직접 읽고 조작합니다. 검증된 커넥터는 앤스로픽 디렉터리(claude.ai/directory) 에서 찾아 claude mcp add로 연결하면 됩니다.

2. 연결 방식 3가지와 기본 문법

MCP 서버 연동은 transport(연결 방식)를 먼저 정하는 데서 시작합니다. 종류는 세 가지입니다.

방식	언제 쓰나	특징
HTTP (--transport http)	원격·클라우드 서비스 (권장)	OAuth 지원, 가장 널리 쓰임
stdio (--transport stdio, 기본)	내 PC 로컬 도구·스크립트	자식 프로세스로 실행
SSE (--transport sse)	deprecated	쓰지 말고 HTTP로

노션·GitHub·Sentry 같은 클라우드 서비스는 전부 HTTP입니다. 로컬 DB나 직접 돌리는 스크립트만 stdio를 씁니다. SSE는 예제 코드에 남아 있더라도 따라가면 시간만 버리니 HTTP로 대체하면 됩니다.

 

기본 문법은 두 갈래입니다. HTTP는 claude mcp add --transport http <이름> <url> 꼴이고, stdio는 claude mcp add [옵션] <이름> -- <명령> [인자]처럼 -- 뒤에 서버 실행 명령을 씁니다. -- 앞은 Claude 옵션, 뒤는 실행 명령이라고 나누면 헷갈리지 않습니다. 환경변수는 -e KEY=value(또는 --env), 인증 헤더는 --header(-H)로 넘깁니다.

 

등록 스코프는 세 가지고, 같은 이름이 여러 스코프에 있으면 병합이 아니라 우선순위(local > project > user) 가장 높은 정의 하나만 적용됩니다.

스코프	저장 위치	공유 범위
local (기본)	~/.claude.json	나, 이 프로젝트만
project (-s project)	.mcp.json	git 커밋으로 팀 공유
user (-s user)	전역 설정	나, 모든 프로젝트

3. 실전 — 서버 4개 붙이기

이제 실제로 붙입니다. 명령은 아래 그대로 쓰면 됩니다.

노션 (HTTP, OAuth). 붙인 뒤 Claude Code 안에서 /mcp를 치면 브라우저 로그인이 뜹니다.

claude mcp add --transport http notion https://mcp.notion.com/mcp

GitHub (HTTP + PAT). 헤더에 fine-grained 토큰을 실어 붙입니다. 붙이면 "PR #456 리뷰해줘" 식으로 시킬 수 있습니다.

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_GITHUB_PAT"

Sentry (HTTP + OAuth). 붙인 뒤 /mcp로 인증하면 "최근 24시간 가장 잦은 에러는?"을 바로 물어볼 수 있습니다.

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

PostgreSQL (stdio, 로컬). 로컬 DB는 읽기전용 계정으로 붙이는 게 안전합니다. "orders 테이블 스키마 보여줘"처럼 물으면 됩니다.

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "postgresql://readonly:pass@host:5432/db"

여기서 구글·Gmail·캘린더는 다릅니다. 이들은 앤스로픽 호스팅 커넥터라 Claude Code의 로컬 OAuth를 지원하지 않아 CLI로 안 붙습니다. claude.ai 설정 → 커넥터에서 연결하면, 같은 계정으로 로그인한 Claude Code에 자동으로 뜹니다. 노션처럼 CLI로 되는 커넥터가 있고, 구글처럼 웹에서 연결해야 뜨는 커넥터가 있다는 것만 기억하면 됩니다.

4. 인증·관리·보안 함정

붙이는 명령보다 그 뒤가 더 자주 막힙니다. 원격 서버가 401/403을 내면 인증이 필요하다는 표시입니다. Claude Code 안에서 /mcp를 치면 브라우저 OAuth가 뜨고, 셸에서는 claude mcp login <이름>으로도 됩니다. 토큰은 안전하게 저장되고 자동 갱신됩니다.

 

관리 명령은 몇 개 안 됩니다. claude mcp list(목록), claude mcp get <이름>(상세), claude mcp remove <이름>(삭제), 대화 안에서 /mcp(연결 상태). Claude Desktop 설정을 그대로 가져오려면 claude mcp add-from-claude-desktop(macOS·WSL), JSON을 직접 넣으려면 claude mcp add-json <이름> '<json>'을 씁니다.

⚠️ 보안 — 신뢰하는 서버만 붙입니다

외부 콘텐츠를 가져오는 서버에는 프롬프트 인젝션 위험이 있습니다. 가져온 문서·이슈 본문에 숨겨진 지시가 섞여 Claude가 의도치 않은 동작을 할 수 있습니다. 출처가 불분명한 서버는 붙이지 않는 게 맞습니다.

팀 공유 함정도 하나 있습니다. .mcp.json(project 스코프)은 git에 커밋되지만, clone한 팀원 화면에서는 서버가 곧바로 안 붙습니다. claude를 실행해 워크스페이스 신뢰 승인을 하기 전까지는 ⏸ Pending approval 상태로 대기합니다. "커밋했는데 왜 팀원 쪽에서 안 뜨냐"는 대개 이 승인 단계를 안 거친 경우입니다.

증상: 원격 서버를 붙였는데 대화창에서 해당 tool이 안 보입니다.

원인: 처음 Sentry를 붙였을 때 겪은 건데, 십중팔구 OAuth 인증을 안 한 401 상태입니다. add는 됐지만 로그인을 안 해 서버가 tool 목록을 안 넘긴 겁니다.

해결: /mcp로 상태를 확인하고 그 자리에서 로그인하거나, 셸에서 claude mcp login <이름>으로 인증합니다.

참고로 붙인 뒤에는 서버의 리소스를 @서버:... 형태로, 미리 정의된 프롬프트를 /mcp__서버__프롬프트 형태로 대화에서 직접 불러 쓸 수 있습니다.

Q&A — 자주 보는 질문 4개

Q. 구글·Gmail은 왜 CLI로 안 붙나요?
A. 앤스로픽 호스팅 커넥터라 Claude Code의 로컬 OAuth를 지원하지 않습니다. claude.ai 설정 → 커넥터에서 연결하면 같은 계정으로 로그인한 Claude Code에 자동으로 나타납니다.

Q. 팀과 서버를 공유하려면요?
A. -s project로 등록하면 .mcp.json이 생기고, git에 커밋하면 됩니다. 단 팀원은 clone 후 claude를 실행해 워크스페이스 신뢰 승인을 해야 서버가 활성화됩니다. 승인 전에는 ⏸ Pending approval로 뜹니다.

Q. 붙였는데 tool이 안 보여요.
A. 대부분 인증 문제입니다. /mcp로 연결 상태를 보고 401이면 그 자리에서 로그인하거나 claude mcp login <이름>을 실행하세요. 목록 자체가 없으면 claude mcp list로 등록 여부부터 확인합니다.

Q. 커넥터에 없는 내 도구를 붙이려면요?
A. 그건 연동이 아니라 서버를 직접 만드는 작업입니다. @modelcontextprotocol/sdk로 tool 하나짜리 서버를 만들어 등록하는 방식이고, 코드가 필요합니다. 제작은 별도 글에서 최소 코드와 함께 다뤘습니다.

MCP 서버 연동의 핵심은 결국 두 가지입니다. 클라우드 서비스는 HTTP로 붙이고, 붙인 뒤 /mcp로 인증을 반드시 마치는 것. 같은 환경이면 위 순서대로 따라가도 무리 없습니다.

📎 이 카테고리의 다른 글

• Claude Code 서브에이전트 실전 배치 — 역할 분리부터 병렬 3~5개 스윗스팟까지 — 2026-07-06
• Claude Code 활용법 정리 — 망치는 습관 3개와 살리는 습관 7개 — 2026-04-26
• Claude Code 필수 설정 가이드 — 2026-03-20

같은 AI 활용법 카테고리에서 이어서 읽기

설치 환경: Windows 11, Node.js v24, Claude Code