MCP Server

MCP(Model Context Protocol)는 Anthropic이 2024년 11월에 발표한 오픈 표준 프로토콜로, AI 애플리케이션(Claude, ChatGPT 등)이 외부 시스템(DB, 파일, API 등)과 표준화된 방식으로 연결할 수 있게 해준다.

USB-C 포트 비유: USB-C가 전자기기를 연결하는 표준이듯, MCP는 AI 앱을 외부 시스템에 연결하는 표준이다.

MCP Server는 이 프로토콜에서 컨텍스트를 제공하는 프로그램을 의미한다. 즉, AI가 사용할 수 있는 도구(tool)나 데이터(resource)를 노출하는 서버 프로그램이다.

해당 개념이 필요한 이유

• AI 앱에서 외부 데이터(DB, API 등)에 접근하려면 각각 커스텀 커넥터를 만들어야 했다 (N×M 문제)
• MCP를 사용하면 하나의 표준 인터페이스로 모든 AI 앱이 동일한 서버에 접속 가능
• Claude Code, Codex CLI 등에서 내 DB의 Todo 데이터를 직접 조회/생성할 수 있다

AS-IS

sequenceDiagram
    autonumber
    participant CC as Claude Code
    participant API as Custom API
    participant DB as Database

    CC->>API: 직접 HTTP 호출 (커스텀 코드 필요)
    API->>DB: SQL 쿼리
    DB-->>API: 결과 반환
    API-->>CC: JSON 응답
    Note over CC,DB: 각 AI 앱마다 별도 연동 코드 필요<br/>(N×M 문제)

TO-BE

sequenceDiagram
    autonumber
    participant CC as Claude Code
    participant MC as MCP Client
    participant MS as MCP Server
    participant DB as DB

    CC->>MC: "Todo 목록 보여줘"
    MC->>MS: tools/call: getTodos (JSON-RPC)
    MS->>DB: getTodos (DB)
    DB-->>MS: Todo[]
    MS-->>MC: content: [{type: "text", text: "..."}]
    MC-->>CC: 자연어 응답 생성
    Note over CC,DB: 표준 프로토콜로 어떤 AI 앱이든<br/>동일한 MCP Server 재사용

MCP 아키텍처: 3가지 참여자

참여자	역할	예시
MCP Host	AI 앱, MCP Client를 관리	Claude Code, Claude Desktop, VS Code
MCP Client	MCP Server와 1:1 연결 유지	Host 내부에서 자동 생성됨
MCP Server	컨텍스트(Tool, Resource)를 제공	Prisma Todo 서버

graph TB
    subgraph "MCP Host (Claude Code)"
        Client1["MCP Client 1"]
        Client2["MCP Client 2"]
    end

    ServerA["MCP Server A<br/>(Todo - Prisma)"]
    ServerB["MCP Server B<br/>(파일시스템)"]

    Client1 ---|"STDIO"| ServerA
    Client2 ---|"STDIO"| ServerB

MCP의 2가지 레이어

Data Layer (JSON-RPC 2.0)

클라이언트-서버 간 메시지 구조와 의미를 정의한다.

• Lifecycle: 연결 초기화 → 기능 협상(capability negotiation) → 종료
• Server Primitives: Tools, Resources, Prompts
• Client Primitives: Sampling, Elicitation, Logging

Transport Layer

통신 채널과 인증을 관리한다.

Transport	설명	MCP 서버 위치	사용 시점
STDIO	stdin/stdout 스트림	같은 컴퓨터 (로컬)	로컬 프로세스
Streamable HTTP	HTTP POST + SSE	다른 컴퓨터 (원격 서버)	원격 서버

레이어 이해를 위한 비유

우체국 시스템에 비유:

레이어	역할	우체국 비유	실제 MCP 예시
Transport Layer	어떤 운송 수단?	🚗 택배차 vs ✈️ 비행기	STDIO vs HTTP
Data Layer	편지 내용과 형식	📝 편지 포맷 (발신자, 수신자, 본문)	JSON-RPC 메시지 (tools/list, tools/call)

예시:

• Transport Layer: “이 편지를 택배차(STDIO)로 보낼까, 비행기(HTTP)로 보낼까?”
• Data Layer: “편지에 어떤 내용(tools/list 요청)을 어떤 형식(JSON-RPC)으로 적을까?”

