2026년 Claude Code MCP 설정: 통합 7가지와 단계별 설치

Ailoot 사용에 관한 추가 지침은 문서에서 확인할 수 있습니다.

MCP 서버란 무엇이며 Claude Code에 왜 필요할까요?#

Anthropic은 2024년 11월 25일 MCP를 개방형 표준으로 발표했습니다. 1년 만에 이 프로토콜은 업계 표준이 되었습니다. OpenAI, Google DeepMind, Microsoft가 이를 지원합니다. 공식 modelcontextprotocol/servers 저장소에는 MCP 프로젝트 자체의 참조 서버(Filesystem, Memory, Sequential Thinking, Fetch 등)가 들어 있습니다. GitHub, Notion, Stripe, Linear, Cloudflare, Sentry 같은 공급업체는 각자의 저장소에서 MCP 서버를 공개합니다. 커뮤니티 색인에는 수천 개의 서버가 등록되어 있습니다.

기술적으로 MCP는 JSON-RPC 2.0을 통해 작동합니다. 구조는 간단합니다. Claude Code는 클라이언트이고, 모든 서비스는 서버이며, 둘 사이의 MCP 서버는 세 가지 요소를 제공합니다. tools(AI가 호출할 수 있는 것), resources(AI가 읽을 수 있는 것), prompts(미리 만들어 둔 템플릿)입니다.

바이브 코딩을 하는 사람에게 이것이 중요한 이유는 다음과 같습니다. MCP가 없을 때는 Claude와 타사 서비스의 연결마다 별도의 통합과 자체 래퍼가 필요했습니다. MCP를 사용하면 Postgres, Slack, GitHub를 비슷한 명령 세 개로 연결할 수 있고, 서비스가 더 이상 필요하지 않을 때 연결을 끊기도 쉽습니다.

MCP는 Skills 및 Subagents와 어떻게 다를까요?#

차이를 기억하기 쉽게 표로 정리했습니다.

실용적으로 정리하면, 작업을 한 번 지정한 뒤 텍스트 형태로 반복한다면 skill입니다. AI가 외부 시스템에서 실시간 응답을 받아야 한다면 MCP입니다. 작업이 길고 여러 갈래로 나뉘며 별도의 두뇌가 필요하다면 subagent입니다.

두 가지 관련 방식에 대한 자세한 내용은 Claude Code Skills: 나만의 라이브러리 만들기와 Claude Code Subagents: 바로 쓸 수 있는 예시 5가지를 참고하세요.

Claude Code CLI MCP 설정: 5분 만에 첫 명령 실행#

공식 문서의 전체 구문:

claude mcp add <name> [options] -- <command> [args...]

세 가지 전송 방식이 지원됩니다. --transport stdio(기본값, 로컬 프로세스), --transport http(원격 HTTP), --transport sse(사용 중단 예정으로 표시됨. 서버가 아직 마이그레이션되지 않은 경우에만 사용)입니다.

--scope 플래그로 세 가지 범위를 지정할 수 있습니다.

• local — 현재 프로젝트 폴더에서만 사용(기본값).
• project — .mcp.json에 기록되고 저장소에 커밋되어 팀 전체에서 사용할 수 있음.
• user — 컴퓨터의 모든 프로젝트에서 전역으로 사용.

MCP 프로젝트의 참조 Filesystem 서버를 사용한 최소 예제입니다. 30초면 시작할 수 있습니다.

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem@2026.8.31 /Users/me/projects
claude mcp list

list를 실행한 뒤 명령에 지정한 폴더가 있으면 목록에 filesystem이 표시됩니다. 폴더가 없으면 서버가 시작되지 않습니다. 이 서버는 Claude Code의 작업 폴더, 즉 Claude Code를 실행한 폴더를 볼 수 있습니다. 왜 이런 현상이 생기고 이 서버가 실제로 유용한 경우가 언제인지는 아래 5.2절에서 설명합니다.

MCP가 연결되었는지 확인하려면 Claude Code 세션에서 /mcp를 실행하세요. 모든 서버와 상태, 도구 목록이 표시됩니다. Ailoot 사용에 관한 추가 지침은 문서에서 확인할 수 있습니다. 선택한 MCP 서버의 README에서 해당 서버의 명령을 확인하세요.

