Split View: MCP(Model Context Protocol) 완전 가이드: 9,700만 다운로드의 AI 표준이 된 이유
MCP(Model Context Protocol) 완전 가이드: 9,700만 다운로드의 AI 표준이 된 이유
- MCP란 무엇인가: AI의 USB-C
- 아키텍처 딥다이브
- 왜 MCP가 승리했는가
- MCP 서버 만들기: 실전 가이드
- 주요 MCP 서버 생태계
- Claude Code + MCP 실전 워크플로우
- 개발자가 알아야 할 MCP 로드맵
- 실전 퀴즈
- 참고 자료
MCP란 무엇인가: AI의 USB-C
하나의 프로토콜이 모든 것을 연결하다
USB가 등장하기 전, 프린터에는 패럴렐 포트, 키보드에는 PS/2, 카메라에는 시리얼 포트를 사용했습니다. 기기마다 다른 케이블, 다른 드라이버, 다른 연결 방식. USB가 이 혼란을 종식시킨 것처럼, **MCP(Model Context Protocol)**는 AI 세계의 연결 표준을 만들었습니다.
MCP는 AI 모델이 외부 데이터 소스, 도구, 서비스와 통신하기 위한 개방형 표준 프로토콜입니다. Anthropic이 2024년 11월에 오픈소스로 공개했으며, 불과 1년여 만에 AI 업계의 사실상 표준(de facto standard)이 되었습니다.
MCP 이전의 세계: N x M 문제
MCP가 없던 시절을 떠올려보겠습니다.
- ChatGPT가 GitHub 데이터에 접근하려면? OpenAI 전용 플러그인 필요
- Claude가 Slack 메시지를 읽으려면? Anthropic 전용 통합 필요
- Gemini가 데이터베이스를 조회하려면? Google 전용 커넥터 필요
N개의 AI 모델과 M개의 외부 도구가 있을 때, 총 N x M개의 커스텀 통합이 필요했습니다. AI 모델이 5개이고 외부 도구가 100개라면, 500개의 개별 통합을 만들어야 했습니다.
MCP는 이 문제를 N + M으로 줄였습니다. 각 AI 모델은 MCP 클라이언트 하나만 구현하면 되고, 각 도구는 MCP 서버 하나만 구현하면 됩니다. USB처럼 한쪽 끝만 맞추면 모든 것이 연결됩니다.
폭발적 성장의 타임라인
MCP의 성장 속도는 경이적입니다.
| 시점 | 이벤트 | 의미 |
|---|---|---|
| 2024년 11월 | Anthropic이 MCP 오픈소스 공개 | 프로토콜 탄생 |
| 2025년 1월 | Claude Desktop에 MCP 통합 | 최초의 대규모 클라이언트 |
| 2025년 3월 | OpenAI가 Agents SDK에 MCP 채택 | 경쟁사의 수용, 업계 표준 인정 |
| 2025년 4월 | Google DeepMind가 Agent Development Kit에 MCP 지원 | 빅3 완성 |
| 2025년 6월 | OAuth 2.0 인증 스펙 추가 | 엔터프라이즈 준비 완료 |
| 2025년 11월 | MCP 1주년 업데이트, 원격 서버 지원 강화 | 성숙기 진입 |
| 2025년 12월 | Linux Foundation AAIF에 기부 | 커뮤니티 거버넌스 전환 |
| 2026년 3월 | 월간 SDK 다운로드 9,700만 돌파 | 폭발적 채택 확인 |
Python SDK와 TypeScript SDK의 월간 다운로드를 합치면 9,700만 회에 달합니다. MCP.so 마켓플레이스에는 수만 개의 MCP 서버가 등록되어 있으며, GitHub에서 "MCP server"를 검색하면 수천 개의 리포지토리가 나옵니다.
MCP가 해결하는 핵심 문제
AI 모델은 기본적으로 격리된 존재입니다. 아무리 똑똑한 모델이라도 학습 데이터 이후의 정보를 모르고, 회사 내부 데이터에 접근할 수 없으며, 외부 시스템에 작업을 요청할 수 없습니다.
MCP는 이 격리를 세 가지 방식으로 해소합니다.
- Resources (리소스): AI가 읽을 수 있는 데이터를 제공 (파일, DB 레코드, API 응답)
- Tools (도구): AI가 실행할 수 있는 함수를 제공 (API 호출, 코드 실행, 파일 생성)
- Prompts (프롬프트): 특정 작업에 최적화된 프롬프트 템플릿을 제공
이 세 가지 요소가 MCP 프로토콜의 기둥이며, 다음 섹션에서 아키텍처를 자세히 살펴보겠습니다.
아키텍처 딥다이브
Client-Server 모델
MCP는 클라이언트-서버 아키텍처를 따릅니다. JSON-RPC 2.0 프로토콜 위에 구축되어 가볍고 효율적입니다.
MCP 아키텍처 개요
┌─────────────────────────────────────────────────┐
│ Host Application │
│ (Claude Desktop, VS Code, IDE, 커스텀 앱) │
│ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ MCP Client │ │ MCP Client │ ... │
│ │ #1 │ │ #2 │ │
│ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │
└─────────│────────────────│───────────────────────┘
│ │
┌────▼────┐ ┌───▼─────┐
│ MCP │ │ MCP │
│ Server │ │ Server │
│ (Git) │ │ (Slack) │
└────┬────┘ └────┬────┘
│ │
┌────▼────┐ ┌───▼─────┐
│ GitHub │ │ Slack │
│ API │ │ API │
└─────────┘ └─────────┘
핵심 구성요소를 정리하면 다음과 같습니다.
- Host: MCP 클라이언트를 실행하는 애플리케이션 (Claude Desktop, VS Code, 커스텀 앱)
- Client: 호스트 내부에서 특정 MCP 서버와 1:1로 통신하는 커넥터
- Server: 외부 시스템의 데이터와 기능을 표준화된 형태로 제공하는 서비스
하나의 호스트 앱이 여러 MCP 클라이언트를 동시에 실행할 수 있습니다. 예를 들어 Claude Desktop이 GitHub MCP 서버, Slack MCP 서버, PostgreSQL MCP 서버에 동시에 연결하는 것이 가능합니다.
3가지 핵심 개념: Resources, Tools, Prompts
Resources (리소스)
리소스는 MCP 서버가 클라이언트에 제공하는 읽기 전용 데이터입니다. URI 형태로 식별됩니다.
{
"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"
}
]
}
리소스는 AI 모델의 컨텍스트를 풍부하게 만듭니다. 코드 파일, 데이터베이스 스키마, API 문서, 설정 파일 등 AI가 참조해야 할 모든 데이터를 리소스로 제공할 수 있습니다.
Tools (도구)
도구는 AI 모델이 실행할 수 있는 함수입니다. Function calling의 표준화된 버전이라고 볼 수 있습니다.
{
"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"]
}
}
]
}
AI 모델은 도구 목록을 확인하고, 사용자의 요청에 따라 적절한 도구를 선택하여 호출합니다. 결과는 다시 모델에 전달되어 응답 생성에 사용됩니다.
Prompts (프롬프트)
프롬프트는 특정 작업에 최적화된 재사용 가능한 프롬프트 템플릿입니다.
{
"prompts": [
{
"name": "code-review",
"description": "Review code for best practices and potential issues",
"arguments": [
{
"name": "language",
"description": "Programming language",
"required": true
}
]
}
]
}
프롬프트를 통해 도메인 전문가가 최적의 지시문을 만들고, 이를 MCP 서버를 통해 배포할 수 있습니다.
Transport: 로컬 vs 원격
MCP는 두 가지 전송 방식을 지원합니다.
stdio (표준 입출력)
- 로컬에서 MCP 서버를 프로세스로 실행
- stdin/stdout을 통해 JSON-RPC 메시지 교환
- 설치가 간단하고 보안이 높음
- 개인 개발 환경에 적합
Streamable HTTP (이전 SSE)
- 원격 서버와 HTTP를 통해 통신
- 2025년 11월 업데이트로 SSE에서 Streamable HTTP로 발전
- 팀/조직 단위 공유에 적합
- Cloudflare, AWS 등에 배포 가능
전송 방식 비교
stdio (로컬) Streamable HTTP (원격)
┌──────────┐ stdin/stdout ┌──────────┐
│ Client │◄──────────────────►│ Server │
└──────────┘ (로컬 프로세스) └──────────┘
┌──────────┐ HTTP/HTTPS ┌──────────┐
│ Client │◄──────────────────►│ Server │
└──────────┘ (네트워크) └──────────┘
인증: OAuth 2.0
2025년 6월에 추가된 인증 스펙은 MCP의 엔터프라이즈 적용을 가능하게 한 핵심 업데이트입니다.
- OAuth 2.0 기반 인증 흐름 표준화
- 토큰 기반 권한 관리
- 세분화된 스코프(scope) 제어
- 기존 IdP(Identity Provider)와 통합 가능
이를 통해 기업 환경에서 "어떤 AI 모델이 어떤 데이터에 접근할 수 있는가"를 체계적으로 관리할 수 있게 되었습니다.
프로토콜 수명주기
MCP 연결의 수명주기는 다음과 같습니다.
- 초기화(Initialization): 클라이언트가 서버에 연결하고 프로토콜 버전, 지원 기능 협상
- 디스커버리(Discovery): 클라이언트가 서버의 리소스, 도구, 프롬프트 목록 조회
- 실행(Execution): AI 모델의 요청에 따라 도구 호출, 리소스 읽기 수행
- 종료(Shutdown): 연결 정리 및 리소스 해제
{
"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 문제의 근본적 해결
앞서 설명한 N x M 문제는 AI 생태계의 가장 큰 비효율이었습니다.
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개 통합만 필요
이 효율성은 생태계가 커질수록 더 극적입니다. AI 모델 10개, 외부 도구 1,000개인 경우 10,000개의 통합 대신 1,010개만 있으면 됩니다.
OpenAI의 채택: 경쟁사가 만든 표준을 수용하다
2025년 3월, OpenAI가 Agents SDK에 MCP 지원을 발표한 것은 업계에 큰 충격이었습니다. Anthropic이 만든 프로토콜을 최대 경쟁사가 채택한 것입니다.
OpenAI의 Sam Altman은 이렇게 언급했습니다. "개방형 표준은 모든 참여자에게 이익이 된다. 우리는 에이전트가 더 많은 도구에 접근할 수 있기를 원한다."
이 결정의 배경에는 실용적 판단이 있었습니다.
- 이미 형성된 MCP 생태계를 무시할 수 없음
- 자체 프로토콜을 만들면 생태계가 분열됨
- 개발자들이 이미 MCP 서버를 구축하고 있었음
- 표준화가 전체 시장을 키워 모두에게 이익
Google DeepMind의 합류
2025년 4월, Google은 Agent Development Kit(ADK)에서 MCP를 지원한다고 발표했습니다. 이로써 AI 업계의 "빅3"가 모두 MCP를 지원하게 되었습니다.
Google의 합류는 MCP가 단일 기업의 프로젝트가 아니라 업계 전체의 표준이 되었음을 확인해주었습니다.
Linux Foundation 기부: 커뮤니티 거버넌스
2025년 12월, Anthropic은 MCP를 Linux Foundation의 AI and Data Foundation(AAIF)에 기부했습니다. 이는 매우 중요한 결정입니다.
- 중립성 보장: 특정 기업이 아닌 커뮤니티가 표준을 관리
- 지속 가능성: Anthropic의 사업 방향과 무관하게 프로토콜이 발전
- 신뢰 구축: 경쟁사들이 안심하고 참여할 수 있는 환경
- 거버넌스 투명성: 공개적인 의사결정 과정
Linux, Kubernetes, Node.js 등 성공적인 오픈소스 프로젝트들이 걸어온 길과 동일한 경로입니다.
MCP vs Function Calling vs LangChain Tools
| 항목 | MCP | Function Calling | LangChain Tools |
|---|---|---|---|
| 표준화 | 개방형 프로토콜 | 각 AI 벤더 독자 스펙 | 라이브러리 수준 추상화 |
| 재사용성 | 한번 만들면 모든 AI에서 사용 | 특정 AI 벤더에 종속 | LangChain 생태계 내에서만 |
| 전송 방식 | stdio, Streamable HTTP | HTTP API | 인프로세스(in-process) |
| 디스커버리 | 동적 도구/리소스 검색 | 사전 정의 필요 | 사전 정의 필요 |
| 인증 | OAuth 2.0 표준 | 각 벤더 방식 | 별도 구현 필요 |
| 상태 관리 | 프로토콜 수준 지원 | 없음 | 라이브러리 수준 |
| 생태계 크기 | 수만 개 서버 | 벤더별 플러그인 | 수백 개 도구 |
MCP의 가장 큰 차별점은 벤더 독립성입니다. 한 번 만든 MCP 서버는 Claude, ChatGPT, Gemini, 오픈소스 LLM 등 어떤 AI 모델에서든 동작합니다.
MCP 서버 만들기: 실전 가이드
FastMCP로 Python 서버 만들기
FastMCP는 Python으로 MCP 서버를 빠르게 구축할 수 있는 프레임워크입니다. 간단한 날씨 정보 서버를 만들어보겠습니다.
# 패키지 설치
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()
이 서버를 실행하면 Claude Desktop이나 다른 MCP 클라이언트에서 바로 연결할 수 있습니다.
# 직접 실행 테스트
python weather_server.py
TypeScript SDK로 서버 만들기
TypeScript를 선호한다면 공식 SDK를 사용할 수 있습니다.
# 프로젝트 초기화
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)
MCP Inspector로 디버깅하기
MCP Inspector는 MCP 서버를 테스트하고 디버깅할 수 있는 공식 도구입니다.
# Inspector 실행
npx @modelcontextprotocol/inspector python weather_server.py
Inspector를 실행하면 브라우저에서 다음과 같은 작업이 가능합니다.
- 서버가 제공하는 도구, 리소스, 프롬프트 목록 확인
- 각 도구를 직접 호출하고 결과 확인
- JSON-RPC 메시지 로그 실시간 확인
- 에러 메시지 디버깅
개발 과정에서 Inspector는 필수 도구입니다. 서버가 올바르게 동작하는지 클라이언트 연결 전에 미리 검증할 수 있습니다.
Cloudflare에 원격 서버 배포하기
로컬에서 검증이 끝나면 원격으로 배포할 수 있습니다. Cloudflare Workers는 MCP 서버 배포에 특히 적합합니다.
# 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
배포 후 어디서든 Streamable HTTP를 통해 MCP 서버에 연결할 수 있습니다. 팀 전체가 하나의 원격 MCP 서버를 공유하는 것이 가능합니다.
주요 MCP 서버 생태계
GitHub MCP Server
GitHub 공식 MCP 서버는 가장 인기 있는 MCP 서버 중 하나입니다.
제공하는 도구들:
- 리포지토리 검색 및 탐색
- 이슈 생성, 조회, 수정
- Pull Request 생성 및 리뷰
- 코드 검색 (정규식 지원)
- 브랜치 관리
- 파일 읽기/쓰기
Claude Desktop 설정 예시:
{
"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"
}
}
}
}
Google Drive / Docs MCP
Google Workspace와 AI를 연결하는 MCP 서버입니다.
주요 기능:
- Google Drive 파일 검색
- Google Docs 문서 내용 읽기
- Google Sheets 데이터 조회
- 파일 메타데이터 조회
Slack MCP
팀 커뮤니케이션 도구인 Slack과 AI를 연결합니다.
주요 기능:
- 채널 메시지 읽기
- 메시지 검색
- 채널 목록 조회
- 스레드 컨텍스트 파악
Database MCP (PostgreSQL, MySQL)
데이터베이스에 직접 접근하여 AI가 데이터를 조회하고 분석할 수 있게 합니다.
주요 기능:
- SQL 쿼리 실행 (읽기 전용 모드 지원)
- 스키마 탐색
- 테이블 목록 및 컬럼 정보 조회
- 쿼리 결과 분석
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://user:password@localhost:5432/mydb"
]
}
}
}
Filesystem MCP
로컬 파일 시스템에 대한 접근을 제공하는 기본 MCP 서버입니다.
주요 기능:
- 파일/디렉토리 읽기
- 파일 검색 (glob 패턴)
- 파일 생성/수정
- 디렉토리 구조 탐색
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/projects"]
}
}
}
Brave Search MCP
웹 검색 기능을 AI에 제공합니다. AI가 최신 정보를 검색하고 답변에 활용할 수 있습니다.
주요 기능:
- 웹 검색
- 뉴스 검색
- 검색 결과 요약
- 특정 도메인 필터링
이 외에도 수만 개의 MCP 서버가 MCP.so 마켓플레이스와 GitHub에 공개되어 있습니다. Notion, Jira, Linear, Figma, AWS, GCP 등 거의 모든 주요 서비스에 대한 MCP 서버가 존재합니다.
Claude Code + MCP 실전 워크플로우
Claude Code에서 MCP 서버 연결하기
Claude Code는 Anthropic이 제공하는 CLI 기반 AI 코딩 도구로, MCP를 네이티브로 지원합니다.
# 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
Claude Code의 설정 파일에 직접 추가할 수도 있습니다.
{
"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"]
}
}
}
실제 사용 예: DB 조회에서 PR 생성까지
MCP의 진정한 힘은 여러 서버를 조합할 때 나타납니다. 실제 워크플로우를 살펴보겠습니다.
시나리오: "users 테이블에 last_login_at 컬럼을 추가하고, 마이그레이션을 만들어서 PR을 올려줘"
이 하나의 요청에서 Claude Code는 다음과 같이 동작합니다.
- PostgreSQL MCP 서버로 현재 users 테이블 스키마 조회
- 기존 스키마를 분석하여 마이그레이션 SQL 작성
- Filesystem MCP 서버로 마이그레이션 파일 생성
- 관련 모델 코드 업데이트
- GitHub MCP 서버로 브랜치 생성, 커밋, PR 생성
전체 과정이 하나의 대화에서 자동으로 이루어집니다. 개발자는 최종 PR만 리뷰하면 됩니다.
또 다른 시나리오: "Slack에서 오늘 논의된 버그 리포트를 정리해서 GitHub 이슈로 만들어줘"
- Slack MCP 서버로 오늘의 채널 메시지 검색
- 버그 관련 메시지 필터링 및 요약
- GitHub MCP 서버로 이슈 생성 (라벨, 담당자 자동 지정)
이처럼 MCP는 AI 에이전트가 실제로 업무를 수행할 수 있게 만드는 핵심 인프라입니다.
MCP 서버 디버깅 팁
Claude Code에서 MCP 서버 연결에 문제가 있을 때 유용한 디버깅 방법들입니다.
# MCP 서버 상태 확인
claude mcp list
# 서버 로그 확인 (Claude Desktop의 경우)
# macOS: ~/Library/Logs/Claude/
# Windows: %APPDATA%/Claude/logs/
# Inspector로 독립적 테스트
npx @modelcontextprotocol/inspector your-server-command
자주 발생하는 문제와 해결 방법:
| 증상 | 원인 | 해결 |
|---|---|---|
| 서버가 연결되지 않음 | 실행 파일 경로 오류 | 절대 경로 사용, which 명령으로 확인 |
| 도구가 표시되지 않음 | 초기화 실패 | Inspector로 서버 독립 테스트 |
| 타임아웃 에러 | 서버 응답 지연 | 비동기 처리 확인, 타임아웃 설정 조정 |
| 인증 실패 | 토큰 만료/오류 | 환경 변수 재설정 |
개발자가 알아야 할 MCP 로드맵
2024-2025 주요 마일스톤
2024년 11월 - 탄생
Anthropic이 MCP를 오픈소스로 공개했습니다. 초기에는 Claude Desktop 전용이었지만, 개방형 프로토콜로 설계되어 누구나 구현할 수 있었습니다.
2025년 3월 - OpenAI 채택
OpenAI가 Agents SDK에서 MCP를 지원한다고 발표했습니다. 이는 MCP가 단일 기업의 프로젝트를 넘어 업계 표준으로 자리매김하는 전환점이었습니다.
2025년 6월 - 인증 스펙 추가
OAuth 2.0 기반 인증이 MCP 스펙에 추가되었습니다. 이를 통해 기업 환경에서 안전하게 MCP를 사용할 수 있게 되었습니다.
- 토큰 기반 인증 흐름
- 세분화된 권한(scope) 관리
- 기존 IdP(Identity Provider) 통합
- 감사(audit) 로그 지원
2025년 11월 - 1주년 대규모 업데이트
MCP 1주년을 맞아 주요 업데이트가 발표되었습니다.
- Streamable HTTP: 기존 SSE 전송을 대체하는 더 효율적인 원격 통신 방식
- Tool Annotations: 도구의 부작용(side effects)을 명시적으로 선언
- Elicitation: 서버가 실행 중 사용자에게 추가 정보를 요청하는 기능
- Structured Output: 도구 출력의 스키마를 정의하는 기능
2025년 12월 - Linux Foundation 기부
MCP가 Linux Foundation의 AI and Data Foundation(AAIF)에 기부되었습니다. 이로써 MCP의 거버넌스는 Anthropic 단독에서 커뮤니티 주도로 전환되었습니다.
2026년 전망
에이전트 간 MCP 통신
현재 MCP는 주로 "AI 모델 - 외부 도구" 간의 통신에 사용됩니다. 2026년에는 에이전트 간 통신으로 확장될 전망입니다.
현재: AI 모델 → MCP → 외부 도구
미래: AI 에이전트 A → MCP → AI 에이전트 B
예를 들어, 코딩 에이전트가 테스트 에이전트에게 MCP를 통해 테스트 실행을 요청하고, 테스트 에이전트가 결과를 MCP를 통해 반환하는 시나리오가 가능해집니다.
멀티모달 MCP
텍스트뿐만 아니라 이미지, 오디오, 비디오를 MCP를 통해 전달하는 기능이 확장될 전망입니다. 이미 일부 MCP 서버가 이미지 리소스를 지원하고 있으며, 이 추세는 가속화될 것입니다.
엔터프라이즈 MCP 게이트웨이
대기업 환경에서 MCP 서버 접근을 중앙 관리하는 게이트웨이 솔루션이 등장하고 있습니다.
- 중앙 집중식 인증/인가
- 사용량 모니터링 및 제한
- 감사 로그
- 정책 기반 접근 제어
MCP 레지스트리
npm이나 PyPI처럼 MCP 서버를 검색하고 설치할 수 있는 공식 레지스트리의 등장이 예상됩니다. 현재 MCP.so가 비공식 마켓플레이스 역할을 하고 있으나, Linux Foundation 기부 이후 공식 레지스트리 구축이 논의되고 있습니다.
실전 퀴즈
MCP에 대한 이해를 점검해보겠습니다.
Q1. MCP가 해결하는 핵심 문제인 "N x M 문제"란 무엇인가요?
정답: N개의 AI 모델과 M개의 외부 도구를 연결할 때, 각각에 대한 커스텀 통합이 필요하여 총 N x M개의 통합이 필요한 문제입니다. MCP는 표준 프로토콜을 제공하여 이를 N + M으로 줄입니다. 각 AI 모델은 MCP 클라이언트 하나만, 각 도구는 MCP 서버 하나만 구현하면 됩니다.
Q2. MCP의 3가지 핵심 개념(Resources, Tools, Prompts)의 차이점을 설명해주세요.
정답:
- Resources (리소스): AI가 읽을 수 있는 읽기 전용 데이터입니다. 파일, DB 스키마, API 응답 등 컨텍스트를 제공합니다. URI로 식별됩니다.
- Tools (도구): AI가 실행할 수 있는 함수입니다. API 호출, 데이터 생성/수정, 외부 시스템 조작 등 액션을 수행합니다.
- Prompts (프롬프트): 특정 작업에 최적화된 재사용 가능한 프롬프트 템플릿입니다. 도메인 전문가가 최적의 지시문을 만들어 배포할 수 있습니다.
간단히 말해, 리소스는 "읽기", 도구는 "실행", 프롬프트는 "안내"입니다.
Q3. OpenAI가 경쟁사인 Anthropic이 만든 MCP를 채택한 이유는 무엇일까요?
정답: 실용적 판단의 결과입니다. 첫째, 이미 형성된 MCP 생태계를 무시할 수 없었습니다. 둘째, 자체 프로토콜을 만들면 생태계가 분열되어 모두에게 손해입니다. 셋째, 개발자들이 이미 MCP 서버를 구축하고 있어 네트워크 효과가 작동하고 있었습니다. 넷째, 표준화가 전체 시장을 키워 결과적으로 OpenAI에게도 이익이 됩니다. 이는 마치 웹 브라우저들이 W3C 표준을 따르는 것과 같은 논리입니다.
Q4. MCP의 두 가지 전송 방식(stdio vs Streamable HTTP)은 각각 어떤 상황에 적합한가요?
정답:
- stdio (표준 입출력): 로컬 개발 환경에 적합합니다. MCP 서버를 로컬 프로세스로 실행하고 stdin/stdout으로 통신합니다. 설치가 간단하고, 네트워크 없이 동작하며, 보안이 높습니다. 개인 개발자나 단일 머신 환경에서 사용합니다.
- Streamable HTTP: 원격/팀 환경에 적합합니다. HTTP를 통해 네트워크로 통신하므로 Cloudflare, AWS 등에 배포하여 팀 전체가 공유할 수 있습니다. 인증, 접근 제어, 모니터링이 가능합니다.
Q5. MCP가 Linux Foundation에 기부된 것이 왜 중요한가요?
정답: Linux Foundation 기부는 MCP의 장기적 성공을 위한 핵심 결정입니다. 첫째, 특정 기업이 아닌 커뮤니티가 표준을 관리하여 중립성이 보장됩니다. 둘째, Anthropic의 사업 방향 변화와 무관하게 프로토콜이 지속 가능합니다. 셋째, 경쟁사들이 안심하고 참여할 수 있어 신뢰가 강화됩니다. 넷째, 공개적인 의사결정 과정으로 거버넌스 투명성이 확보됩니다. Linux, Kubernetes, Node.js 등 성공적인 오픈소스 프로젝트들의 검증된 경로입니다.
참고 자료
- MCP 공식 사이트 - modelcontextprotocol.io - 스펙, 문서, 퀵스타트 가이드
- MCP GitHub 리포지토리 - github.com/modelcontextprotocol - 소스코드, SDK, 예제
- Anthropic MCP 발표 블로그 - anthropic.com/news/model-context-protocol - 2024년 11월 최초 발표
- OpenAI MCP 채택 발표 - openai.com/index/new-tools-for-building-agents - 2025년 3월
- Google ADK MCP 지원 - google.github.io/adk-docs - Agent Development Kit 문서
- Linux Foundation AAIF 기부 발표 - linuxfoundation.org - 2025년 12월
- MCP 1주년 업데이트 - modelcontextprotocol.io/blog - Streamable HTTP, Tool Annotations 등
- FastMCP 공식 문서 - gofastmcp.com - Python MCP 프레임워크
- MCP TypeScript SDK - npmjs.com/package/@modelcontextprotocol/sdk
- MCP Python SDK - pypi.org/project/mcp
- GitHub MCP Server - github.com/github/github-mcp-server
- Cloudflare MCP 배포 가이드 - developers.cloudflare.com/agents/guides/remote-mcp-server
- MCP Inspector - github.com/modelcontextprotocol/inspector
- MCP.so 마켓플레이스 - mcp.so - 커뮤니티 MCP 서버 디렉토리
- Claude Code MCP 문서 - docs.anthropic.com/en/docs/claude-code - MCP 통합 가이드
- MCP 스펙 문서 - spec.modelcontextprotocol.io - 프로토콜 상세 스펙
MCP Complete Guide: Why Model Context Protocol Became the USB-C of AI with 97M Downloads
- What Is MCP: The USB-C of AI
- Architecture Deep Dive
- Why MCP Won
- Building MCP Servers: A Practical Guide
- Major MCP Server Ecosystem
- Claude Code + MCP: Real-World Workflows
- MCP Roadmap Every Developer Should Know
- Practice Quiz
- References
What Is MCP: The USB-C of AI
One Protocol to Connect Them All
Before USB existed, printers needed parallel ports, keyboards needed PS/2 connectors, and cameras required serial ports. Different cables, different drivers, different connection methods for every device. Just as USB ended that chaos, MCP (Model Context Protocol) has created the connectivity standard for the AI world.
MCP is an open standard protocol for AI models to communicate with external data sources, tools, and services. Anthropic released it as open source in November 2024, and in just over a year, it has become the de facto standard of the AI industry.
The World Before MCP: The N x M Problem
Think back to a world without MCP:
- ChatGPT needs to access GitHub data? Requires an OpenAI-specific plugin.
- Claude needs to read Slack messages? Requires an Anthropic-specific integration.
- Gemini needs to query a database? Requires a Google-specific connector.
With N AI models and M external tools, you needed a total of N x M custom integrations. With 5 AI models and 100 external tools, that meant 500 individual integrations.
MCP reduces this problem to N + M. Each AI model only needs to implement one MCP client, and each tool only needs to implement one MCP server. Like USB, just match one end and everything connects.
The Timeline of Explosive Growth
The growth rate of MCP has been extraordinary:
| Date | Event | Significance |
|---|---|---|
| Nov 2024 | Anthropic open-sources MCP | Protocol born |
| Jan 2025 | MCP integrated into Claude Desktop | First major client |
| Mar 2025 | OpenAI adopts MCP in Agents SDK | Competitor adoption, industry standard confirmed |
| Apr 2025 | Google DeepMind supports MCP in Agent Development Kit | Big Three complete |
| Jun 2025 | OAuth 2.0 authentication spec added | Enterprise ready |
| Nov 2025 | MCP 1st anniversary update, enhanced remote server support | Maturity phase |
| Dec 2025 | Donated to Linux Foundation AAIF | Community governance transition |
| Mar 2026 | Monthly SDK downloads surpass 97M | Explosive adoption confirmed |
Combining Python SDK and TypeScript SDK monthly downloads reaches 97 million. The MCP.so marketplace hosts tens of thousands of MCP servers, and searching "MCP server" on GitHub returns thousands of repositories.
The Core Problem MCP Solves
AI models are fundamentally isolated entities. No matter how intelligent a model is, it cannot know information after its training cutoff, cannot access internal company data, and cannot request actions from external systems.
MCP resolves this isolation in three ways:
- Resources: Provides data that AI can read (files, DB records, API responses)
- Tools: Provides functions that AI can execute (API calls, code execution, file creation)
- Prompts: Provides prompt templates optimized for specific tasks
These three elements form the pillars of the MCP protocol. We will examine the architecture in detail in the next section.
Architecture Deep Dive
Client-Server Model
MCP follows a client-server architecture, built on top of the JSON-RPC 2.0 protocol for lightweight and efficient communication.
MCP Architecture Overview
+--------------------------------------------------+
| Host Application |
| (Claude Desktop, VS Code, IDE, Custom App) |
| |
| +--------------+ +--------------+ |
| | MCP Client | | MCP Client | ... |
| | #1 | | #2 | |
| +------+-------+ +------+-------+ |
| | | |
+---------+-----------------+------------------------+
| |
+----v-----+ +----v------+
| MCP | | MCP |
| Server | | Server |
| (Git) | | (Slack) |
+----+-----+ +-----+----+
| |
+----v-----+ +----v------+
| GitHub | | Slack |
| API | | API |
+----------+ +-----------+
Here is a summary of the key components:
- Host: The application running MCP clients (Claude Desktop, VS Code, custom apps)
- Client: A connector within the host that communicates 1:1 with a specific MCP server
- Server: A service that provides data and functionality from external systems in a standardized format
A single host app can run multiple MCP clients simultaneously. For example, Claude Desktop can connect to GitHub MCP server, Slack MCP server, and PostgreSQL MCP server all at the same time.
Three Core Concepts: Resources, Tools, Prompts
Resources
Resources are read-only data that MCP servers provide to clients. They are identified by URIs.
{
"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"
}
]
}
Resources enrich the context of AI models. Code files, database schemas, API documentation, configuration files -- any data that AI needs to reference can be provided as resources.
Tools
Tools are executable functions that AI models can invoke. Think of them as a standardized version of function calling.
{
"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"]
}
}
]
}
AI models inspect the list of available tools and select the appropriate one based on the user's request. Results are fed back to the model for response generation.
Prompts
Prompts are reusable prompt templates optimized for specific tasks.
{
"prompts": [
{
"name": "code-review",
"description": "Review code for best practices and potential issues",
"arguments": [
{
"name": "language",
"description": "Programming language",
"required": true
}
]
}
]
}
Through prompts, domain experts can craft optimal instructions and distribute them via MCP servers.
Transport: Local vs Remote
MCP supports two transport mechanisms:
stdio (Standard Input/Output)
- Runs the MCP server as a local process
- Exchanges JSON-RPC messages via stdin/stdout
- Simple setup with high security
- Ideal for personal development environments
Streamable HTTP (formerly SSE)
- Communicates with remote servers over HTTP
- Evolved from SSE to Streamable HTTP in the November 2025 update
- Ideal for team/organization-wide sharing
- Deployable to Cloudflare, AWS, and more
Transport Comparison
stdio (Local) Streamable HTTP (Remote)
+----------+ stdin/stdout +----------+
| Client |<------------------->| Server |
+----------+ (local process) +----------+
+----------+ HTTP/HTTPS +----------+
| Client |<------------------->| Server |
+----------+ (network) +----------+
Authentication: OAuth 2.0
The authentication spec added in June 2025 was a critical update enabling enterprise adoption of MCP.
- Standardized OAuth 2.0 authentication flow
- Token-based permission management
- Fine-grained scope control
- Integration with existing Identity Providers (IdP)
This enables organizations to systematically manage which AI models can access which data.
Protocol Lifecycle
The lifecycle of an MCP connection proceeds as follows:
- Initialization: Client connects to server, negotiates protocol version and supported capabilities
- Discovery: Client queries the server for lists of resources, tools, and prompts
- Execution: Tool calls and resource reads are performed based on AI model requests
- Shutdown: Connection cleanup and resource release
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-11-05",
"capabilities": {
"tools": {},
"resources": {},
"prompts": {}
},
"clientInfo": {
"name": "claude-desktop",
"version": "1.0.0"
}
}
}
Why MCP Won
Fundamental Solution to the N x M Problem
As described earlier, the N x M problem was the biggest inefficiency in the AI ecosystem.
Before MCP: N x M Integrations
AI Models External Tools
+---------+ +---------+
| ChatGPT |-------| GitHub |
| |--+ +--| |
+---------+ | | +---------+
+---------+ | | +---------+
| Claude |--+-+--| Slack |
| |--+-+--| |
+---------+ | | +---------+
+---------+ | | +---------+
| Gemini |--+ +--| DB |
| |-------| |
+---------+ +---------+
= 3 x 3 = 9 integrations needed
After MCP: N + M Integrations
AI Models MCP External Tools
+---------+ +-----+ +---------+
| ChatGPT |---| |---| GitHub |
+---------+ | | +---------+
+---------+ | MCP | +---------+
| Claude |---| |---| Slack |
+---------+ | Pro | +---------+
+---------+ | to | +---------+
| Gemini |---| |---| DB |
+---------+ | col | +---------+
+-----+
= 3 + 3 = only 6 integrations needed
This efficiency becomes more dramatic as the ecosystem grows. With 10 AI models and 1,000 external tools, you need only 1,010 integrations instead of 10,000.
OpenAI Adoption: Accepting a Standard Built by a Competitor
In March 2025, OpenAI announced MCP support in their Agents SDK, which sent shockwaves through the industry. The largest competitor had adopted a protocol created by Anthropic.
Sam Altman noted that open standards benefit all participants, and that they want agents to have access to more tools.
The rationale behind this decision was pragmatic:
- The existing MCP ecosystem could not be ignored
- Creating a proprietary protocol would fragment the ecosystem
- Developers were already building MCP servers
- Standardization grows the entire market, benefiting everyone
Google DeepMind Joins
In April 2025, Google announced MCP support in their Agent Development Kit (ADK). With this, all three major AI companies now supported MCP.
Google joining confirmed that MCP had transitioned from a single company's project to an industry-wide standard.
Linux Foundation Donation: Community Governance
In December 2025, Anthropic donated MCP to the Linux Foundation's AI and Data Foundation (AAIF). This was a pivotal decision:
- Neutrality: The community, not a single company, manages the standard
- Sustainability: The protocol evolves independently of Anthropic's business direction
- Trust: Competitors can confidently participate
- Governance transparency: Open decision-making processes
This follows the same path as successful open-source projects like Linux, Kubernetes, and Node.js.
MCP vs Function Calling vs LangChain Tools
| Aspect | MCP | Function Calling | LangChain Tools |
|---|---|---|---|
| Standardization | Open protocol | Vendor-specific spec | Library-level abstraction |
| Reusability | Build once, use with any AI | Vendor-locked | LangChain ecosystem only |
| Transport | stdio, Streamable HTTP | HTTP API | In-process |
| Discovery | Dynamic tool/resource discovery | Pre-defined required | Pre-defined required |
| Authentication | OAuth 2.0 standard | Vendor-specific | Custom implementation |
| State Management | Protocol-level support | None | Library-level |
| Ecosystem Size | Tens of thousands of servers | Vendor-specific plugins | Hundreds of tools |
The biggest differentiator of MCP is vendor independence. An MCP server built once works with Claude, ChatGPT, Gemini, open-source LLMs, or any other AI model.
Building MCP Servers: A Practical Guide
Building a Python Server with FastMCP
FastMCP is a framework for quickly building MCP servers in Python. Let us build a simple weather information server.
# Install packages
pip install fastmcp httpx
# weather_server.py
from fastmcp import FastMCP
import httpx
import json
# Create MCP server
mcp = FastMCP("weather-server")
# Resource: List of supported cities
@mcp.resource("weather://cities")
def list_cities() -> str:
"""Returns the list of available cities."""
cities = [
"seoul", "tokyo", "new-york",
"london", "paris", "berlin"
]
return json.dumps(cities)
# Tool: Get weather
@mcp.tool()
async def get_weather(city: str) -> str:
"""
Fetches current weather information for a specified city.
Args:
city: City name (e.g., 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"]
})
# Tool: Get forecast
@mcp.tool()
async def get_forecast(city: str, days: int = 3) -> str:
"""
Fetches weather forecast for a specified city.
Args:
city: City name
days: Number of forecast 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)
# Prompt: Weather briefing
@mcp.prompt()
def weather_briefing(city: str) -> str:
"""Prompt for city weather briefing"""
return f"""Analyze the weather information for the following city and provide a briefing:
City: {city}
Please include:
1. Current temperature and feels-like temperature
2. Humidity and wind conditions
3. 3-day forecast summary
4. Recommendations for going out (umbrella, jacket, etc.)
"""
if __name__ == "__main__":
mcp.run()
Once running, this server can be immediately connected from Claude Desktop or any other MCP client.
# Test directly
python weather_server.py
Building a Server with the TypeScript SDK
If you prefer TypeScript, you can use the official SDK.
# Initialize project
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',
})
// In-memory todo store
interface TodoItem {
id: string
title: string
completed: boolean
createdAt: string
}
const todos: Map<string, TodoItem> = new Map()
// Tool: Add todo
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),
},
],
}
}
)
// Tool: List todos
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),
},
],
}
})
// Tool: Complete todo
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),
},
],
}
}
)
// Resource: Todo stats
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),
},
],
}
})
// Start server
async function main() {
const transport = new StdioServerTransport()
await server.connect(transport)
console.error('Todo MCP Server running on stdio')
}
main().catch(console.error)
Debugging with MCP Inspector
MCP Inspector is the official tool for testing and debugging MCP servers.
# Run Inspector
npx @modelcontextprotocol/inspector python weather_server.py
When running Inspector, you can perform the following in the browser:
- View the list of tools, resources, and prompts offered by the server
- Directly invoke each tool and inspect the results
- Watch JSON-RPC message logs in real time
- Debug error messages
Inspector is an essential tool during development. It lets you verify that the server works correctly before connecting any client.
Deploying a Remote Server to Cloudflare
Once local verification is complete, you can deploy remotely. Cloudflare Workers is particularly well-suited for MCP server deployment.
# Start with the Cloudflare MCP server template
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')
},
}
# Deploy
npx wrangler deploy
After deployment, you can connect to the MCP server from anywhere via Streamable HTTP. An entire team can share a single remote MCP server.
Major MCP Server Ecosystem
GitHub MCP Server
The official GitHub MCP server is one of the most popular MCP servers.
Available tools:
- Repository search and browsing
- Issue creation, viewing, and editing
- Pull request creation and review
- Code search (regex support)
- Branch management
- File read/write
Claude Desktop configuration example:
{
"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"
}
}
}
}
Google Drive / Docs MCP
An MCP server connecting Google Workspace with AI.
Key features:
- Google Drive file search
- Google Docs content reading
- Google Sheets data retrieval
- File metadata queries
Slack MCP
Connects the team communication tool Slack with AI.
Key features:
- Channel message reading
- Message search
- Channel listing
- Thread context awareness
Database MCP (PostgreSQL, MySQL)
Enables AI to directly access databases for querying and analysis.
Key features:
- SQL query execution (read-only mode supported)
- Schema exploration
- Table listing and column information
- Query result analysis
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://user:password@localhost:5432/mydb"
]
}
}
}
Filesystem MCP
A basic MCP server providing access to the local file system.
Key features:
- File/directory reading
- File search (glob patterns)
- File creation/modification
- Directory structure exploration
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/projects"]
}
}
}
Brave Search MCP
Provides web search capabilities to AI, enabling it to search for and leverage the latest information.
Key features:
- Web search
- News search
- Search result summarization
- Domain filtering
Beyond these, tens of thousands of MCP servers are available on the MCP.so marketplace and GitHub. MCP servers exist for virtually every major service including Notion, Jira, Linear, Figma, AWS, and GCP.
Claude Code + MCP: Real-World Workflows
Connecting MCP Servers in Claude Code
Claude Code is Anthropic's CLI-based AI coding tool with native MCP support.
# Add MCP server (project scope)
claude mcp add github -- docker run -i --rm \
-e GITHUB_PERSONAL_ACCESS_TOKEN \
ghcr.io/github/github-mcp-server
# Add MCP server (global scope)
claude mcp add --scope user postgres -- \
npx -y @modelcontextprotocol/server-postgres \
postgresql://localhost:5432/mydb
# List registered MCP servers
claude mcp list
# Remove a specific MCP server
claude mcp remove github
You can also add servers directly to the Claude Code configuration file:
{
"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"]
}
}
}
Real-World Example: From DB Query to PR Creation
The true power of MCP emerges when you combine multiple servers. Let us walk through a real workflow.
Scenario: "Add a last_login_at column to the users table, create a migration, and open a PR."
For this single request, Claude Code operates as follows:
- Queries the current users table schema via the PostgreSQL MCP server
- Analyzes the existing schema and writes migration SQL
- Creates the migration file via the Filesystem MCP server
- Updates related model code
- Creates a branch, commits, and opens a PR via the GitHub MCP server
The entire process happens automatically within a single conversation. The developer only needs to review the final PR.
Another scenario: "Summarize today's bug reports from Slack and create GitHub issues."
- Searches today's channel messages via the Slack MCP server
- Filters and summarizes bug-related messages
- Creates issues via the GitHub MCP server (with auto-assigned labels and assignees)
MCP is the critical infrastructure that enables AI agents to actually perform work.
MCP Server Debugging Tips
Useful debugging methods when MCP server connections have issues in Claude Code:
# Check MCP server status
claude mcp list
# Check server logs (for Claude Desktop)
# macOS: ~/Library/Logs/Claude/
# Windows: %APPDATA%/Claude/logs/
# Independent testing with Inspector
npx @modelcontextprotocol/inspector your-server-command
Common issues and solutions:
| Symptom | Cause | Solution |
|---|---|---|
| Server not connecting | Executable path error | Use absolute paths, verify with which command |
| Tools not appearing | Initialization failure | Test server independently with Inspector |
| Timeout errors | Server response delay | Check async handling, adjust timeout settings |
| Authentication failure | Token expired/invalid | Reset environment variables |
MCP Roadmap Every Developer Should Know
2024-2025 Key Milestones
November 2024 - Birth
Anthropic released MCP as open source. Initially it was for Claude Desktop only, but it was designed as an open protocol that anyone could implement.
March 2025 - OpenAI Adoption
OpenAI announced MCP support in their Agents SDK. This was the turning point where MCP transcended being a single company's project and established itself as an industry standard.
June 2025 - Authentication Spec Added
OAuth 2.0-based authentication was added to the MCP specification, enabling safe enterprise use.
- Token-based authentication flows
- Fine-grained permission (scope) management
- Integration with existing Identity Providers (IdP)
- Audit log support
November 2025 - First Anniversary Major Update
Major updates were announced for MCP's first anniversary:
- Streamable HTTP: A more efficient remote communication method replacing the previous SSE transport
- Tool Annotations: Explicit declaration of tool side effects
- Elicitation: Ability for servers to request additional information from users during execution
- Structured Output: Defining schemas for tool outputs
December 2025 - Linux Foundation Donation
MCP was donated to the Linux Foundation's AI and Data Foundation (AAIF). This transitioned MCP's governance from Anthropic alone to community-driven.
2026 Outlook
Inter-Agent MCP Communication
Currently, MCP is primarily used for communication between AI models and external tools. In 2026, it is expected to expand to inter-agent communication.
Current: AI Model -> MCP -> External Tool
Future: AI Agent A -> MCP -> AI Agent B
For example, a coding agent could request test execution from a testing agent via MCP, and the testing agent returns results via MCP.
Multimodal MCP
The ability to transmit images, audio, and video through MCP (not just text) is expected to expand. Some MCP servers already support image resources, and this trend will accelerate.
Enterprise MCP Gateway
Gateway solutions for centrally managing MCP server access in large enterprise environments are emerging:
- Centralized authentication/authorization
- Usage monitoring and rate limiting
- Audit logs
- Policy-based access control
MCP Registry
An official registry for discovering and installing MCP servers -- similar to npm or PyPI -- is anticipated. Currently MCP.so serves as an unofficial marketplace, but after the Linux Foundation donation, an official registry is being discussed.
Practice Quiz
Test your understanding of MCP.
Q1. What is the "N x M problem" that MCP solves?
Answer: When connecting N AI models to M external tools, a custom integration is needed for each combination, requiring N x M total integrations. MCP provides a standard protocol that reduces this to N + M. Each AI model implements just one MCP client, and each tool implements just one MCP server.
Q2. Explain the differences between MCP's three core concepts: Resources, Tools, and Prompts.
Answer:
- Resources: Read-only data that AI can access. Provides context through files, DB schemas, API responses, etc. Identified by URIs.
- Tools: Executable functions that AI can invoke. Performs actions like API calls, data creation/modification, and external system operations.
- Prompts: Reusable prompt templates optimized for specific tasks. Domain experts can create and distribute optimal instructions.
In short: Resources are for "reading," Tools are for "executing," and Prompts are for "guiding."
Q3. Why did OpenAI adopt MCP, a protocol created by their competitor Anthropic?
Answer: It was a pragmatic decision. First, the existing MCP ecosystem could not be ignored. Second, creating a proprietary protocol would fragment the ecosystem, harming everyone. Third, developers were already building MCP servers, and network effects were in motion. Fourth, standardization grows the entire market, ultimately benefiting OpenAI as well. This follows the same logic as web browsers adopting W3C standards.
Q4. When are MCP's two transport mechanisms (stdio vs Streamable HTTP) each appropriate?
Answer:
- stdio (Standard I/O): Best for local development environments. Runs the MCP server as a local process, communicating via stdin/stdout. Simple setup, no network required, and high security. Used by individual developers or single-machine environments.
- Streamable HTTP: Best for remote/team environments. Communicates over HTTP, so it can be deployed to Cloudflare, AWS, etc. for the entire team to share. Enables authentication, access control, and monitoring.
Q5. Why is it significant that MCP was donated to the Linux Foundation?
Answer: The Linux Foundation donation is a critical decision for MCP's long-term success. First, neutrality is guaranteed as the community, not a single company, manages the standard. Second, the protocol's sustainability is ensured regardless of changes in Anthropic's business direction. Third, trust is strengthened as competitors can confidently participate. Fourth, governance transparency is secured through open decision-making processes. This follows the proven path of successful open-source projects like Linux, Kubernetes, and Node.js.
References
- MCP Official Site - modelcontextprotocol.io - Spec, documentation, quickstart guides
- MCP GitHub Repository - github.com/modelcontextprotocol - Source code, SDKs, examples
- Anthropic MCP Announcement Blog - anthropic.com/news/model-context-protocol - November 2024 initial release
- OpenAI MCP Adoption Announcement - openai.com/index/new-tools-for-building-agents - March 2025
- Google ADK MCP Support - google.github.io/adk-docs - Agent Development Kit documentation
- Linux Foundation AAIF Donation Announcement - linuxfoundation.org - December 2025
- MCP 1st Anniversary Update - modelcontextprotocol.io/blog - Streamable HTTP, Tool Annotations, etc.
- FastMCP Official Docs - gofastmcp.com - Python MCP framework
- MCP TypeScript SDK - npmjs.com/package/@modelcontextprotocol/sdk
- MCP Python SDK - pypi.org/project/mcp
- GitHub MCP Server - github.com/github/github-mcp-server
- Cloudflare MCP Deployment Guide - developers.cloudflare.com/agents/guides/remote-mcp-server
- MCP Inspector - github.com/modelcontextprotocol/inspector
- MCP.so Marketplace - mcp.so - Community MCP server directory
- Claude Code MCP Docs - docs.anthropic.com/en/docs/claude-code - MCP integration guide
- MCP Spec Documentation - spec.modelcontextprotocol.io - Detailed protocol specification