[Claude Code MCP 서버 연동] 실전 튜토리얼 — 처음부터 배포까지

 

안녕하세요!

재아군의 관찰인생입니다.

 

오늘은 개발자들 사이에서 뜨거운 관심을 받고 있는 Claude Code MCP 서버 연동에 대해 처음부터 배포까지 실전 튜토리얼을 준비했습니다.

AI 코딩 어시스턴트가 외부 도구와 직접 소통할 수 있게 해주는 이 기술, 어떻게 활용하면 좋을지 함께 알아보겠습니다.

 

 

---

 

1. Claude Code MCP 서버 연동이란 무엇인가?

 

MCP(Model Context Protocol)는 Anthropic이 2024년 11월에 공개한 오픈 프로토콜로, AI 모델이 외부 데이터 소스와 도구에 표준화된 방식으로 접근할 수 있게 해주는 통신 규격입니다.

Claude Code에서 MCP 서버를 연동한다는 것은, Claude가 단순히 코드를 생성하는 것을 넘어 데이터베이스 조회, API 호출, 파일 시스템 접근, 외부 서비스 제어 등을 직접 수행할 수 있게 된다는 의미입니다.

 

등장 배경

 

LLM 기반 코딩 도구가 빠르게 발전하면서, 개발자들은 AI가 코드만 생성하는 것이 아니라 실제 개발 워크플로우에 깊이 통합되기를 원했습니다.

기존에는 AI에게 "이 데이터베이스에서 사용자 목록을 조회해줘"라고 요청하면, AI가 SQL 쿼리 코드를 생성해줄 뿐 실제 실행은 개발자가 직접 해야 했습니다.

MCP는 이 간극을 메워줍니다.

 

기존 방식의 4가지 한계

 

문제	구체적 상황
컨텍스트 단절	AI가 프로젝트의 DB 스키마, API 스펙 등 실시간 정보에 접근할 수 없어 부정확한 코드를 생성하는 경우가 빈번했습니다
수동 브릿지 작업	개발자가 AI 출력을 복사해서 터미널에 붙여넣고, 결과를 다시 AI에게 전달하는 반복 작업이 필요했습니다
도구별 커스텀 통합	각 외부 도구마다 별도의 플러그인이나 API 래퍼를 만들어야 했고, 유지보수 비용이 기하급수적으로 증가했습니다
보안 및 권한 관리 부재	AI가 외부 시스템에 접근할 때 표준화된 인증/인가 체계가 없어 보안 사고 위험이 높았습니다

 

Claude Code MCP 서버 연동은 이러한 문제들을 단일 프로토콜로 해결합니다.

JSON-RPC 2.0 기반의 표준 통신 규격을 통해 어떤 도구든 동일한 방식으로 연결할 수 있게 된 것입니다.

 

 

---

 

2. 핵심 특징 & 기능 분석

 

1. 표준화된 프로토콜 기반 통신

 

MCP는 JSON-RPC 2.0 위에 구축된 프로토콜로, 클라이언트(Claude Code)와 서버(외부 도구) 간의 통신을 표준화합니다.

이는 REST API처럼 각 서비스마다 다른 인터페이스를 학습할 필요 없이, 하나의 규격만 알면 모든 MCP 서버와 통신할 수 있다는 의미입니다.

전송 계층으로는 stdio(로컬 프로세스)와 HTTP with SSE(원격 서버) 두 가지를 지원합니다.

 

2. 세 가지 핵심 프리미티브

 

MCP 서버는 세 가지 유형의 기능을 노출할 수 있습니다.

 

• Tools: AI가 호출할 수 있는 함수입니다. 데이터베이스 쿼리 실행, 파일 생성, API 호출 등 실제 액션을 수행합니다.
• Resources: 읽기 전용 데이터 소스입니다. 파일 내용, DB 스키마, 설정 정보 등을 AI에게 컨텍스트로 제공합니다.
• Prompts: 재사용 가능한 프롬프트 템플릿입니다. 특정 작업에 최적화된 지시사항을 서버 측에서 정의할 수 있습니다.

 

3. 동적 도구 발견(Dynamic Tool Discovery)

 

Claude Code는 MCP 서버에 연결하면 해당 서버가 제공하는 도구 목록을 자동으로 발견합니다.

개발자가 새로운 도구를 MCP 서버에 추가하면 Claude Code가 즉시 해당 도구를 인식하고 사용할 수 있게 됩니다.

별도의 플러그인 설치나 재시작이 필요하지 않습니다.

 