stdio와 HTTP 중 어떤 전송 방식을 선택해야 할까요?#

주요 기준별 비교:

간단한 기준은 이렇습니다. 디스크나 로컬 데이터베이스에 저장된 것은 stdio를 사용합니다. 클라우드에 있는 것은 HTTP를 사용합니다. SSE는 공식적으로 사용 중단 예정이므로 선택하지 마세요.

기업가를 위한 바로 쓸 수 있는 MCP 서버 7가지#

5.1. GitHub MCP — GitHub의 공식 서버

기능: Claude Code가 이슈, pull request, 저장소 파일, action 실행 내역에 접근할 수 있게 합니다. 이 서버는 오픈 소스이며 GitHub에서 별 30,000개가 넘는 관심을 받았습니다.

설치(HTTP, OAuth 사용):

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

OAuth 대신 PAT 토큰이 필요하면 Docker를 통한 stdio를 사용할 수도 있습니다.

예시: “bug 레이블이 붙은 미해결 이슈를 읽고, 컴포넌트별로 묶은 다음 어떤 순서로 해결할지 제안해 줘.” Claude는 GitHub MCP를 호출해 모든 이슈를 읽고 우선순위가 정해진 목록을 반환합니다.

저장소: github/github-mcp-server.

5.2. Filesystem MCP — MCP 프로젝트의 참조 서버

기능: 승인된 폴더 안의 컴퓨터 파일에 AI가 접근할 수 있게 합니다. MCP 프로젝트에서 직접 배포하며, npm 레지스트리는 Model Context Protocol a Series of LF Projects, LLC를 작성자로 표시합니다.

설치(stdio), 버전을 고정한 경우:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem@2026.8.31 /Users/me/projects

Claude Code가 연결되면 자신의 작업 폴더를 서버에 전달하며, 전달된 폴더는 명령에 지정한 모든 폴더를 대체합니다. Claude Code의 작업 폴더는 Claude Code를 실행한 폴더와 /add-dir 명령 또는 --add-dir 플래그로 추가한 폴더입니다. 명령을 통해 별도의 목업 폴더를 서버에 지정할 수는 없습니다. 명령에 지정한 폴더는 여전히 존재해야 하며, 그렇지 않으면 서버가 시작되지 않습니다.

따라서 Claude Code에서는 이 서버가 기본 제공 도구와 대부분 기능이 중복됩니다. 다른 폴더의 파일에 접근하려면 /add-dir만으로 충분합니다. 그러면 Claude Code 자체 도구로도 해당 폴더를 읽을 수 있습니다. 이 서버는 자체 파일 접근 기능이 없는 프로그램에서 더 유용합니다. Claude Desktop에서는 다른 문제가 발생할 수 있습니다. 도구 설명이 오래된 스키마 형식을 사용해 서버 도구가 거부될 수 있습니다. 이 문제는 아직 해결되지 않았습니다.

명령과 /add-dir 모두 실제로 필요한 폴더에만 접근 권한을 부여하세요. 디스크 루트에 접근 권한을 주지 마세요. 이것이 첫 번째 보안 취약점입니다.

예시: 먼저 /add-dir ~/Documents/design을 실행하고, 이어서 “~/Documents/design/landing-v3/의 목업을 모두 현재 프로젝트로 옮기고 hero-*.png 규칙에 따라 이름을 바꿔 줘.”라고 요청합니다.

5.3. Postgres MCP — DBHub (Bytebase)

기능: Claude를 Postgres, MySQL, SQL Server, MariaDB 또는 SQLite에 연결합니다. 읽기 전용 모드를 지원하므로 AI 에이전트가 명령 한 번으로 데이터베이스를 삭제할 수 없습니다. Anthropic의 보관 처리된 참조 서버 server-postgres를 대체하는 용도로 자주 사용됩니다.

설치(HTTP, 읽기 전용):

claude mcp add postgres -- npx -y @bytebase/dbhub --dsn "postgresql://user:pass@localhost:5432/mydb?sslmode=disable" --readonly