실제 동작:

sequenceDiagram
    autonumber
    participant Client as MCP Client
    participant Server as MCP Server

    Note over Client,Server: Transport Layer: STDIO로 물리적 전송
    Client->>Server: {"method":"tools/list"} (Data Layer)
    Note over Server: JSON-RPC 메시지 해석
    Server-->>Client: {"result":{"tools":[...]}} (Data Layer)
    Note over Client: 응답 데이터 처리

• Transport Layer: STDIO를 통해 데이터가 물리적으로 전송됨
• Data Layer: JSON-RPC 형식의 메시지가 의미적으로 해석됨

3대 Server Primitives (핵심)

MCP Server가 노출할 수 있는 3가지 핵심 요소:

1. Tools (도구)

• AI가 실행 가능한 함수 (e.g. getTodos, createTodo)
• tools/list로 발견, tools/call로 실행
• inputSchema로 파라미터 타입 정의 (JSON Schema)

2. Resources (리소스)

• 읽기 전용 데이터 제공 (파일 내용, DB 스키마 등)
• resources/list로 발견, resources/read로 조회

3. Prompts (프롬프트)

• 재사용 가능한 템플릿 (시스템 프롬프트, few-shot 예시)
• prompts/list로 발견, prompts/get으로 조회

TypeScript로 MCP Server 만드는 방법

1. 프로젝트 셋업

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod@3
npm install -D @types/node typescript

2. Tool 등록 (핵심 코드 패턴)

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
 
const server = new McpServer({
  name: "my-server",
  version: "1.0.0",
});
 
// Tool 등록
server.registerTool(
  "getTodos",
  {
    description: "Get all todos from the database",
    inputSchema: {},  // 파라미터 없음
  },
  async () => {
    // Prisma로 DB 조회
    const todos = await prisma.todo.findMany();
    return {
      content: [{ type: "text", text: JSON.stringify(todos) }],
    };
  }
);
 
// 서버 시작 (STDIO transport)
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}
main();

3. Claude Code에 등록

~/.claude/settings.json:

{
  "mcpServers": {
    "todo-server": {
      "command": "node",
      "args": ["/absolute/path/to/build/index.js"]
    }
  }
}

프로토콜 통신 흐름 (실제 JSON-RPC 메시지)

sequenceDiagram
    autonumber
    participant Client as MCP Client
    participant Server as MCP Server

    Note over Client,Server: 1. 초기화 (Lifecycle)
    Client->>Server: initialize {protocolVersion, capabilities}
    Server-->>Client: {capabilities: {tools: {}}}
    Client->>Server: notifications/initialized

    Note over Client,Server: 2. 도구 발견 (Discovery)
    Client->>Server: tools/list
    Server-->>Client: {tools: [{name: "getTodos", ...}]}

    Note over Client,Server: 3. 도구 실행 (Execution)
    Client->>Server: tools/call {name: "getTodos"}
    Server-->>Client: {content: [{type: "text", text: "[...]"}]}

STDIO Transport

STDIO(Standard Input/Output) Transport는 같은 머신에서 실행되는 두 프로세스 간 통신 방식이다.

핵심 원리:

• 부모 프로세스(Claude Code)가 자식 프로세스(MCP Server)를 spawn
• 부모 → 자식: stdin으로 JSON-RPC 메시지 전송
• 자식 → 부모: stdout으로 JSON-RPC 응답 전송

왜 console.log() 금지인가:

• stdout은 JSON-RPC 메시지 전용 채널
• console.log("hello")가 stdout에 쓰이면 → 클라이언트가 "hello"를 JSON-RPC로 파싱 시도 → 파싱 에러로 서버 크래시
• 디버깅 로그는 반드시 console.error() (stderr)로 출력

STDIO vs HTTP 비교:

	STDIO	Streamable HTTP
실행 위치	로컬 (같은 머신)	원격 가능
연결 방식	프로세스 spawn	HTTP 요청
클라이언트 수	1:1	1:N
네트워크 오버헤드	없음	있음

참고 문서

• MCP 공식 소개
• MCP 아키텍처
• MCP Server 빌드 가이드
• Wikipedia: Model Context Protocol