Using Claude

Claude Code에 커스텀 커넥터 추가하기 — MCP 서버 설정 완전 가이드

Claude Code에 외부 도구를 연결하는 MCP 서버 설정 방법을 단계별로 안내합니다. 원격 HTTP 서버부터 로컬 서버까지, 처음 연결하는 분도 따라 할 수 있습니다.

Claude Code에 외부 도구를 연결하고 싶은데 어디서부터 시작해야 할지 모르겠다면, 이 글이 그 출발점입니다. MCP — Model Context Protocol, 즉 AI와 외부 도구를 연결하는 공개 규약 — 를 이용하면 Claude Code가 Notion, GitHub, PostgreSQL 같은 서비스에 직접 접근할 수 있습니다. 데이터를 일일이 복사해서 붙여 넣을 필요가 없어집니다. 이 글을 끝까지 따라 하면 원격 서버 하나를 Claude Code에 연결하고, 실제로 동작하는 것을 확인할 수 있습니다. 예상 소요 시간은 10~15분입니다.

Claude Code 여러분의 작업 환경 MCP 서버 연결 규약 처리 외부 도구 Notion · GitHub PostgreSQL 등 명령 전달 데이터 요청 Claude Code → MCP 서버 → 외부 도구: 세 요소가 이어져야 연결이 완성됩니다

시작 전 준비물 확인

설정을 시작하기 전에 아래 항목을 먼저 확인하세요.

  • Claude Code 설치 여부 — 터미널(명령 프롬프트)에서 claude --version을 실행했을 때 버전 번호가 나와야 합니다. 설치가 안 되어 있다면 공식 문서의 설치 안내를 먼저 따르세요.
  • 연결할 서버의 URL 또는 실행 명령어 — 예를 들어 Notion MCP 서버라면 https://mcp.notion.com/mcp 같은 주소가 필요합니다.
  • 인증 토큰(필요한 경우) — 서비스에 따라 API 키나 Bearer 토큰이 필요할 수 있습니다. 해당 서비스의 계정 설정 페이지에서 미리 발급받아 두세요.

용어 빠른 풀이

  • MCP — Model Context Protocol. AI(Claude)와 외부 도구를 잇는 공개 연결 규약입니다. 일종의 공통 언어라고 생각하면 됩니다.
  • MCP 서버 — Claude Code와 외부 서비스 사이에서 '통역사' 역할을 하는 프로그램입니다. 직접 만들 수도 있고, 이미 만들어진 것을 가져다 쓸 수도 있습니다.
  • stdio — Standard Input/Output. 컴퓨터 안에서만 실행되는 로컬 MCP 서버가 쓰는 통신 방식입니다.
  • HTTP 서버 — 인터넷 주소(URL)를 통해 접근하는 원격 MCP 서버입니다. 가장 널리 쓰이는 방식입니다.
  • SSE — Server-Sent Events. 서버가 클라이언트에게 실시간으로 데이터를 밀어 보내는 방식입니다.
  • 범위(scope) — 연결한 MCP 서버가 어디서 작동하는지 결정하는 설정입니다. 내 컴퓨터 전체, 특정 프로젝트, 또는 나 혼자만 쓸지를 고릅니다.
  • Bearer 토큰 — 서비스에 내가 누구인지 증명하는 인증 열쇠입니다. 비밀번호처럼 안전하게 보관해야 합니다.

방법 1: 원격 HTTP 서버 연결 (가장 권장)

원격 HTTP 서버 방식은 공식 문서에서도 가장 넓게 지원된다고 명시한 방법입니다. Notion, GitHub 같이 이미 MCP 서버를 제공하는 서비스에 연결할 때 사용합니다.

  1. 터미널을 열고 아래 명령어를 입력합니다. <이름>은 내가 이 서버를 부를 별명(영문), <URL>은 서버 주소입니다.

    claude mcp add --transport http <이름> <URL>

    예를 들어 Notion에 연결한다면:

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

  2. 인증 토큰이 필요한 서비스라면 --header 옵션으로 토큰을 함께 전달합니다.

    claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer 여기에-토큰-입력"

  3. 연결이 등록되면 이렇게 보이면 성공입니다. 터미널에 "Added MCP server" 또는 서버 이름이 포함된 확인 메시지가 나타납니다. 이후 Claude Code 세션을 새로 시작하면 해당 도구를 사용할 수 있습니다.