프로덕션 데이터베이스에는 항상 읽기 전용 권한이 있는 별도의 사용자를 사용하고 VIEW 또는 중간 API 경로를 통해 개인 데이터를 익명화하세요. 쓰기 권한으로 프로덕션 데이터베이스에 연결하지 마세요.

예시: “지난 한 달 동안 구독 상태가 expired였던 고객을 조회하고, 총 결제 금액 기준 상위 20명을 나열해 줘.”

저장소: bytebase/dbhub.

5.4. Slack MCP — 팀 커뮤니케이션

기능: Claude가 Slack 채널을 읽고 메시지를 보낼 수 있게 합니다. 자동화에 유용합니다. “빌드가 통과하면 #releases에 게시해 줘.”, “#engineering에서 주간 요약을 작성해 줘.”와 같이 사용할 수 있습니다.

설치(npx 래퍼를 통한 stdio. 예: @modelcontextprotocol/server-slack 또는 공급업체의 동등한 도구):

claude mcp add slack \
  -e SLACK_BOT_TOKEN=xoxb-... \
  -e SLACK_TEAM_ID=T0... \
  -- npx -y @modelcontextprotocol/server-slack

인증에는 Slack Bot Token을 사용하며, 접근 권한은 Slack 측의 scope로 제한됩니다. AI에 chat:read와 chat:write:user만 부여하면 작업 공간 설정은 수정할 수 없습니다. 생태계가 빠르게 바뀌므로 선택한 서버의 README에서 최신 명령을 확인하세요.

예시: “매일 오전 9:00에 어제 병합된 PR 목록을 #daily에 보내 줘.”

5.5. Notion MCP — 지식 베이스

기능: Claude가 Notion 페이지와 데이터베이스에 접근할 수 있게 합니다. 프로젝트 밖에 두는 지식 베이스입니다. 그곳에 메모, 고객 목록 또는 편집 정책을 보관하면 AI가 읽을 수 있습니다.

설치(HTTP, OAuth 사용):

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

Anthropic 공식 @makenotion/claude-code-notion-plugin 플러그인을 사용할 수도 있습니다.

예시: “Notion 데이터베이스 ‘Customers’에서 상태가 ‘active’이고 2주 넘게 통화하지 않은 사람을 모두 찾아 줘. 각 사람에게 보낼 이메일 초안을 작성해 줘.”

Notion 가이드: developers.notion.com/guides/mcp.

5.6. Sentry MCP — 오류 추적

기능: Claude를 프로덕션 시스템의 오류에 연결합니다. 페이지에서 500 오류가 발생하면 “프로젝트의 Sentry에서 최신 이슈 10개를 보여 주고 각 이슈의 근본 원인을 설명해 줘.”라고 요청해 즉시 분석을 받을 수 있습니다.

설치(HTTP):

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

인증은 Sentry OAuth를 사용합니다. 접근 권한을 특정 프로젝트로 제한할 수 있습니다.

예시: “지난 24시간 동안 가장 자주 발생한 이슈 세 개를 골라 줘. 무슨 일이 있었는지 쉬운 말로 설명하고 해결 방법을 제안해 줘.”

저장소: getsentry/sentry-mcp.

5.7. Playwright MCP — 브라우저 작업 흐름

기능: Claude가 브라우저를 사용할 수 있게 합니다. AI는 페이지를 열고, 클릭하고, 양식을 작성하고, 스크린샷을 찍을 수 있습니다. UI 확인, 게시 후 수동 테스트, 작업 흐름 분석에 유용합니다.

설치(stdio):

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

2026년 5월 7일에 출시된 버전 v0.0.75는 Microsoft가 활발히 유지 관리하고 있습니다(별 32,000개 이상).

예시: “우리 웹사이트의 홈 페이지를 열고 모든 카드가 제대로 표시되는지 확인한 다음 데스크톱과 모바일에서 스크린샷을 찍어 줘.”

저장소: microsoft/playwright-mcp.

선택한 Playwright MCP 버전의 README에서 버전을 고정한 명령, 여러 세션을 동시에 사용하는 플래그, 흔한 설치 오류를 확인하세요.

