가이드2026년 4월 3일
MCP (Model Context Protocol) 완전 가이드: AI 에이전트의 표준 연결 방식
## MCP란 무엇인가?
MCP(Model Context Protocol)는 Anthropic이 2024년 11월 오픈소스로 공개한 AI-도구 연결 표준입니다. LLM이 외부 도구, 데이터소스, 서비스에 표준화된 방식으로 접근하게 해줍니다.
USB-C가 다양한 기기를 표준 포트로 연결하듯, MCP는 AI 모델과 도구를 표준 프로토콜로 연결합니다.
```mermaid
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
```
---
## 핵심 개념
**MCP의 3가지 기능:**
1. **Tools** — LLM이 호출할 수 있는 함수 (웹 검색, DB 쿼리, API 호출)
2. **Resources** — LLM이 읽을 수 있는 데이터 (파일, URL, DB 레코드)
3. **Prompts** — 재사용 가능한 프롬프트 템플릿
---
## Claude Desktop에 MCP 연결하기
```json
// ~/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"
}
}
}
}
```
연결 후 Claude에게: "내 Documents 폴더의 파일 목록을 보여줘" → 자동으로 파일시스템 MCP 호출
---
## 커스텀 MCP 서버 만들기 (Python)
```python
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())
```
---
## MCP 서버 등록
```json
// Claude Desktop config에 추가
{
"mcpServers": {
"my-shop": {
"command": "python",
"args": ["/path/to/my_mcp_server.py"]
}
}
}
```
---
## TypeScript로 MCP 서버 만들기
```typescript
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);
```
---
## MCP 활용 사례
```mermaid
mindmap
root((MCP 활용))
개발 도구
GitHub 연동
Jira 티켓 조회
CI/CD 모니터링
데이터 분석
PostgreSQL 쿼리
BigQuery 분석
Notion 문서 검색
비즈니스
Slack 메시지 전송
CRM 고객 조회
ERP 재고 확인
AI 파이프라인
벡터 DB 검색
임베딩 생성
외부 API 호출
```
---
## 현재 사용 가능한 공식 MCP 서버
- `@modelcontextprotocol/server-filesystem` — 파일시스템 읽기/쓰기
- `@modelcontextprotocol/server-github` — GitHub API
- `@modelcontextprotocol/server-postgres` — PostgreSQL 쿼리
- `@modelcontextprotocol/server-google-drive` — Google Drive
- `@modelcontextprotocol/server-slack` — Slack 메시지
- `@modelcontextprotocol/server-brave-search` — Brave 웹 검색
- `@modelcontextprotocol/server-puppeteer` — 브라우저 자동화
MCP는 AI 에이전트 생태계의 USB 포트가 되고 있습니다. 지금 공식 MCP 서버 목록(github.com/modelcontextprotocol/servers)을 확인하고 Claude Desktop에 연결해보세요.