방법 2: 원격 SSE 서버 연결

일부 오래된 서비스는 HTTP 대신 SSE 방식을 씁니다. 연결하려는 서비스의 문서에 SSE라고 명시된 경우에만 이 방법을 씁니다.

claude mcp add --transport sse <이름> <URL>

방법 3: 로컬 stdio 서버 연결

내 컴퓨터에서 직접 실행되는 MCP 서버를 연결할 때 씁니다. 직접 만든 서버나, 인터넷 연결 없이 작동해야 하는 경우에 적합합니다.

claude mcp add <이름> <실행명령어> [인수...]

예를 들어, my-server라는 Node.js 스크립트를 연결한다면:

claude mcp add my-server node /path/to/my-server.js

범위(Scope) 설정 — 어디서 쓸지 정하기

MCP 서버 범위(Scope) 비교 Local (기본값) Project User 현재 프로젝트 폴더 나만 사용 현재 프로젝트 폴더 팀 전체 공유 가능 모든 프로젝트 나만 사용 .mcp.json (gitignore 권장) .mcp.json (git 저장소에 커밋) ~/.claude.json (홈 디렉토리) --scope local --scope project --scope user

MCP 서버를 추가할 때 --scope 옵션으로 적용 범위를 지정할 수 있습니다. 범위를 따로 지정하지 않으면 local(현재 프로젝트, 나만 사용)이 기본값입니다.

  • local(기본) — 지금 열려 있는 프로젝트 폴더에서만 작동합니다. 설정은 .mcp.json에 저장되며, 나만 씁니다. 개인 인증 토큰처럼 외부에 노출되면 안 되는 정보가 있을 때 적합합니다.
  • project — 프로젝트 폴더에서 팀원 전체가 쓸 수 있습니다. .mcp.json 파일을 git 저장소에 올려 팀과 공유할 때 씁니다. 주의: 이 파일에 토큰·비밀번호 같은 민감 정보를 직접 넣지 마세요.
  • user — 내 컴퓨터의 모든 프로젝트에서 작동합니다. 자주 쓰는 개인용 도구를 한 번만 등록해 두고 싶을 때 편리합니다.

범위를 지정해서 추가하는 예시입니다.

# 팀 전체가 쓸 수 있도록 project 범위로 추가
claude mcp add --transport http --scope project notion https://mcp.notion.com/mcp

# 내 모든 프로젝트에서 쓸 수 있도록 user 범위로 추가
claude mcp add --transport http --scope user my-tool https://my-tool.example.com/mcp

등록된 서버 확인 및 관리

현재 등록된 MCP 서버 목록을 보려면 아래 명령어를 입력합니다.

claude mcp list

특정 서버를 삭제하려면:

claude mcp remove <서버-이름>

이 명령어를 실행하면 등록된 서버 이름, 종류, 상태가 표시됩니다. 방금 추가한 서버 이름이 목록에 나타나면 등록에 성공한 것입니다.