PreToolUse hook으로 보안을 제어하는 방법#

SQL 접두사 차단 목록은 읽기 전용 권한 경계가 아닙니다. 소문자, 주석, UPDATE, INSERT, ALTER, 여러 문장, 부작용 함수는 세 대문자 접두사로 처리되지 않습니다. 별도의 읽기 전용 권한 계정을 사용하고 일회용 데이터베이스에서 권한을 검증하세요. hook은 추가 제어입니다.

다음은 좁은 격리 예시입니다. 구체적인 정책을 검토·시험하기 전까지 세 MCP 서버 계열의 모든 호출을 거부하며 읽기도 차단합니다. 실제 서버·도구 이름에 맞추세요. 이름을 바꾼 서버, 기본 Bash, 다른 커넥터는 범위 밖입니다.

.claude/settings.json에 별도 규칙을 넣으세요.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__postgres__.*",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/deny-unapproved-mcp.sh\""
          }
        ]
      },
      {
        "matcher": "mcp__slack__.*",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/deny-unapproved-mcp.sh\""
          }
        ]
      },
      {
        "matcher": "mcp__filesystem__.*",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/deny-unapproved-mcp.sh\""
          }
        ]
      }
    ]
  }
}

.claude/hooks/deny-unapproved-mcp.sh에 아래 스크립트를 저장하세요. 예전 최상위 decision: approve/block 대신 공식 PreToolUse 결정 계약을 반환합니다.

#!/bin/bash
printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"This MCP server family is quarantined pending a reviewed policy."}}'

SQL을 파싱하거나 분류하지 않고 일치한 호출을 항상 거부합니다. 중요한 데이터를 연결하기 전 격리 세션에서 SELECT 1, 소문자 delete, 주석으로 시작하는 UPDATE, Slack 읽기·전송, Filesystem의 .env 읽기가 이름 일치 시 모두 거부되는지 확인하세요. 다른 서버 계열은 범위 밖으로 남는지도 명시적으로 확인하세요.

읽기 전용 DB 작업에는 검증된 권한을 쓰고 실제 도구의 검토된 정책으로 격리를 대체하세요. Slack 읽기 전용 작업에는 전송 권한 없는 자격 증명을, 파일에는 서버 허용 루트와 프로세스 파일 권한을 쓰세요. 다른 도구, 셸, 첨부 프롬프트, 에이전트가 바꿀 수 있는 정책 파일을 통한 접근까지 막는다고 주장하지 마세요.

비슷한 “실행 전 확인” 로직은 Claude Code의 Plan Mode 가이드에서 더 자세히 다룹니다.

Claude Code MCP 설정 파일: .mcp.json과 도구 로딩 관리#

Claude Code 문서에 따르면 이 기능은 이제 기본적으로 활성화되어 있어 수동으로 켤 필요가 없습니다.

Claude Code가 모든 도구를 즉시 불러오는 예외 상황은 다음과 같습니다. 타사 프록시를 통해 작업할 때(ANTHROPIC_BASE_URL이 Anthropic 주소가 아닌 주소로 설정된 경우), Google Cloud에서 4.5 세대보다 오래된 모델을 사용할 때, Azure의 Microsoft Foundry 배포를 사용할 때입니다. ENABLE_TOOL_SEARCH 변수는 작동 방식을 변경합니다.

• 설정되지 않음 — 모든 MCP 도구를 미루고 필요할 때 불러옴.
• true — 같은 방식으로 작동하며, Claude Code가 프록시를 통해 검색을 활성화하려고 시도함.
• auto — 임계값 모드: 모든 도구 설명이 컨텍스트 창의 10% 미만을 차지하는 동안에는 즉시 불러오고, 그 이상이면 미룸.
• auto:N — 같은 방식으로 작동하지만 사용자 지정 비율 임계값을 사용함. 예: auto:5.
• false — 이전 동작으로, 모든 도구를 즉시 컨텍스트에 넣음.

