MCP (Model Context Protocol) 완전 가이드: AI와 외부 세계를 연결하는 새로운 표준

모델 수 × 도구 수 = 통합 코드 수

Claude + (Slack + GitHub + DB + Notion) = 4개의 Claude 통합
GPT-4 + (Slack + GitHub + DB + Notion) = 4개의 GPT 통합
Gemini + (Slack + GitHub + DB + Notion) = 4개의 Gemini 통합

총 12개의 서로 다른 통합 코드

도구 수 = MCP 서버 수 (모델과 무관하게 재사용)

Slack MCP 서버 1개 → Claude, GPT-4, Gemini 모두 사용 가능
GitHub MCP 서버 1개 → 모든 모델에서 사용 가능

┌─────────────────────┐         ┌──────────────────────┐
│     MCP Client      │◄───────►│     MCP Server       │
│  (Claude, Cursor,   │  JSON   │  (your tools, DBs,   │
│   IDE, 등)          │  RPC    │   APIs, files, etc.) │
└─────────────────────┘         └──────────────────────┘

MCP Server가 노출하는 3가지:

├── Resources (읽기 전용 데이터)
│   └── 파일, DB 쿼리 결과, API 응답 등
│
├── Tools (실행 가능한 액션)
│   └── 파일 쓰기, API 호출, DB 수정 등
│
└── Prompts (재사용 가능한 프롬프트 템플릿)
    └── "코드 리뷰해줘" 같은 구조화된 템플릿

from mcp.server import Server
from mcp.server.models import InitializationOptions
import mcp.types as types
import json
import asyncio

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

# Resources 등록: 읽기 전용 데이터 노출
@app.list_resources()
async def list_resources() -> list[types.Resource]:
    return [
        types.Resource(
            uri="db://customers",
            name="Customer Database",
            description="Access customer records. Returns up to 100 records.",
            mimeType="application/json"
        ),
        types.Resource(
            uri="db://orders",
            name="Order History",
            description="Access order history for all customers",
            mimeType="application/json"
        )
    ]

@app.read_resource()
async def read_resource(uri: str) -> str:
    if uri == "db://customers":
        # 실제 DB에서 데이터를 가져옴
        customers = await db.fetch_all(
            "SELECT id, name, email, created_at FROM customers LIMIT 100"
        )
        return json.dumps([dict(c) for c in customers])

    elif uri == "db://orders":
        orders = await db.fetch_all(
            "SELECT id, customer_id, total, status, created_at FROM orders LIMIT 100"
        )
        return json.dumps([dict(o) for o in orders])

    raise ValueError(f"Unknown resource: {uri}")

# Tools 등록: 실행 가능한 액션 노출
@app.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="create_customer",
            description="Create a new customer record in the database",
            inputSchema={
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "Customer's full name"
                    },
                    "email": {
                        "type": "string",
                        "description": "Customer's email address"
                    },
                    "phone": {
                        "type": "string",
                        "description": "Customer's phone number (optional)"
                    }
                },
                "required": ["name", "email"]
            }
        ),
        types.Tool(
            name="search_customers",
            description="Search customers by name or email",
            inputSchema={
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Search query (name or email)"
                    }
                },
                "required": ["query"]
            }
        )
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
    if name == "create_customer":
        result = await db.execute(
            "INSERT INTO customers (name, email, phone) VALUES (:name, :email, :phone)",
            {
                "name": arguments["name"],
                "email": arguments["email"],
                "phone": arguments.get("phone", None)
            }
        )
        return [types.TextContent(
            type="text",
            text=f"Customer created successfully. ID: {result.lastrowid}"
        )]

    elif name == "search_customers":
        query = f"%{arguments['query']}%"
        customers = await db.fetch_all(
            "SELECT id, name, email FROM customers WHERE name LIKE :q OR email LIKE :q",
            {"q": query}
        )
        if not customers:
            return [types.TextContent(type="text", text="No customers found")]

        result = "\n".join([f"ID: {c.id}, Name: {c.name}, Email: {c.email}" for c in customers])
        return [types.TextContent(type="text", text=result)]

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

# 서버 실행
async def main():
    from mcp.server.stdio import stdio_server
    async with stdio_server() as (read_stream, write_stream):
        await app.run(
            read_stream,
            write_stream,
            InitializationOptions(
                server_name="my-database-server",
                server_version="0.1.0"
            )
        )

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

// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
// Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "my-database": {
      "command": "python",
      "args": ["/path/to/your/mcp_server.py"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost/mydb"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/projects"]
    }
  }
}

# OpenAI function calling — OpenAI API에 종속
tools = [{"type": "function", "function": {"name": "search", ...}}]
response = openai.chat.completions.create(tools=tools, ...)

# LangChain — 프레임워크에 종속
from langchain.tools import tool

@tool
def search(query: str) -> str:
    """Search the web"""
    return web_search(query)

# MCP — 어떤 MCP 클라이언트에서도 동작
@app.list_tools()
async def list_tools():
    return [types.Tool(name="search", ...)]

# npm으로 설치 (Node.js 서버의 경우)
npx -y @modelcontextprotocol/server-github

# pip으로 설치 (Python 서버의 경우)
pip install mcp

# 나쁜 예
types.Tool(name="query_db", description="Query database")

# 좋은 예
types.Tool(
    name="query_customers",
    description=(
        "Search customer records. Use this when you need to find customers "
        "by name, email, or ID. Returns customer ID, name, email, and creation date. "
        "Use search_orders for order-related queries."
    )
)

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    try:
        result = await execute_operation(arguments)
        return [types.TextContent(type="text", text=json.dumps(result))]
    except Exception as e:
        # 에러도 정상 응답으로 반환 — LLM이 에러를 보고 대응할 수 있음
        return [types.TextContent(
            type="text",
            text=f"Error: {str(e)}. Please check the input and try again."
        )]