클로드 코드에서 MCP 서버 연동하기

클로드 코드는 파일 읽기/쓰기, Bash 명령어 실행, 코드 검색처럼 개발에 필요한 핵심 도구를 기본으로 갖추고 있습니다. 그런데 실제 개발 작업을 하다 보면 GitHub에서 이슈를 만들거나 데이터베이스 스키마를 확인하거나 웹에서 최신 문서를 검색해야 할 때가 있잖아요?

이럴 때 MCP(Model Context Protocol) 서버를 연결하면 클로드 코드의 능력을 크게 확장할 수 있습니다. MCP 서버를 한번 설정해두면 “GitHub 이슈 42번 내용 알려줘”, “users 테이블 스키마 보여줘” 같은 자연어 요청만으로 외부 시스템을 다룰 수 있게 되거든요.

이 글에서는 클로드 코드에 MCP 서버를 추가하고 관리하는 방법을 처음부터 차근차근 살펴보겠습니다.

CLI로 MCP 서버 추가하기

가장 기본적인 방법은 claude mcp add 명령어입니다. 터미널에서 바로 실행할 수 있어서 간편해요.

claude mcp add <서버이름> -- <실행명령어> [인자...]

예를 들어 파일 시스템 MCP 서버를 추가하려면 이렇게 합니다.

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/projects

원격 서버라면 --transport 옵션으로 전송 방식을 지정해야 해요.

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

옵션 하나만 주의하면 됩니다. --transport, --env, --scope 같은 플래그는 반드시 서버 이름 앞에 써야 해요. 그리고 로컬 서버의 경우 --(이중 대시) 뒤에 실행 명령어를 적습니다.

전송 방식: stdio와 http

MCP 서버와 통신하는 방식은 크게 두 가지입니다.

stdio는 로컬에서 실행되는 서버에 쓰는 방식이에요. 클로드 코드가 해당 프로세스를 자식 프로세스로 띄우고 표준 입출력(stdin/stdout)으로 메시지를 주고받습니다. 지연 시간이 5ms 미만으로 빠르고, 네트워크 설정도 필요 없어서 대부분의 로컬 도구에 적합합니다. --transport를 생략하면 기본값이 stdio예요.

claude mcp add my-tool -- npx -y @some/mcp-package

http는 원격 서버를 위한 방식입니다. MCP 스펙 2025-03-26에서 도입된 Streamable HTTP 표준을 사용하며, 단일 HTTP 엔드포인트로 요청과 응답을 처리합니다. OAuth 2.1 인증도 지원하고요.

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

과거에 사용되던 SSE(Server-Sent Events) 방식은 2025년 3월부로 폐기(deprecated)되었습니다. 기존 SSE 서버가 있다면 Streamable HTTP로 전환하는 걸 권장합니다.

정리하면, 로컬 도구는 stdio, 원격 서비스는 http를 쓰면 됩니다.

.mcp.json으로 팀과 공유하기

혼자 쓸 때는 CLI로 하나씩 추가해도 괜찮지만, 팀 프로젝트에서는 모든 개발자가 동일한 MCP 환경을 갖추는 게 중요합니다. 이때 프로젝트 루트에 .mcp.json 파일을 만들어서 Git으로 관리하면 편해요.

.mcp.json
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"]
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

이 파일을 커밋해두면 팀원이 클로드 코드를 실행할 때 자동으로 같은 MCP 서버가 연결됩니다. 보안을 위해 프로젝트 스코프의 MCP 서버는 처음 사용할 때 승인 확인이 뜹니다.

환경 변수를 참조할 때는 ${변수명} 문법을 쓸 수 있습니다. 위 예시의 ${DATABASE_URL}처럼요. 기본값도 지정 가능한데, ${API_KEY:-my-default-key} 형태로 씁니다. 이 덕분에 민감한 정보를 파일에 직접 넣지 않아도 됩니다.

CLI에서도 --scope project 플래그를 쓰면 .mcp.json에 자동으로 추가돼요.

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

설정 범위 이해하기

MCP 서버 설정은 세 가지 범위(scope)로 나뉩니다. 각 범위마다 저장 위치와 용도가 다릅니다.

local (기본값)은 현재 프로젝트에서 나만 쓰는 설정입니다. ~/.claude.json 파일 안에 프로젝트 경로별로 저장돼요. Git에 올라가지 않으니 개인 토큰이나 실험적인 설정을 넣기 좋습니다.

claude mcp add my-tool -- npx -y @some/package

project는 팀 전체가 공유하는 설정이에요. 프로젝트 루트의 .mcp.json에 저장되며 Git으로 버전 관리됩니다. 프로젝트에서 꼭 필요한 도구를 여기에 넣어두면 팀원 모두 같은 환경을 쓸 수 있죠.

claude mcp add --transport http --scope project github https://api.githubcopilot.com/mcp/

user는 내 모든 프로젝트에 적용되는 전역 설정입니다. ~/.claude.json의 최상위에 저장됩니다. 어떤 프로젝트에서든 쓰고 싶은 범용 도구를 등록하기에 적합해요.