항상 표시되어야 하는 중요 도구에는 서버 설명 옆의 .mcp.json에서 alwaysLoad: true 플래그를 사용할 수 있습니다. 이 설정을 적용한 도구는 처음부터 컨텍스트 공간을 차지하므로 Claude가 거의 모든 응답에서 필요로 하는 도구에만 사용하세요.

MCP 서버가 5개 이상이고 Claude가 어떤 도구를 호출해야 할지 혼란스러워한다면, 먼저 검색이 비활성화되어 있는지 확인하세요. 설정에서 ENABLE_TOOL_SEARCH=false를 찾고 프록시를 사용하고 있는지 확인합니다.

/compact로 컨텍스트 줄이기도 도움이 될 수 있습니다.

MCP가 필요하지 않은 경우: Skill, Subagent 또는 CLI가 더 나을까요?#

토큰 비용과 복잡도에 따른 순서:

1. Bash를 통한 CLI 명령 — 거의 무료입니다. AI가 gh pr list, psql -c 또는 curl을 실행하고 일반 터미널 사용자와 같은 응답을 받습니다.
2. Skill — 저렴합니다. 무엇을 호출하고 결과를 어떻게 처리할지에 관한 지침이 들어 있는 미리 만들어 둔 프롬프트 템플릿입니다. 폴더 이름의 트리거에 따라 불러옵니다.
3. Subagent — 보통입니다. 자체 토큰 세션을 사용하는 별도의 컨텍스트로, 긴 작업을 처리합니다.
4. MCP server — 비쌉니다. 컨텍스트에는 도구 이름만 남지만 Claude가 호출 전에 도구를 찾아내면 도구 설명을 불러옵니다. 서비스 응답은 길 수 있습니다. 도구 응답이 10,000 토큰을 넘으면 Claude Code가 경고합니다. HTTP의 경우 OAuth 세션도 필요합니다.

직관에 반하는 조언일 수 있지만, 웹 페이지 분석, git 작업, PDF 열기, 오픈 소스 유틸리티 사용에는 MCP가 아니라 CLI를 선택하세요. AI는 사람처럼 터미널 명령을 실행할 수 있으며 도구 설명이나 서버 오버헤드 없이 명령과 응답에 대해서만 토큰을 사용합니다.

다음 두 가지 경우에는 MCP가 적합합니다.

• 서비스가 폐쇄형인 경우: Slack, Notion, Sentry, Linear. CLI 도구도 있지만 MCP는 OAuth와 scope 제어를 통해 더 세밀하게 접근할 수 있습니다.
• 실시간 양방향 대화가 필요한 경우: AI가 Postgres에 연결해 스키마를 확인하고, 후속 쿼리를 요청하고, 데이터를 받은 다음 다음 단계를 수행합니다. CLI를 사용한다면 수동 명령 10개가 필요할 작업입니다.

MCP 연결 시 피해야 할 실수 6가지#

1. MCP 서버 수집벽. “혹시 몰라서” 서버 10개를 연결했습니다. Claude는 어떤 도구를 호출할지 헷갈리고 서버 응답은 컨텍스트를 가득 채웁니다. 해결책: 현재 프로젝트에 필요한 서버 3–5개만 남기고 claude mcp remove로 나머지를 제거하세요.

2. 프로덕션 데이터베이스에 쓰기 권한 부여. --readonly, 별도 사용자 또는 허용 목록 hook 없이 Postgres MCP를 프로덕션 데이터베이스에 연결했습니다. “테스트 레코드를 삭제해 줘”라는 프롬프트 하나면 프로덕션 데이터가 삭제됩니다. 해결책: 검증된 읽기 전용 권한의 별도 역할, 해당되는 서버 읽기 전용 모드, 시험한 도구 호출 제어를 사용하세요. DROP|TRUNCATE|DELETE 접두사 목록은 충분한 권한 제어가 아닙니다.

3. 익명화하지 않은 개인정보. 고객 이메일, 전화번호, 여권 정보가 든 데이터베이스를 직접 연결했습니다. Claude가 데이터를 보고, 그 데이터는 Anthropic 로그에 남습니다. 해결책: VIEW 또는 중간 API 경로를 사용해 j***@gmail.com처럼 마스킹된 데이터를 반환하세요.

