MCP(Model Context Protocol) 완전 가이드: 9,700만 다운로드의 AI 표준이 된 이유

MCP 아키텍처 개요

┌─────────────────────────────────────────────────┐
│              Host Application                    │
│  (Claude Desktop, VS Code, IDE, 커스텀 앱)       │
│                                                  │
│  ┌─────────────┐  ┌─────────────┐               │
│  │ MCP Client  │  │ MCP Client  │  ...          │
│  │     #1      │  │     #2      │               │
│  └──────┬──────┘  └──────┬──────┘               │
│         │                │                       │
└─────────│────────────────│───────────────────────┘
          │                │
     ┌────▼────┐      ┌───▼─────┐
     │   MCP   │      │   MCP   │
     │ Server  │      │ Server  │
     │  (Git)  │      │ (Slack) │
     └────┬────┘      └────┬────┘
          │                │
     ┌────▼────┐      ┌───▼─────┐
     │ GitHub  │      │  Slack  │
     │   API   │      │   API   │
     └─────────┘      └─────────┘

{
  "resources": [
    {
      "uri": "file:///project/src/main.py",
      "name": "Main source file",
      "mimeType": "text/x-python"
    },
    {
      "uri": "db://users/schema",
      "name": "Users table schema",
      "mimeType": "application/json"
    }
  ]
}

{
  "tools": [
    {
      "name": "search_code",
      "description": "Search for code across all repositories",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Search query"
          },
          "language": {
            "type": "string",
            "description": "Programming language filter"
          }
        },
        "required": ["query"]
      }
    }
  ]
}

{
  "prompts": [
    {
      "name": "code-review",
      "description": "Review code for best practices and potential issues",
      "arguments": [
        {
          "name": "language",
          "description": "Programming language",
          "required": true
        }
      ]
    }
  ]
}

전송 방식 비교

stdio (로컬)                     Streamable HTTP (원격)
┌──────────┐    stdin/stdout     ┌──────────┐
│  Client  │◄──────────────────►│  Server  │
└──────────┘    (로컬 프로세스)   └──────────┘

┌──────────┐    HTTP/HTTPS       ┌──────────┐
│  Client  │◄──────────────────►│  Server  │
└──────────┘    (네트워크)        └──────────┘

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-05",
    "capabilities": {
      "tools": {},
      "resources": {},
      "prompts": {}
    },
    "clientInfo": {
      "name": "claude-desktop",
      "version": "1.0.0"
    }
  }
}

MCP 이전: N x M 통합

AI 모델들          외부 도구들
┌─────────┐       ┌─────────┐
│ ChatGPT │───────│ GitHub  │
│         │──┐ ┌──│         │
└─────────┘  │ │  └─────────┘
┌─────────┐  │ │  ┌─────────┐
│  Claude │──┼─┼──│  Slack  │
│         │──┼─┼──│         │
└─────────┘  │ │  └─────────┘
┌─────────┐  │ │  ┌─────────┐
│ Gemini  │──┘ └──│   DB    │
│         │───────│         │
└─────────┘       └─────────┘
= 3 x 3 = 9개 통합 필요

MCP 이후: N + M 통합

AI 모델들       MCP       외부 도구들
┌─────────┐    ┌───┐    ┌─────────┐
│ ChatGPT │────│ M │────│ GitHub  │
└─────────┘    │ C │    └─────────┘
┌─────────┐    │ P │    ┌─────────┐
│  Claude │────│   │────│  Slack  │
└─────────┘    │ 프 │    └─────────┘
┌─────────┐    │ 로 │    ┌─────────┐
│ Gemini  │────│ 토 │────│   DB    │
└─────────┘    │ 콜 │    └─────────┘
               └───┘
= 3 + 3 = 6개 통합만 필요

# 패키지 설치
pip install fastmcp httpx

# weather_server.py
from fastmcp import FastMCP
import httpx
import json

# MCP 서버 생성
mcp = FastMCP("weather-server")

# 리소스: 지원하는 도시 목록
@mcp.resource("weather://cities")
def list_cities() -> str:
    """사용 가능한 도시 목록을 반환합니다."""
    cities = [
        "seoul", "tokyo", "new-york",
        "london", "paris", "berlin"
    ]
    return json.dumps(cities, ensure_ascii=False)

# 도구: 날씨 조회
@mcp.tool()
async def get_weather(city: str) -> str:
    """
    지정된 도시의 현재 날씨 정보를 가져옵니다.

    Args:
        city: 도시 이름 (예: seoul, tokyo, new-york)
    """
    async with httpx.AsyncClient() as client:
        response = await client.get(
            f"https://wttr.in/{city}",
            params={"format": "j1"}
        )
        data = response.json()
        current = data["current_condition"][0]

        return json.dumps({
            "city": city,
            "temperature_c": current["temp_C"],
            "humidity": current["humidity"],
            "description": current["weatherDesc"][0]["value"],
            "wind_speed_kmh": current["windspeedKmph"],
            "feels_like_c": current["FeelsLikeC"]
        }, ensure_ascii=False)

