MCP 서버 직접 만들기 — Claude·Cursor 연동 7단계 실전 가이드 2026년 5월

MCP 서버, 5월부터 한국 개발자 본업 자동화의 핵심

Model Context Protocol(MCP)이 2024년 11월 첫 발표 이후 1년 반 만에 ‘AI 자동화 표준’으로 자리잡았어요. 5월 시점 Claude·Cursor·VS Code·Cline·OpenAI 등 호스트가 모두 MCP 지원하고 공개 서버 1만+ 개가 있어요.

저도 5월 1주차부터 회사 내부 API 래퍼 MCP 서버를 직접 만들어봤는데 ‘1시간 작업으로 매일 30분 자동화’ 효과가 진짜 컸어요. 이번 글에서는 MCP 서버를 직접 만들어 Claude·Cursor에 연동하는 7단계 가이드를 한국 개발자 입장에서 정리하고, 5월 신규 transport 변경 사항까지 짚어드릴게요.

1단계 — Python SDK 설치 + 기본 서버 스켈레톤

5월 기준 공식 SDK 중 가장 빠른 진입이 Python. pip install mcp 한 줄로 끝.

# server.py
from mcp.server import Server
from mcp.types import Tool, TextContent

app = Server("my-korean-api-server")

@app.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="get_invoice",
            description="한국 PG에서 인보이스 조회. 거래 ID를 입력하면 결제 정보를 반환합니다.",
            inputSchema={
                "type": "object",
                "properties": {
                    "transaction_id": {"type": "string"}
                },
                "required": ["transaction_id"]
            }
        )
    ]

@app.call_tool()
async def call_tool(name, arguments):
    if name == "get_invoice":
        # 실제 API 호출 로직
        result = fetch_korean_pg(arguments["transaction_id"])
        return [TextContent(type="text", text=str(result))]

함수명·description 명확하게 적는 게 중요. AI가 이 description 보고 ‘언제 이 도구 써야 하나’ 판단해요. 한국 개발자가 자주 마주치는 함정이 ‘description 한 줄로 끝내기’ 패턴인데, 짧으면 AI가 이 도구를 언제 호출해야 하는지 헷갈려서 ‘다른 도구로 잘못 호출’ 사고가 발생해요. 자세히 적을수록 정확도가 올라가니까 description 3~5문장 분량으로 작성하는 게 본전 분기 가장 좋아요.

2단계 — 입력 검증·에러 처리

MCP 서버에서 가장 자주 발생하는 사고가 ‘AI가 잘못된 인자 전달 → 서버 크래시’. 입력 검증 + 에러 처리 필수.

import pydantic

class GetInvoiceInput(pydantic.BaseModel):
    transaction_id: str = pydantic.Field(min_length=8, max_length=64)

@app.call_tool()
async def call_tool(name, arguments):
    if name == "get_invoice":
        try:
            input = GetInvoiceInput(**arguments)
            result = fetch_korean_pg(input.transaction_id)
            return [TextContent(type="text", text=str(result))]
        except pydantic.ValidationError as e:
            return [TextContent(type="text", text=f"입력 오류: {e}")]
        except Exception as e:
            return [TextContent(type="text", text=f"서버 오류: {e}")]

한국 사용자가 자주 마주치는 케이스가 ‘한국어 transaction_id 인코딩 오류’. UTF-8 명시 + pydantic 검증으로 안전하게 처리 가능. 한국 PG 거래 ID에는 한글이 포함되는 경우는 거의 없지만 클라이언트 ID·고객 이름 같은 필드에는 한글이 자주 들어가기 때문에 모든 문자열 입력은 무조건 UTF-8 인코딩 명시 + 검증 두 단계 거치는 게 안전한 분기예요.

3단계 — Streamable HTTP transport 설정 (5월 신규)

5월 업데이트로 SSE → Streamable HTTP 표준 전환. 신규 서버는 Streamable HTTP 권장.

from mcp.server.streamable_http import StreamableHTTPServer

if __name__ == "__main__":
    server = StreamableHTTPServer(app, host="0.0.0.0", port=8080)
    server.start()