4. skill 대신 MCP 사용. “X 형식으로 영업 보고서 작성하기”처럼 미리 만든 프롬프트가 있는 skill로 해결할 수 있는 반복 작업이 필요합니다. MCP 서버를 만들지 마세요.

5. 오픈 소스 CLI 대신 MCP 사용. PDF를 텍스트로 변환해야 합니다. pdftotext가 있습니다. “PDF MCP”를 만들지 마세요. 토큰만 낭비합니다.

6. 토큰 비용을 추적하지 않음. claude mcp list에서 연결된 서버는 볼 수 있지만 대화마다 얼마나 사용하는지는 모릅니다. 일주일이 지난 뒤에야 “MCP가 컨텍스트의 40%를 소모했고 그동안 계속 비용을 내고 있었네”라는 사실을 알게 됩니다. 해결책: 사용하지 않는 서버를 주기적으로 비활성화하고 Claude Code 사용량 한도 추적으로 사용량이 어떻게 변하는지 확인하세요.

MCP 연결 실패 문제를 해결하는 방법#

단계별 체크리스트:

1. 목록에 서버가 표시되나요?

   claude mcp list
   

   표시되지 않는다면 claude mcp add가 완료되지 않은 것입니다. 가장 흔한 원인은 --scope입니다. local 범위에 추가한 뒤 다른 프로젝트에서 확인하고 있을 수 있습니다.

2. 서버 상태가 녹색인가요?

   claude mcp status <name>
   

   빨간색은 프로세스가 시작되지 않았거나(stdio), 서버가 응답하지 않았다는 뜻입니다(HTTP).

3. 서버 로그에 유용한 내용이 있나요?

   claude mcp logs <name>
   

   스택 추적이 보이면 대개 패키지 문제입니다(npx가 패키지를 찾지 못했거나 Node 버전이 20 미만인 경우).

4. OAuth 콜백이 돌아오지 않나요? 대개 --callback-port 또는 네트워크 필터가 원인입니다. 특정 포트를 전달하세요.

   claude mcp add --transport http --callback-port 8765 [name] [url]
   

5. 도구 이름이 충돌하나요? 두 서버가 같은 이름의 도구를 제공하면 Claude가 잘못된 도구를 호출할 수 있습니다. Tool Search를 사용하거나(앞의 H2 참조) claude mcp remove로 추가 서버를 수동으로 제거하세요.

6. claude.ai 확장 프로그램(connector)이 보이지 않나요? 알려진 문제입니다. claude.ai 웹 인터페이스의 확장 프로그램(connector)은 API 키를 사용하는 Claude Code에서 사용할 수 없습니다. 해결책: 웹 인터페이스가 아니라 CLI를 통해 MCP를 연결하세요.

다음 단계: OAuth, 나만의 MCP 서버, Plugin Marketplace#

Plugin Marketplace는 설치 명령을 기억하고 싶지 않은 사용자에게 편리합니다. 한 패키지 안에 여러 서버를 설명하는 .claude-plugin/marketplace.json 매니페스트 형식을 사용합니다.

Marketplace에서 플러그인을 설치합니다.

claude plugin install <plugin-name>

플러그인 하나에 여러 MCP 서버, skill, subagent가 함께 들어갈 수 있습니다. 전자상거래, 마케팅, 법무 부서 등 특정 상황에 맞춘 패키지형 설정입니다.

modelcontextprotocol.io 사양에 따라 자체 MCP 서버를 작성하세요. 최소 템플릿은 Anthropic의 Python 또는 TypeScript SDK를 사용합니다. 그런 다음 도구를 설명하고 전송 방식을 연결합니다. FastAPI로 REST API를 작성하는 것과 비슷한 수준의 복잡도입니다.

프로젝트에 이미 설정된 CLAUDE.md가 있고 context engineering을 이해하고 있다면 자체 MCP를 추가하는 데 하루가 걸립니다. 그렇지 않다면 먼저 기본부터 익히는 편이 좋습니다.

모델 작업을 계속하려면 Ailoot으로 이동하세요.