claude mcp add --transport http --scope user brave-search https://search.brave.com/mcp

같은 이름의 서버가 여러 범위에 있으면 local이 project보다, project가 user보다 우선합니다.

자주 쓰는 MCP 서버 예시

실무에서 유용한 MCP 서버 몇 가지를 소개합니다.

GitHub MCP 서버는 아마 가장 많이 쓰게 될 서버일 거예요. 이슈 생성이나 PR 리뷰, 코드 검색을 자연어로 할 수 있습니다.

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

설정 후에는 “이 버그를 GitHub 이슈로 만들어줘”나 “열린 PR 목록 보여줘” 같은 요청이 바로 먹힙니다. 더 자세한 설정 방법은 GitHub MCP 서버 사용법에서 다루고 있어요.

데이터베이스 서버는 스키마를 확인하거나 쿼리를 실행할 때 유용합니다. 프로덕션 DB에 연결할 때는 반드시 읽기 전용 계정을 사용하세요.

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

Playwright MCP 서버를 연결하면 브라우저 자동화가 가능해져요. 스크린샷을 찍고 웹 페이지를 탐색하고 E2E 테스트까지 돌릴 수 있습니다.

claude mcp add playwright -- npx -y @playwright/mcp@latest

Sentry는 원격 HTTP 서버로 제공되어 설정이 간단합니다. 에러 모니터링 데이터를 클로드 코드에서 바로 조회할 수 있어요.

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

이 외에도 Notion, Slack, Linear 같은 협업 도구의 MCP 서버가 있고, MCP Registry에서 수백 개의 공개 서버를 검색할 수 있습니다.

MCP 서버 관리하기

서버를 추가한 뒤에는 몇 가지 명령어로 관리할 수 있습니다.

현재 등록된 서버 목록을 보려면 list를 쓰세요.

claude mcp list

특정 서버의 상세 정보가 궁금하면 get으로 확인합니다.

claude mcp get github

더 이상 필요 없는 서버는 remove로 삭제해요.

claude mcp remove github

클로드 코드 대화 중에 서버 연결 상태를 확인하고 싶으면 /mcp 슬래시 명령어를 입력하면 됩니다. 각 서버의 연결 상태와 사용 가능한 도구 목록을 한눈에 볼 수 있어요. OAuth 인증이 필요한 서버는 여기서 인증을 진행할 수도 있습니다.

이미 존재하는 서버 설정을 JSON으로 직접 추가하고 싶다면 add-json 명령어도 있습니다.

claude mcp add-json weather '{"type":"http","url":"https://weather.example.com/mcp"}'

Claude Desktop에 이미 MCP 서버를 설정해둔 분이라면 한 번에 가져올 수도 있어요.

claude mcp add-from-claude-desktop

환경 변수로 민감한 정보 관리하기

API 키나 데이터베이스 비밀번호를 설정 파일에 직접 넣으면 보안 사고로 이어질 수 있죠. 클로드 코드는 이를 위해 두 가지 방법을 제공합니다.

CLI에서 추가할 때 -e 플래그로 환경 변수를 전달할 수 있어요.

claude mcp add brave-search -e BRAVE_API_KEY=your-key -- npx -y @modelcontextprotocol/server-brave-search

.mcp.json에서는 ${변수명} 문법으로 시스템 환경 변수를 참조합니다.

.mcp.json
{
  "mcpServers": {
    "brave-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    }
  }
}

원격 서버에 인증 헤더가 필요하면 --header 옵션을 사용합니다.

claude mcp add --transport http --header "Authorization: Bearer ${API_TOKEN}" my-api https://api.example.com/mcp

커밋 전에는 git diff --cached로 토큰이 포함되지 않았는지 꼭 확인하는 습관을 들이세요.

클로드 코드를 MCP 서버로 쓰기

재미있는 점은 클로드 코드 자체도 MCP 서버가 될 수 있다는 겁니다. claude mcp serve 명령어를 실행하면 클로드 코드의 내장 도구(Bash, Read, Write, Edit, Grep, Glob 등)가 MCP 도구로 노출됩니다.

claude mcp serve

이렇게 하면 Claude Desktop이나 다른 MCP 클라이언트에서 클로드 코드의 코딩 능력을 그대로 활용할 수 있어요. 예를 들어 Claude Desktop 설정에 다음과 같이 추가할 수 있습니다.

claude_desktop_config.json
{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"]
    }
  }
}

실전 팁

MCP를 실제 프로젝트에서 쓸 때 알아두면 좋은 것들을 정리했어요.

먼저 Node.js 버전을 확인하세요. stdio 방식의 MCP 서버 대부분이 npx를 사용하는데, Node.js 18 이상이 필요합니다. MCP 관련 오류의 90%는 Node.js 버전이 너무 낮아서 생깁니다. node -v로 한번 확인해보세요.

서버가 연결되지 않으면 실행 파일이 접근 가능한지, 토큰이 유효한지 점검해보세요. claude mcp list에서 서버가 “disconnected”로 나타나면 클로드 코드를 재시작해보는 것도 방법입니다.