기존 SSE 서버는 6월말까지 마이그 권장. 한국 개발자가 5월 신규 서버 만든다면 처음부터 Streamable HTTP로 시작하는 게 안전. 수평 확장·무상태·세션 안정성 모두 우수.

Streamable HTTP가 SSE 대비 우수한 점이 ‘여러 서버 인스턴스 동시 운영 가능’이라는 점이에요. 한 회사에서 여러 팀이 MCP 서버를 공유할 때 ‘세션 상태가 한 인스턴스에만 묶이는 SSE’는 인스턴스가 죽으면 모든 세션 끊김 사고가 나는데, Streamable HTTP는 어느 인스턴스로 가도 같은 처리 가능해서 운영 안정성이 훨씬 좋아요.

4단계 — Claude Desktop 등록

claude_desktop_config.json 편집. 위치는 macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\\Claude\\.

{
  "mcpServers": {
    "korean-api": {
      "command": "python",
      "args": ["/path/to/server.py"],
      "env": {
        "KOREAN_PG_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Desktop 재시작 후 자동 인식. 5월 GUI 메뉴 추가돼서 코드 편집 없이 ‘설정 → MCP 서버’ 메뉴에서도 등록 가능.

한국 사용자가 처음 등록 시 자주 하는 실수가 환경변수 누락이에요. 서버 코드 안에서 os.environ["KOREAN_PG_API_KEY"] 같이 환경변수를 읽는다면 설정 파일의 env 객체에 반드시 명시해야 작동해요. 빠진 채로 등록하면 ‘서버 시작은 됐는데 도구 호출 시 키 없음 에러’가 발생해서 디버깅 시간이 의외로 오래 걸리니까 처음부터 env 명시 습관 들이는 게 안전합니다.

5단계 — Cursor·VS Code 동시 등록

같은 MCP 서버를 여러 호스트에서 동시 사용 가능.

Cursor는 .cursor/mcp.json.

{
  "mcpServers": {
    "korean-api": {
      "command": "python",
      "args": ["/path/to/server.py"]
    }
  }
}

VS Code Copilot은 .vscode/mcp.json 또는 settings.json. 한 번 만든 MCP 서버는 호스트 종속 없이 5곳 동시 사용 가능. 한국 개발자가 ‘회사 PC = VS Code, 개인 PC = Claude Desktop’ 다른 환경 운영해도 같은 서버 그대로.

6단계 — 보안·인증 (5월 OAuth 2.1)

5월 업데이트로 OAuth 2.1·.well-known 메타데이터 표준화. 외부 공개 MCP 서버는 OAuth 필수.

from mcp.server.auth import OAuthMiddleware

app.add_middleware(OAuthMiddleware(
    issuer="https://your-oauth-provider.com",
    audience="korean-api-server",
    jwks_url="https://your-oauth-provider.com/.well-known/jwks.json"
))

회사 내부용 서버는 ‘VPN 또는 사내망 한정’ 운영이 추가로 안전. 5월 한국 회사에서 자주 굴리는 패턴은 ‘VPN 한정 + Bearer 토큰 발급’ 2중 보안.

특히 금융·의료·공공 영역 회사라면 ‘MCP 서버 자체를 사내 서버에만 배포 + 인터넷 노출 금지’ 정책이 5월 시점 한국 컴플라이언스 표준이에요. 클라우드 배포는 데이터 국외 이전 동의 절차가 필요해서 행정 비용이 크고, 사내 서버 배포는 한 번 셋업해두면 추가 비용 거의 없이 안정적으로 운영 가능해요. 도커 컴포즈 한 줄로 사내 서버에 띄울 수 있으니까 인프라 부담도 작아요.

7단계 — 모니터링·로그

모든 호출 로그 저장 + 비정상 패턴 알람. Sentry·DataDog 통합 권장.

import logging
from datetime import datetime

logger = logging.getLogger("mcp_audit")

@app.call_tool()
async def call_tool(name, arguments):
    logger.info({
        "timestamp": datetime.now().isoformat(),
        "tool": name,
        "arguments_hash": hash(str(arguments)),
        "user": get_authenticated_user()
    })
    # ... actual logic

n8n과 Claude API 자동화 5단계 글에서 비슷한 자동화 패턴을 더 깊이 다뤘으니 참고하세요.

한국 본업 자동화 활용 패턴 5가지

5월 시점 한국 개발자가 만든 MCP 서버 인기 패턴.

가장 본전 분기 빠른 게 ‘사내 봇 통합’. 한 번 만들어두면 매주 10시간 절감 효과가 누적돼서 한 분기 후 100~150시간 절감 보고돼요.

한국 IT 회사에서 자주 마주치는 자동화 영역이 ‘반복적인 데이터 조회 → 슬랙 보고’ 패턴이에요. 매일 오전 마케팅팀이 ‘어제 광고 성과 데이터 정리’, 개발팀이 ‘어제 발생한 에러 로그 정리’, 운영팀이 ‘어제 결제 실패 건수 정리’ 같이 반복 작업을 수동으로 처리하는 경우가 많은데, MCP 서버 한 번 만들어두면 ‘슬랙에 명령 한 줄’로 자동 처리 가능해요. 5월 시점 한국 IT 스타트업 30% 이상이 이런 자동화 패턴을 도입하기 시작했어요.

본업 자동화 ROI를 정확히 계산해보면 회사 직원 시급 평균 3만 원 기준 주 10시간 절감 = 주 30만 원 = 월 120만 원 가치예요. MCP 서버 1개 만드는 데 1~2일 작업이면 1주일 안에 본전 회수가 끝나는 셈이라 의사결정 명확. 인프라 비용도 거의 0원이라 도입 부담 없어요.

5월 신규 변경 사항 정리

5월 업데이트로 바뀐 항목 정리.

• transport: SSE → Streamable HTTP (수평 확장 가능)
• 인증: OAuth 2.1 + .well-known 메타데이터 표준화
• transport 발견: 메타데이터 표준화로 ‘라이브 연결 없이도 서버 능력 확인 가능’
• Resources: 5월 정식 GA. ‘툴 실행 없이 데이터 읽기’ 가능
• Prompts: 5월 정식 GA. ‘재사용 가능 프롬프트 템플릿’ 공유

기존 SSE 서버 운영 중이라면 6월말까지 Streamable HTTP 마이그 권장. 마이그 자체는 SDK 업그레이드 + 한 줄 변경이라 30분 작업.

추가로 ‘Resources GA’ 변경 사항이 한국 사용자에게 중요한 의미예요. Resources는 ‘툴 실행 없이 데이터 읽기’ 가능한 기능인데, 5월 정식 출시로 인해 ‘회사 내부 문서 검색 → AI가 자동으로 컨텍스트로 활용’ 패턴이 안정화됐어요. 이전에는 ‘툴 호출 → 답변 받기 → 다시 LLM에 전달’ 2단계 거쳤는데 Resources 사용 시 한 번에 처리. 응답 속도가 평균 30~50% 빨라져요.

Prompts GA도 큰 의미예요. ‘재사용 가능 프롬프트 템플릿’을 MCP 서버에 등록해두면 여러 호스트에서 공유 가능. 한국 회사에서 ‘회의록 요약 템플릿’, ‘이슈 보고 템플릿’, ‘외주 견적 템플릿’ 같이 자주 쓰는 프롬프트를 MCP 서버에 모아두면 팀 전체가 같은 표준으로 작업 가능. 품질 일관성 효과가 정말 큰 변화예요.

흔한 실수 5가지

실수 1 — Tool description 모호하게 작성 ‘API 호출 도구’ 같이 모호하면 AI가 언제 호출할지 판단 못 함. ‘한국 PG에서 거래 ID로 인보이스 조회’ 같이 명확하게.

실수 2 — 입력 검증 누락 잘못된 인자 → 서버 크래시 → AI가 무한 재시도 사고. pydantic 검증 필수.

실수 3 — 인증 없이 외부 공개 인증 없으면 누구나 호출 가능. OAuth 2.1 또는 Bearer 토큰 필수.

실수 4 — 로그 없음 어떤 도구가 언제 호출됐는지 추적 불가. 감사·디버깅 어려워요. 모든 호출 로그 저장 필수.

실수 5 — SSE 마이그 미준비 6월말까지 Streamable HTTP 전환 안 하면 신규 호스트에서 안 될 수 있어요. 5월 안에 마이그 시작 권장.

마무리 — 지금 당장 할 수 있는 액션

5월 16일 시점 추천 액션 순서는 이래요.

먼저 Python pip install mcp 또는 TypeScript npm install @modelcontextprotocol/sdk 한 줄 설치. 5분이면 끝나요. SDK 설치 후 공식 예제 폴더에 ‘Hello World 서버’ 5분 만에 만들 수 있는 템플릿 있으니까 그거 따라 해보는 게 가장 빠른 진입 분기예요.

다음 가장 간단한 ‘REST API 래퍼 MCP 서버’ 한 개 만들기. 회사 내부 API 1개 골라서 30분~1시간 작업. 처음은 read-only 도구 한 개만. 입력 검증·에러 처리·로그 세 가지만 챙기면 안전. write·delete 권한은 두 번째 서버부터 추가하고 첫 서버는 read-only로 시작해서 안정성 확인하는 게 본전 분기 안전한 진행 순서예요.

만든 서버를 Claude Desktop·Cursor 두 곳에 등록. 5월 GUI 메뉴 추가됐으니 코드 편집 없이 GUI에서 등록 가능. 등록 후 Claude 채팅에 ‘[도구명] 써서 X 처리해줘’ 한 줄로 테스트. 정상 작동 확인되면 동료에게 ‘이거 등록하면 너도 쓸 수 있어’ 공유 가능해서 팀 단위로 자동화 효과 확산되는 패턴이 자연스럽게 시작돼요.

작동 확인되면 ‘회사 내부 자동화 패턴 5가지’ 중 하나 골라서 본격 운영. 사내 봇 통합·한국 PG·Jira 자동화 셋 중 본인 본업 절감 효과 가장 큰 것부터 시작. 한 번 운영 안정화되면 다른 영역으로 자연스럽게 확장되니까 처음부터 욕심 부리지 마시고 한 가지 영역에 집중하는 게 본전 분기 안전한 진행 패턴이에요.

5월 신규 Streamable HTTP·OAuth 2.1·Resources·Prompts 네 가지 변경 사항 숙지. 새 서버는 처음부터 신규 표준으로 만드는 게 6월 이후 안정성 가장 좋아요. 한 번 구버전 패턴으로 만들어두면 마이그 부담이 누적되니까 처음부터 최신 표준 적용이 본전 분기 안전. 기존 SSE 서버 운영 중이라면 5월 안에 마이그 시작 권장. 6월 들어가면 호스트별 SSE 호환성이 점점 떨어지니까 미루지 마시고 5월 안에 진행이 안전한 분기예요.

6월에는 MCP 1.0 정식 발표·엔터프라이즈 SSO 통합·게이트웨이 표준화 예정이라 ‘회사 본업 자동화에 정식 도입’ 시점이 6~7월. 5월에 미리 익숙해두면 회사에 도입 제안할 때 본인이 리더 역할 가능해요. 본전 회수가 굉장히 빠른 영역이라 망설이지 마시고 시작하세요.

한국 시니어 개발자 입장에서 MCP는 ‘AI 시대의 인프라 표준 잡기’ 기회예요. 2010년대 초반 도커가 표준화될 때 일찍 익힌 분들이 데브옵스 영역 리더가 됐던 것처럼, MCP도 비슷한 흐름이에요. 5월~6월 미리 익숙해두면 한 분기 후 회사 인프라 변화 시점에 자연스러운 리더 자리에 설 수 있어요. 본업 자동화 ROI도 있고 커리어 ROI도 큰 영역이라 두 마리 토끼 잡는 분기예요.