# 도구: 일기예보 조회
@mcp.tool()
async def get_forecast(city: str, days: int = 3) -> str:
    """
    지정된 도시의 일기예보를 가져옵니다.

    Args:
        city: 도시 이름
        days: 예보 일수 (1-3)
    """
    async with httpx.AsyncClient() as client:
        response = await client.get(
            f"https://wttr.in/{city}",
            params={"format": "j1"}
        )
        data = response.json()
        forecasts = []

        for day in data["weather"][:days]:
            forecasts.append({
                "date": day["date"],
                "max_temp_c": day["maxtempC"],
                "min_temp_c": day["mintempC"],
                "description": day["hourly"][4]["weatherDesc"][0]["value"]
            })

        return json.dumps(forecasts, ensure_ascii=False)

# 프롬프트: 날씨 브리핑
@mcp.prompt()
def weather_briefing(city: str) -> str:
    """도시의 날씨 브리핑을 위한 프롬프트"""
    return f"""다음 도시의 날씨 정보를 분석하고 한국어로 브리핑해주세요:

도시: {city}

다음 정보를 포함해주세요:
1. 현재 기온과 체감 기온
2. 습도와 바람 상태
3. 향후 3일 예보 요약
4. 외출 시 추천 사항 (우산, 겉옷 등)
"""

if __name__ == "__main__":
    mcp.run()

# 직접 실행 테스트
python weather_server.py

# 프로젝트 초기화
npm init -y
npm install @modelcontextprotocol/sdk zod

// src/index.ts
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: 'todo-server',
  version: '1.0.0',
})

// 인메모리 할 일 저장소
interface TodoItem {
  id: string
  title: string
  completed: boolean
  createdAt: string
}

const todos: Map<string, TodoItem> = new Map()

// 도구: 할 일 추가
server.tool(
  'add_todo',
  'Add a new todo item',
  {
    title: z.string().describe('The todo item title'),
  },
  async ({ title }) => {
    const id = crypto.randomUUID()
    const todo: TodoItem = {
      id,
      title,
      completed: false,
      createdAt: new Date().toISOString(),
    }
    todos.set(id, todo)

    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(todo, null, 2),
        },
      ],
    }
  }
)

// 도구: 할 일 목록 조회
server.tool('list_todos', 'List all todo items', {}, async () => {
  const allTodos = Array.from(todos.values())
  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify(allTodos, null, 2),
      },
    ],
  }
})

// 도구: 할 일 완료 처리
server.tool(
  'complete_todo',
  'Mark a todo as completed',
  {
    id: z.string().describe('The todo item ID'),
  },
  async ({ id }) => {
    const todo = todos.get(id)
    if (!todo) {
      return {
        content: [{ type: 'text', text: 'Todo not found' }],
        isError: true,
      }
    }
    todo.completed = true
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(todo, null, 2),
        },
      ],
    }
  }
)

// 리소스: 할 일 통계
server.resource('todo-stats', 'todo://stats', async (uri) => {
  const allTodos = Array.from(todos.values())
  const stats = {
    total: allTodos.length,
    completed: allTodos.filter((t) => t.completed).length,
    pending: allTodos.filter((t) => !t.completed).length,
  }

  return {
    contents: [
      {
        uri: uri.href,
        mimeType: 'application/json',
        text: JSON.stringify(stats, null, 2),
      },
    ],
  }
})

// 서버 시작
async function main() {
  const transport = new StdioServerTransport()
  await server.connect(transport)
  console.error('Todo MCP Server running on stdio')
}

main().catch(console.error)

# Inspector 실행
npx @modelcontextprotocol/inspector python weather_server.py

# Cloudflare MCP 서버 템플릿으로 시작
npm create cloudflare@latest -- my-mcp-server \
  --template=cloudflare/ai/demos/remote-mcp-server

// src/index.ts (Cloudflare Workers용)
import { McpAgent } from 'agents/mcp'
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { z } from 'zod'

export class MyMCP extends McpAgent {
  server = new McpServer({
    name: 'my-remote-server',
    version: '1.0.0',
  })

  async init() {
    this.server.tool('hello', 'Say hello to someone', { name: z.string() }, async ({ name }) => ({
      content: [{ type: 'text', text: `Hello, ${name}!` }],
    }))
  }
}

export default {
  fetch(request: Request, env: Env, ctx: ExecutionContext) {
    const url = new URL(request.url)
    if (url.pathname === '/sse' || url.pathname === '/mcp') {
      return MyMCP.serve('/sse').fetch(request, env, ctx)
    }
    return new Response('MCP Server Running')
  },
}

# 배포
npx wrangler deploy

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://user:password@localhost:5432/mydb"
      ]
    }
  }
}

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/projects"]
    }
  }
}

# MCP 서버 추가 (프로젝트 범위)
claude mcp add github -- docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN \
  ghcr.io/github/github-mcp-server

# MCP 서버 추가 (글로벌 범위)
claude mcp add --scope user postgres -- \
  npx -y @modelcontextprotocol/server-postgres \
  postgresql://localhost:5432/mydb

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

# 특정 MCP 서버 제거
claude mcp remove github

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/projects"]
    }
  }
}

# MCP 서버 상태 확인
claude mcp list

# 서버 로그 확인 (Claude Desktop의 경우)
# macOS: ~/Library/Logs/Claude/
# Windows: %APPDATA%/Claude/logs/

# Inspector로 독립적 테스트
npx @modelcontextprotocol/inspector your-server-command

현재: AI 모델 → MCP → 외부 도구
미래: AI 에이전트 A → MCP → AI 에이전트 B