4. 세분화된 권한 제어

 

MCP 연동 시 각 도구별로 권한을 세밀하게 제어할 수 있습니다.

Claude Code의 설정 파일(settings.json)에서 특정 MCP 서버의 특정 도구만 자동 허용하거나, 매번 사용자 승인을 요구하도록 설정할 수 있습니다.

이를 통해 읽기 전용 도구는 자동 허용하고, 데이터 변경 도구는 승인 필수로 운영하는 등 실무에 적합한 보안 정책을 구현할 수 있습니다.

 

5. 다중 서버 동시 연결

 

Claude Code는 여러 MCP 서버를 동시에 연결할 수 있습니다.

예를 들어, PostgreSQL MCP 서버로 DB를 조회하면서 동시에 GitHub MCP 서버로 이슈를 관리하고, Slack MCP 서버로 팀에 알림을 보내는 것이 가능합니다.

각 서버는 독립적으로 동작하며, Claude Code가 작업 맥락에 따라 적절한 서버의 도구를 자동으로 선택합니다.

 

 

---

 

3. 기술 아키텍처 & 동작 원리

 

구성 요소

 

구성 요소	역할	기술 스택
MCP Host	Claude Code 애플리케이션 자체. MCP 클라이언트를 관리하고 AI 모델과의 인터페이스를 제공합니다	Node.js 런타임
MCP Client	호스트 내부에서 MCP 서버와 1:1 연결을 유지하는 프로토콜 클라이언트입니다	JSON-RPC 2.0
MCP Server	외부 도구/데이터를 MCP 프로토콜로 노출하는 경량 서버입니다	TypeScript/Python SDK
Transport Layer	클라이언트-서버 간 실제 통신 채널입니다. stdio 또는 Streamable HTTP를 사용합니다	stdio / HTTP+SSE

 

동작 흐름

 

실제 MCP 서버가 요청을 처리하는 과정을 코드로 살펴보겠습니다.

 

// MCP 서버 구현 예시 — PostgreSQL 쿼리 도구
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import pg from "pg";

const server = new McpServer({
  name: "postgres-mcp",
  version: "1.0.0",
});

const pool = new pg.Pool({
  connectionString: process.env.DATABASE_URL,
});

// Tool 정의: 읽기 전용 SQL 쿼리 실행
server.tool(
  "query",
  "PostgreSQL 데이터베이스에 읽기 전용 쿼리를 실행합니다",
  {
    sql: z.string().describe("실행할 SELECT 쿼리"),
  },
  async ({ sql }) => {
    // 안전성 검증: SELECT만 허용
    if (!/^\s*SELECT/i.test(sql)) {
      return {
        content: [{ type: "text", text: "오류: SELECT 쿼리만 허용됩니다." }],
        isError: true,
      };
    }

    const result = await pool.query(sql);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result.rows, null, 2),
        },
      ],
    };
  }
);

// Resource 정의: DB 스키마 정보 제공
server.resource(
  "schema",
  "postgres://schema/public",
  async (uri) => {
    const result = await pool.query(`
      SELECT table_name, column_name, data_type
      FROM information_schema.columns
      WHERE table_schema = 'public'
      ORDER BY table_name, ordinal_position
    `);
    return {
      contents: [{
        uri: uri.href,
        mimeType: "application/json",
        text: JSON.stringify(result.rows, null, 2),
      }],
    };
  }
);

// 서버 시작
const transport = new StdioServerTransport();
await server.connect(transport);

 

통신 흐름 요약

 

사용자 → Claude Code → MCP Client → [JSON-RPC 2.0] → MCP Server → 외부 시스템
                                                                      ↓
사용자 ← Claude Code ← MCP Client ← [JSON-RPC 2.0] ← MCP Server ← 응답 반환

 

1. 사용자가 Claude Code에 자연어로 요청합니다
2. Claude Code(AI 모델)가 요청을 분석하고 적절한 MCP 도구를 선택합니다
3. MCP Client가 JSON-RPC 2.0 형식으로 요청을 직렬화하여 서버에 전송합니다
4. MCP Server가 요청을 역직렬화하고 실제 외부 시스템 작업을 수행합니다
5. 결과가 역순으로 전달되어 사용자에게 자연어로 표시됩니다

 

설계 원칙 4가지

 

