Claude Code에 원하는 외부 도구를 붙이는 것은 MCP(Model Context Protocol — Claude가 깃허브·노션·센트리 같은 외부 서비스와 직접 대화하도록 해 주는 연결 규약) 커넥터를 명령어 한 줄로 설치하면 끝나는 일입니다. 이 글을 따라 하면 15~20분 안에 실무에서 자주 쓰는 커넥터(깃허브·센트리·데이터베이스 등)를 최소 하나 연결하고, 앞으로 어떤 커넥터를 어떤 기준으로 고르면 되는지까지 감을 잡을 수 있습니다.
🟢 현행 모델 라인업 일치 · 모델 안내 · Fable 구독 안내
Fable 5·5.1 구독 안내(2026년 9월 7일 갱신): 2026년 9월 1일 출시된 Claude Fable 5.1이 현행 Fable 모델이고, Fable 5는 레거시로 전환됐습니다. 구독 조건은 두 모델이 같습니다 — Max·Team Premium 플랜은 주간 사용 한도의 50% 범위에서 포함되고, Pro·Team Standard 플랜은 사용량 크레딧(입력 100만 토큰당
MCP 커넥터란 무엇인가요?
MCP 커넥터는 Claude Code가 깃허브 이슈, 센트리 에러 로그, 노션 문서, 데이터베이스 같은 외부 서비스를 직접 읽고 조작하게 해 주는 연결 고리입니다. 커넥터가 없으면 다른 도구에서 정보를 복사해 대화창에 붙여 넣어야 하지만, 커넥터를 연결하면 "센트리에서 어제 발생한 에러 가장 많은 것 알려줘"처럼 말만 해도 Claude가 해당 서비스에 직접 접속해 답합니다. 공식 문서는 이런 상황, 즉 이슈 트래커나 모니터링 대시보드의 내용을 대화창에 복사해 넣고 있다면 그때가 커넥터를 연결할 때라고 안내합니다.
기술적으로 MCP 커넥터는 두 가지 방식(전송 방식) 중 하나로 연결됩니다. 원격 서비스는 HTTP 방식(클라우드에 있는 서버에 인터넷으로 접속), 내 컴퓨터에서 직접 실행하는 도구는 stdio 방식(로컬 프로세스로 실행)을 씁니다. 어떤 방식을 쓸지는 커넥터마다 정해져 있어서, 공식 안내에 나온 명령어를 그대로 따라 하면 됩니다.
시작 전 준비물
- Claude Code CLI가 설치되어 있고 로그인된 상태 (터미널에서
claude명령어가 실행되는지 먼저 확인하세요) - 터미널(명령 프롬프트) 사용 환경 — macOS, Windows, Linux 모두 가능
- 연결하려는 서비스의 계정 (예: 깃허브 계정, 센트리 계정)과 필요 시 접근 토큰을 발급할 수 있는 관리자 권한
용어 빠른 풀이
- MCP(Model Context Protocol) — Claude가 외부 도구·데이터에 접속하는 공개 표준 규약
- 커넥터(connector) — MCP 규약으로 특정 서비스와 연결된 서버 하나하나를 부르는 말
- 전송 방식(transport) — 커넥터가 연결되는 방법. 원격 서비스는 HTTP, 로컬 실행 도구는 stdio
- 스코프(scope) — 이 커넥터를 나만 쓸지, 프로젝트 전체 팀원과 공유할지, 내 모든 프로젝트에서 쓸지 정하는 범위
- PAT(Personal Access Token) — 계정 비밀번호 대신 쓰는 개인용 접근 토큰. 깃허브 등에서 발급받습니다
- OAuth — 브라우저에서 로그인 화면을 띄워 안전하게 인증하는 방식
어떤 커넥터부터 연결하면 좋을까요?
실무에서 자주 쓰이는 순서로는 코드 작업 중이면 깃허브, 오류 대응 중이면 센트리, 문서 작업이 많으면 노션, 데이터 조회가 잦으면 데이터베이스 커넥터를 먼저 연결하는 것이 좋습니다. 아래는 공식 문서에 실제 명령어 예시가 나와 있는 대표 커넥터입니다.
| 커넥터 | 주요 용도 | 전송 방식 | 인증 방식 |
|---|---|---|---|
| 깃허브(GitHub) | PR 리뷰, 이슈 생성·조회 | HTTP | PAT(개인 접근 토큰) |
| 센트리(Sentry) | 에러 모니터링, 장애 원인 분석 | HTTP | OAuth (/mcp에서 로그인) |
| 노션(Notion) | 문서 조회·작성 | HTTP | OAuth |
| PostgreSQL(dbhub 경유) | 데이터베이스 자연어 조회 | stdio(로컬 실행) | 연결 문자열(DSN) |
단계별 설치 방법
MCP 커넥터 설치는 ①명령어로 커넥터 추가 → ②/mcp로 인증 → ③대화에서 사용, 이 3단계로 끝납니다. 아래부터는 실제로 확인된 명령어 예시입니다.
1단계 — 깃허브 커넥터 추가하기 (원격 HTTP 방식 예시)
깃허브의 공식 원격 MCP 서버는 개인 접근 토큰(PAT)을 헤더로 전달해 인증합니다. 깃허브 설정에서 세밀한(fine-grained) 토큰을 새로 발급해 원하는 저장소에만 권한을 주고, 아래처럼 커넥터를 추가합니다.
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
--header "Authorization: Bearer YOUR_GITHUB_PAT"주의: claude mcp add는 토큰이 맞는지 검증하지 않고 그대로 저장합니다. 즉 잘못된 토큰을 넣어도 명령어 자체는 성공합니다. 반드시 다음 단계에서 실제 연결 상태를 확인해야 합니다.
2단계 — /mcp로 인증하고 연결 상태 확인하기
Claude Code 안에서 아래 명령어를 입력합니다.
/mcpOAuth 방식 커넥터(센트리·노션 등)는 여기서 브라우저 로그인 화면이 뜨며 안내를 따라 로그인하면 됩니다. 이렇게 보이면 성공: /mcp 목록에서 해당 커넥터 상태가 connected로 표시됩니다. 자격 증명이 잘못됐다면 failed로 표시되므로, 토큰을 다시 확인하세요.
3단계 — 데이터베이스처럼 로컬로 실행하는 커넥터 (stdio 방식 예시)
PostgreSQL 데이터베이스는 dbhub라는 도구를 로컬에서 실행해 연결합니다.
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
--dsn "postgresql://readonly:[email protected]:5432/analytics"주의: stdio 방식 커넥터는 명령어 중간에 --(하이픈 두 개)를 반드시 넣어야 합니다. 이 기호 앞은 Claude Code 자체 옵션(--transport, --env 등), 뒤는 실제 실행할 프로그램과 그 인자입니다. --를 빠뜨리면 뒤에 오는 값을 Claude Code가 자신의 옵션으로 잘못 해석해 오류가 납니다.
연결 후에는 "이번 달 총 매출이 얼마야?"처럼 자연어로 데이터베이스에 질문할 수 있습니다.
자주 막히는 지점과 해결
- 인증 없이는 목록에만 있고 실제로 안 붙는다 — 커넥터를 추가한 직후에는 설정만 저장된 상태입니다. 반드시
/mcp를 실행해 인증까지 마쳐야 실제로 작동합니다. - 401 Unauthorized·403 Forbidden 오류 — 토큰이 만료됐거나 권한이 부족한 경우입니다.
/mcp에서 재인증하거나 토큰을 새로 발급하세요. - 오래된 npm 패키지 안내를 따라 하다 막힘 —
@modelcontextprotocol/server-github,@modelcontextprotocol/server-postgres같은 예전 방식의 로컬 설치 패키지는 더 이상 권장되지 않는 보관(deprecated) 상태입니다. 이런 안내를 발견하면, 위에서 소개한 최신 원격 커넥터(깃허브 공식 엔드포인트)나 dbhub 같은 대안을 대신 쓰세요. - stdio 명령어에서 뒤쪽 옵션이 이상하게 파싱된다 —
--구분자를 빠뜨렸을 가능성이 큽니다. 위 데이터베이스 예시처럼-- npx ...형태로 실행할 프로그램 앞에 반드시 넣으세요.
스코프 지정 — 나만 쓸지, 팀과 공유할지
커넥터를 어디까지 공유할지는 -s 또는 --scope 옵션으로 정합니다. 아무 옵션도 안 주면 local(기본값)로 저장되어 현재 프로젝트에서 나만 사용합니다. project로 지정하면 .mcp.json 파일에 저장되어 버전 관리 시스템(git 등)으로 커밋해 팀원과 공유할 수 있고, 팀원은 처음 실행할 때 승인 절차를 거칩니다. user로 지정하면 내 모든 프로젝트에서 공통으로 쓸 수 있습니다.
# 팀과 공유하는 예시
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp연결 후 관리 명령어
| 명령어 | 기능 |
|---|---|
claude mcp list | 연결된 커넥터 전체 목록 확인 |
claude mcp get github | 특정 커넥터의 상세 상태 확인 |
claude mcp remove github | 커넥터 삭제 |
/mcp (대화 중) | 연결 상태 확인 및 인증 |
응용/다음 단계
더 다양한 커넥터를 미리 둘러보고 싶다면 Anthropic이 검토한 커넥터 목록인 Anthropic Directory를 참고하세요. 여기 올라온 원격 서버는 앞서 설명한 것과 동일한 claude mcp add 명령어로 바로 추가할 수 있습니다. claude.ai 계정으로 이미 claude.ai/customize/connectors에서 커넥터를 연결해 두었다면, 같은 계정으로 Claude Code에 로그인했을 때 자동으로 목록에 나타납니다. 더 자세한 옵션은 공식 MCP 문서에서 확인할 수 있습니다.
자주 묻는 질문
Q. 커넥터를 추가하기만 하면 바로 쓸 수 있나요?
아니요, claude mcp add로 추가한 뒤에도 /mcp로 인증(로그인)까지 마쳐야 실제로 연결됩니다. 추가 명령어 자체는 자격 증명을 검증하지 않으므로, 반드시 /mcp에서 connected 상태인지 확인하세요.
Q. 회사·팀 전체가 같은 커넥터를 쓰게 하려면 어떻게 하나요?--scope project 옵션으로 추가하면 프로젝트 루트의 .mcp.json 파일에 저장되어 버전 관리로 팀원과 공유할 수 있습니다. 다만 팀원 각자 처음 실행할 때 보안을 위한 승인 절차를 거칩니다.
Q. claude.ai에서 이미 추가한 커넥터가 Claude Code에도 나타나나요?
네, claude.ai 계정으로 Claude Code에 로그인되어 있다면 claude.ai에서 추가한 커넥터가 자동으로 /mcp 목록에 나타납니다. 단, API 키 등 다른 인증 방식을 쓰는 경우는 해당하지 않습니다.
Q. 로컬에 npm 패키지를 설치하는 예전 방식과 원격 HTTP 방식 중 뭐가 나은가요?
가능하면 원격 HTTP 방식을 우선 고려하는 것이 좋습니다. 원격 HTTP 서버는 가장 널리 지원되는 방식이고, 일부 예전 로컬 패키지(예: 깃허브·PostgreSQL용 구버전 npm 패키지)는 보관(deprecated) 상태로 더 이상 권장되지 않습니다.
다른 커넥터도 찾고 있다면 커넥터 디렉토리에서 자주 쓰는 커넥터를 용도별로 검색·필터해볼 수 있습니다.