자주 막히는 지점과 해결 방법

  • "claude 명령어를 찾을 수 없습니다" 오류
    Claude Code가 설치되지 않았거나 터미널 경로 설정이 안 된 상태입니다. Claude Code를 먼저 설치하고, 설치 후 터미널을 새로 열어 다시 시도하세요.
  • 서버는 추가됐는데 Claude Code에서 도구가 보이지 않을 때
    서버를 추가한 뒤에는 Claude Code 세션을 완전히 종료하고 다시 시작해야 적용됩니다. 이미 열려 있는 세션에서는 바로 반영되지 않을 수 있습니다.
  • 인증 오류(401 Unauthorized 등)
    Bearer 토큰이 잘못됐거나 만료된 경우입니다. 해당 서비스에서 토큰을 새로 발급받아 --header 옵션으로 다시 등록하세요.
  • ⚠️ 신뢰하지 않는 서버는 절대 연결하지 마세요. MCP 서버는 Claude Code 세션에서 외부 콘텐츠를 가져올 수 있기 때문에, 악의적으로 만들어진 서버는 프롬프트 인젝션 — 원하지 않는 명령이 몰래 실행되는 현상 — 위험이 있습니다. Anthropic 공식 디렉터리에서 검토된 커넥터를 먼저 확인하세요.
  • project 범위 .mcp.json에 토큰을 넣었을 때
    git에 커밋하는 순간 토큰이 외부에 노출됩니다. 민감 정보는 반드시 환경 변수로 관리하거나 local 범위를 사용하세요.

JSON 설정 파일로 직접 추가하기

명령어 대신 .mcp.json 파일을 직접 편집해서 서버를 추가할 수도 있습니다. 여러 서버를 한꺼번에 등록하거나, 팀과 설정을 공유할 때 편리합니다. 아래는 기본 형태입니다.

{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

참고로 JSON 설정에서는 http 대신 streamable-http를 type 값으로 써도 됩니다. 공식 문서에 따르면 두 표기는 동일하게 동작합니다.

다음 단계: 더 활용하기

커넥터를 연결했다면, 이제 Claude Code에게 이런 식으로 직접 요청해 볼 수 있습니다.

  • "JIRA 이슈 ENG-4521에 설명된 기능을 구현하고 GitHub에 PR을 만들어줘."
  • "PostgreSQL 데이터베이스에서 최근 가입한 사용자 10명의 이메일을 찾아줘."
  • "Slack에 올라온 새 Figma 디자인을 반영해서 이메일 템플릿을 수정해줘."

연결할 수 있는 서비스 목록은 Anthropic 공식 디렉터리에서 확인할 수 있습니다. 디렉터리에 등재된 서버는 검토 과정을 거쳤으므로 처음 시작하는 분께 적합합니다. 직접 MCP 서버를 만들고 싶다면, Claude Code 세션에서 /plugin install mcp-server-dev@claude-plugins-official 명령으로 공식 플러그인을 설치해 시작할 수 있습니다.

이어서 읽어보세요

Claude Code 설정 파일(settings.json) 완전 정리 — 권한·환경변수·도구 설정

Claude Code의 settings.json 구조와 스코프 체계를 처음부터 차근차근 설명합니다. 전역·프로젝트·로컬 설정을 어떻게 나눠 쓰는지, 어디에 파일을 두면 되는지 한눈에 파악할 수 있습니다.

1

PostgreSQL MCP 서버 — 클로드에 데이터베이스 연결하기 (2026)

클로드가 PostgreSQL 스키마를 보고 읽기 쿼리를 실행하도록 연결하는 방법입니다. 아카이브된 공식 서버 사용법과 권장 대안, 안전한 설정을 정리했습니다.

3

Playwright MCP 서버 설정 — 클로드로 브라우저 자동화 (2026)

마이크로소프트 공식 Playwright MCP 서버로 클로드가 브라우저를 열어 클릭·입력하게 하는 방법입니다. npx 설정과 Claude in Chrome과의 차이를 정리했습니다.

2

GitHub MCP 서버 설정 — 클로드에서 레포·이슈·PR 다루기 (2026)

GitHub 공식 MCP 서버로 클로드에서 레포·이슈·PR을 다루는 방법입니다. 원격(GitHub 호스팅)과 로컬(Docker) 두 방식의 설정·인증을 정리했습니다.

3

이 주제, 커뮤니티에서 이야기 나눠요

'클로드 코딩' 게시판 · 글 2개 · 최근: Claude Code 반복 지시 줄이기 — CLAUDE.md부터 만들어 보세요

클로드 코딩에서 토론하기 →Claude Code 더 보기