1. 최소 권한 원칙: 각 MCP 서버는 필요한 최소한의 시스템 접근 권한만 가집니다. DB 조회 서버는 읽기 권한만, 파일 관리 서버는 지정된 디렉토리만 접근합니다.
2. 무상태 프로토콜: 각 요청은 독립적으로 처리됩니다. 서버 장애 시 다른 서버에 영향을 주지 않으며, 수평 확장이 용이합니다.
3. 스키마 우선 설계: 모든 도구의 입출력이 JSON Schema로 명확히 정의됩니다. Zod 등의 스키마 라이브러리를 활용하여 런타임 검증도 자동화됩니다.
4. 점진적 복잡도: 단순한 stdio 연결부터 시작해서 원격 HTTP 서버까지, 필요에 따라 복잡도를 높여갈 수 있는 구조입니다.

 

---

 

4. 실무 활용 가이드

 

시작하기: 첫 MCP 서버 연결

 

Claude Code에서 MCP 서버를 추가하는 방법은 매우 간단합니다.

터미널에서 한 줄 명령으로 설정할 수 있습니다.

 

# 1. 로컬 MCP 서버 추가 (stdio 방식)
claude mcp add postgres-local -s project -- npx -y @anthropic/postgres-mcp

# 2. 원격 MCP 서버 추가 (HTTP 방식)
claude mcp add my-api --transport http https://api.example.com/mcp

# 3. 환경변수를 포함한 서버 추가
claude mcp add github -s user -e GITHUB_TOKEN=ghp_xxxx -- npx -y @modelcontextprotocol/server-github

# 4. 등록된 MCP 서버 확인
claude mcp list

# 5. MCP 서버 제거
claude mcp remove postgres-local

 

-s 플래그는 스코프를 지정합니다. project는 현재 프로젝트에만, user는 전역으로 적용됩니다.

프로젝트 스코프로 추가하면 .claude/settings.json에, 유저 스코프로 추가하면 ~/.claude/settings.json에 설정이 저장됩니다.

 

설정 파일의 실제 형태는 다음과 같습니다:

 