MCP 도구가 너무 많으면 컨텍스트 윈도우를 잡아먹을 수 있어요. 이때 Tool Search 기능이 자동으로 활성화되어 도구 정의가 컨텍스트 윈도우의 10%를 넘으면 필요한 도구만 동적으로 로딩합니다. ENABLE_TOOL_SEARCH 환경 변수로 이 동작을 조절할 수 있고요.

서버 시작 시간이 오래 걸린다면 MCP_TIMEOUT 환경 변수로 타임아웃을 늘릴 수 있습니다.

MCP_TIMEOUT=10000 claude

Windows에서는 npx 서버를 실행할 때 cmd /c로 감싸야 합니다.

claude mcp add my-tool -- cmd /c npx -y @some/package

마치며

MCP 서버를 연결하면 클로드 코드는 단순한 코딩 도구를 넘어 GitHub, 데이터베이스, 모니터링 시스템, 브라우저까지 아우르는 통합 개발 환경이 됩니다. 자연어 한 마디로 이슈를 만들고 쿼리를 날리고 에러 로그를 분석하는 워크플로우는 한번 맛보면 이전으로 돌아가기 어려울 거예요.

처음 시작한다면 GitHub MCP 서버 하나만 연결해보세요. “열린 이슈 보여줘” 한 마디로 동작하는 걸 보면 다른 서버도 추가하고 싶어질 겁니다.

MCP(Model Context Protocol)의 전반적인 개념이 궁금하다면 그 글을, MCP 서버를 찾아서 쓰고 싶다면 MCP Registry 활용 가이드를, GitHub 연동을 더 깊이 파고 싶다면 GitHub MCP 서버 사용법을 참고해보세요.

클로드 코드의 다른 기능도 궁금하시다면 설정 가이드나 Hooks로 워크플로우 자동화하기도 살펴보세요.

This work is licensed under CC BY 4.0 CC BY

관련 포스트

Playwright MCP로 AI 에이전트에게 브라우저 자동화 맡기기

AI 코딩 에이전트를 쓰다 보면 "이 웹 페이지 좀 열어서 확인해줘"라고 말하고 싶을 때가 종종 있지 않나요? 배포한 사이트에 버그가 있는 것 같을 때, 특정 폼이 제대로 동작하는지 테스트하고 싶을 때, 혹은 경쟁사 사이트의 UI를 참고하고 싶을 때... 하지만 대부분의 AI 에이전트는 터미널 안에서만 동작하기 때문에 브라우저를 직접 다룰 수가 없습니다. 이 문제를 해결하는 것이 바로 Playwright MCP입니다. Microsoft에서 만든 이 MCP(Model Context Protocol) 서버를 AI 에이전트에 연결하면 브

클로드 코드 자동 메모리: AI가 스스로 배우고 기억하는 법

클로드 코드에는 두 가지 메모리 시스템이 있습니다. 개발자가 직접 작성하는 CLAUDE.md와 Claude가 스스로 학습하는 자동 메모리(auto memory)입니다. CLAUDE.md가 "이렇게 해"라는 명시적인 지시라면, 자동 메모리는 Claude가 작업하면서 "아, 이 프로젝트에서는 이렇게 하는구나"하고 스스로 메모하는 노트에 가깝습니다. | | CLAUDE.md | 자동 메모리 | | --- | --- | --- | | 작성 주체 | 개발자 | Claude | | 담는 내용 | 지시와 규칙 | 학습과 패턴 | | 적용 범위

클로드 코드 Tasks: 세션을 넘나드는 작업 관리

클로드 코드로 규모 있는 프로젝트를 진행하다 보면 한 세션에서 끝나지 않는 작업이 생기기 마련입니다. 인증 시스템을 추가하려면 DB 스키마부터 설계하고, API 엔드포인트를 만들고, 프론트엔드를 고치고, 테스트까지 작성해야 하죠. 문제는 이 과정에서 어디까지 했고 뭐가 남았는지 추적하기가 쉽지 않다는 겁니다. 🤔 예전에는 Claude Code가 내부적으로 Todo라는 간단한 체크리스트를 사용했는데요. 세션 메모리에만 존재해서 터미널을 닫거나 /clear를 하면 사라져 버렸습니다. 서브 에이전트도 메인 세션의 Todo를 볼 수 없었

Agent Skill 만들기: SKILL.md 작성 가이드

이전 글에서 Agent Skills가 무엇인지, 왜 필요한지 살펴보았습니다. 컨텍스트 파일이 "프로젝트 소개서"라면, Skills는 "업무 매뉴얼"이라고 했죠. 이번 글에서는 한 걸음 더 나아가 직접 Skill을 설계하고 SKILL.md로 작성하는 방법을 알아보겠습니다. 🛠️ 좋은 Skill의 조건 Skill을 만들기 전에 어떤 Skill이 잘 동작하는지 생각해 볼 필요가 있습니다. 가장 중요한 건 범위가 명확해야 한다는 점입니다. "웹 개발하기" 같은 광범위한 Skill보다는 "Next.js API 라우트 작성하기"처럼 구체적인