MCP (Model Context Protocol) 완전 가이드: AI 에이전트의 표준 연결 방식

flowchart LR
    subgraph Client["MCP Client (Claude Desktop, IDE)"]
        LLM[Claude LLM]
    end
    subgraph Servers["MCP Servers"]
        FS[파일시스템 서버]
        DB[데이터베이스 서버]
        API[외부 API 서버]
        Custom[커스텀 서버]
    end
    LLM <-->|MCP Protocol| FS
    LLM <-->|MCP Protocol| DB
    LLM <-->|MCP Protocol| API
    LLM <-->|MCP Protocol| Custom

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Documents"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_URL": "postgresql://localhost/mydb"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
      }
    }
  }
}

from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp import types
import httpx
import json

app = Server("my-custom-server")

@app.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="search_products",
            description="상품 데이터베이스에서 검색합니다",
            inputSchema={
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "검색어"},
                    "category": {"type": "string", "description": "카테고리 필터"},
                    "max_results": {"type": "integer", "default": 10}
                },
                "required": ["query"]
            }
        ),
        types.Tool(
            name="get_order_status",
            description="주문 상태를 조회합니다",
            inputSchema={
                "type": "object",
                "properties": {
                    "order_id": {"type": "string"}
                },
                "required": ["order_id"]
            }
        )
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
    if name == "search_products":
        # 실제 DB 또는 API 호출
        async with httpx.AsyncClient() as client:
            response = await client.get(
                "https://api.myshop.com/products",
                params={"q": arguments["query"], "limit": arguments.get("max_results", 10)}
            )
            products = response.json()

        return [types.TextContent(
            type="text",
            text=json.dumps(products, ensure_ascii=False, indent=2)
        )]

    elif name == "get_order_status":
        # 주문 조회 로직
        order = await fetch_order(arguments["order_id"])
        return [types.TextContent(type="text", text=json.dumps(order, ensure_ascii=False))]

    raise ValueError(f"Unknown tool: {name}")

async def main():
    async with stdio_server() as (read_stream, write_stream):
        await app.run(read_stream, write_stream, app.create_initialization_options())

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

// Claude Desktop config에 추가
{
  "mcpServers": {
    "my-shop": {
      "command": "python",
      "args": ["/path/to/my_mcp_server.py"]
    }
  }
}

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  { name: "weather-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: "get_weather",
    description: "현재 날씨를 가져옵니다",
    inputSchema: {
      type: "object",
      properties: {
        city: { type: "string", description: "도시명" }
      },
      required: ["city"]
    }
  }]
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "get_weather") {
    const { city } = request.params.arguments as { city: string };
    const weather = await fetchWeather(city);
    return {
      content: [{ type: "text", text: JSON.stringify(weather) }]
    };
  }
  throw new Error(`Unknown tool: ${request.params.name}`);
});

const transport = new StdioServerTransport();
await server.connect(transport);

mindmap
  root((MCP 활용))
    개발 도구
      GitHub 연동
      Jira 티켓 조회
      CI/CD 모니터링
    데이터 분석
      PostgreSQL 쿼리
      BigQuery 분석
      Notion 문서 검색
    비즈니스
      Slack 메시지 전송
      CRM 고객 조회
      ERP 재고 확인
    AI 파이프라인
      벡터 DB 검색
      임베딩 생성
      외부 API 호출