{
  "mcpServers": {
    "postgres-local": {
      "command": "npx",
      "args": ["-y", "@anthropic/postgres-mcp"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    },
    "my-api": {
      "type": "http",
      "url": "https://api.example.com/mcp"
    }
  }
}

 

기존 환경에 MCP 도입 4단계

 

단계	작업	소요 시간	산출물
1단계: 도구 식별	팀이 자주 수동으로 수행하는 반복 작업을 목록화합니다 (DB 조회, 로그 확인, 배포 상태 체크 등)	1~2시간	자동화 대상 목록
2단계: 서버 구현	MCP SDK를 사용하여 식별된 도구를 MCP 서버로 래핑합니다. 공식 서버가 있으면 그대로 활용합니다	2~4시간	MCP 서버 코드
3단계: 권한 설정	각 도구별 실행 권한을 설정합니다. 읽기 전용은 자동 허용, 쓰기 작업은 승인 필수로 분류합니다	30분	settings.json 설정
4단계: 팀 배포	.claude/settings.json을 Git에 커밋하여 팀 전체가 동일한 MCP 설정을 공유합니다	15분	공유된 MCP 설정

 

팀 활용 팁

 

프로젝트 스코프 vs 유저 스코프 전략이 중요합니다.

프로젝트 공통 도구(해당 프로젝트의 DB, 해당 프로젝트의 배포 도구)는 프로젝트 스코프(-s project)로 등록하여 .claude/settings.json에 저장하고 Git으로 공유합니다.

개인 도구(개인 GitHub 토큰이 필요한 서버, 개인 노트 서버 등)는 유저 스코프(-s user)로 등록합니다.

 

또한 .claude/settings.json에서 특정 MCP 도구의 자동 허용을 설정할 수 있습니다:

 

{
  "permissions": {
    "allow": [
      "mcp__postgres-local__query",
      "mcp__github__list_issues"
    ],
    "deny": [
      "mcp__postgres-local__execute"
    ]
  }
}

 

이렇게 하면 query 도구는 매번 승인 없이 자동 실행되고, execute 도구는 항상 차단됩니다.

 

---

 

5. 경쟁 기술 비교 분석

 

비교 항목	Claude Code + MCP	GitHub Copilot Extensions	Cursor Tool Use	Continue.dev + OpenAI
프로토콜	MCP (JSON-RPC 2.0 표준)	GitHub 독자 규격	독자 규격 (내장 도구)	OpenAI Function Calling
서버 구현 언어	TypeScript, Python, Java, C# 등 다양	GitHub App 기반 (제한적)	내장 도구만 지원	커스텀 백엔드 필요
커뮤니티 서버	1,000+ 공식/커뮤니티 서버 (2025년 기준)	GitHub Marketplace 의존	해당 없음	제한적
전송 방식	stdio + Streamable HTTP	HTTPS Webhook	프로세스 내부	HTTPS API
권한 제어	도구 단위 세분화 가능	OAuth 스코프 단위	에디터 설정 수준	API 키 단위
오프라인 사용	stdio 서버는 완전 로컬 동작	클라우드 의존	부분 가능	클라우드 의존
멀티 서버	무제한 동시 연결	단일 Extension 단위	해당 없음	커스텀 구현 필요
오픈소스	프로토콜 및 SDK 모두 오픈소스	부분 오픈소스	비공개	SDK만 오픈소스

 

선택 가이드

 

• Claude Code + MCP를 선택해야 하는 경우: 다양한 외부 시스템을 AI 워크플로우에 통합해야 하며, 표준화된 프로토콜과 활발한 오픈소스 생태계가 중요한 팀
• GitHub Copilot Extensions: GitHub 생태계에 깊이 의존하고, GitHub 내부 워크플로우 자동화가 주 목적인 팀
• Cursor Tool Use: 코드 에디터 내 AI 지원이 핵심이고, 외부 도구 연동보다는 코드 생성 품질이 우선인 개인 개발자
• Continue.dev + OpenAI: OpenAI 모델을 선호하며, 자체 백엔드 인프라를 구축할 역량이 있는 팀

 

특히 MCP의 가장 큰 강점은 벤더 중립성입니다.

MCP 서버를 한 번 구현하면 Claude Code뿐 아니라 MCP를 지원하는 모든 클라이언트(Zed, Sourcegraph Cody, Windsurf 등)에서 재사용할 수 있습니다.

 

---

 

6. 도입 시 베스트 프랙티스

 

5가지 핵심 원칙

 

1. 최소 도구 원칙으로 시작하세요

 

처음부터 모든 시스템을 MCP로 연결하려 하지 마세요.

가장 자주 수동으로 수행하는 작업 1~2개부터 시작합니다.

예를 들어 "매번 DB에서 사용자 정보를 확인하는 작업"이나 "배포 상태를 체크하는 작업"처럼 하루에 수십 번 반복하는 것부터 자동화하면 즉각적인 효과를 체감할 수 있습니다.

 

2. 읽기와 쓰기를 분리하세요

 

하나의 MCP 서버에 읽기와 쓰기 도구를 모두 넣더라도, 권한 설정에서 반드시 분리해야 합니다.

읽기 도구(query, list, get)는 자동 허용으로, 쓰기 도구(create, update, delete)는 매번 승인으로 설정하는 것이 안전합니다.

 

3. 환경변수로 시크릿을 관리하세요

 

MCP 서버 설정에 API 키나 비밀번호를 직접 입력하지 마세요.

반드시 env 필드를 통해 환경변수로 주입하고, .claude/settings.json에는 환경변수 이름만 기록합니다.

 

4. 프로젝트 CLAUDE.md에 MCP 사용법을 문서화하세요

 

Claude Code는 CLAUDE.md 파일을 매 세션 시작 시 읽습니다.

여기에 "DB 조회가 필요하면 postgres-local MCP 서버의 query 도구를 사용하세요" 같은 가이드를 작성하면, Claude가 더 정확하게 도구를 선택합니다.

 

5. 에러 메시지를 상세하게 반환하세요

 

MCP 서버에서 에러가 발생하면 isError: true와 함께 구체적인 에러 메시지를 반환해야 합니다.

Claude Code는 이 에러 메시지를 바탕으로 사용자에게 수정 방안을 제안하므로, "쿼리 실패"보다는 "테이블 users가 존재하지 않습니다. public 스키마에서 사용 가능한 테이블: accounts, profiles"처럼 상세한 컨텍스트를 제공하세요.

 

흔한 실수와 해결 방법

 

실수	증상	해결 방법
npx 경로 미설정	"command not found" 에러	MCP 서버 설정에서 command를 npx 절대 경로(/usr/local/bin/npx)로 지정하거나, Claude Code 실행 전 Node.js PATH를 확인합니다
환경변수 누락	서버 시작 후 인증 실패	env 필드에 필요한 환경변수가 모두 포함되어 있는지 확인합니다. claude mcp list로 현재 설정을 점검합니다
stdio 서버 stdout 오염	JSON 파싱 에러 발생	MCP 서버 코드에서 console.log를 사용하면 stdout이 오염됩니다. 디버깅 출력은 반드시 console.error(stderr)로 보내세요
도구 스키마 미정의	Claude가 도구를 발견하지 못함	모든 도구의 입력 파라미터를 Zod 스키마로 명확히 정의해야 합니다. 설명(description)도 상세하게 작성해야 Claude가 적절한 시점에 도구를 선택합니다
타임아웃 미설정	느린 외부 API 호출 시 무응답	MCP 서버 내부에서 외부 API 호출 시 반드시 타임아웃을 설정하세요. 기본 60초 제한을 초과하면 연결이 끊어집니다

 

---

 

7. 향후 전망 & 발전 방향

 

발전 방향 4가지

 

1. 원격 MCP 서버의 보편화

 

현재 대부분의 MCP 서버는 로컬 stdio 방식으로 동작하지만, Streamable HTTP 전송 방식이 표준으로 자리잡으면서 클라우드 호스팅 MCP 서버가 급증할 전망입니다.

SaaS 서비스들이 자사 API와 함께 MCP 엔드포인트를 기본 제공하는 시대가 오고 있습니다.

Cloudflare, Sentry, Stripe 등이 이미 공식 MCP 서버를 제공하고 있으며 이 추세는 가속화될 것입니다.

 

2. OAuth 2.1 기반 인증 표준화

 

MCP 프로토콜의 인증 계층이 OAuth 2.1로 표준화되고 있습니다.

이를 통해 원격 MCP 서버에 안전하게 인증하고, 토큰 갱신과 권한 범위 제어가 프로토콜 수준에서 처리됩니다.

기업 환경에서의 도입 장벽이 크게 낮아질 것입니다.

 

3. 에이전트 간 MCP 통신

 

Claude Code의 서브에이전트들이 MCP를 통해 서로 통신하는 멀티 에이전트 아키텍처가 발전하고 있습니다.

예를 들어, 코드 분석 에이전트가 MCP를 통해 테스트 실행 에이전트에게 특정 테스트를 요청하고, 그 결과를 바탕으로 코드를 수정하는 자율적 워크플로우가 가능해집니다.

 

4. MCP 서버 마켓플레이스

 

npm이나 PyPI처럼 MCP 서버를 검색하고 설치할 수 있는 중앙 레지스트리가 형성되고 있습니다. claude mcp add로 검증된 커뮤니티 서버를 한 줄로 추가하는 경험이 더욱 매끄러워질 것입니다.

 

개발자에게 주는 시사점

 

MCP는 단순한 도구 연동 프로토콜을 넘어, AI 네이티브 개발 환경의 인프라로 자리잡고 있습니다.

지금 MCP 서버를 구현하는 능력을 갖추는 것은, 2010년대 초반에 REST API 설계를 익히는 것과 비슷한 의미를 가집니다.

AI가 개발자의 도구를 직접 사용하는 시대에, 그 연결 통로를 만드는 기술은 앞으로 몇 년간 핵심 역량이 될 것입니다.

 

---

 

마무리

 

지금까지 Claude Code MCP 서버 연동에 대해 깊이 있게 살펴보았습니다.

핵심을 정리하면 다음과 같습니다.

 

• MCP는 AI와 외부 도구 사이의 표준 통신 프로토콜로, JSON-RPC 2.0 기반의 안정적이고 확장 가능한 아키텍처를 제공합니다
• Claude Code에서 claude mcp add 한 줄로 DB, GitHub, Slack 등 다양한 외부 시스템을 즉시 연결할 수 있습니다
• 도구 단위의 세분화된 권한 제어로 보안을 유지하면서도 개발 생산성을 극대화할 수 있습니다
• 오픈소스 생태계와 벤더 중립성 덕분에 한 번 구현한 MCP 서버를 여러 AI 클라이언트에서 재사용할 수 있습니다

 

Claude Code MCP 서버 연동은 AI 기반 개발 워크플로우의 게임 체인저입니다.

아직 경험해보지 않으셨다면, 오늘 바로 간단한 MCP 서버 하나를 만들어 연결해보세요.

공식 문서의 퀵스타트 가이드를 따라하면 30분이면 첫 번째 MCP 서버를 동작시킬 수 있습니다.

 

이 글이 도움이 되셨다면 댓글로 여러분의 MCP 활용 경험을 공유해주세요!

궁금한 점이나 다뤄줬으면 하는 주제가 있다면 언제든 남겨주시기 바랍니다.

공유도 큰 힘이 됩니다.

감사합니다!