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만+ 개가 있어요.

저도 회사 내부 API 래퍼 MCP 서버를 직접 만들어봤는데, 한 번 만들어두니 매번 손으로 하던 조회 작업을 채팅 한 줄로 끝낼 수 있어서 체감 효과가 컸어요. 이번 글에서는 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 권장.

transport는 별도 서버 클래스를 직접 만드는 방식이 아니라 서버를 실행할 때 지정하는 방식이에요. Python SDK의 FastMCP를 쓰면 이렇게 됩니다.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-korean-api-server")

if __name__ == "__main__":
    mcp.run(transport="streamable-http")

호스트·포트 같은 세부 옵션과 저수준 Server 객체를 쓸 때의 배선 방법은 SDK 버전마다 조금씩 달라지니 설치한 버전의 공식 문서를 한 번 확인하고 맞추는 게 안전해요. 신규 서버라면 처음부터 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 재시작 후 자동 인식. 앱 버전에 따라 설정 화면에서 서버를 등록하는 경로가 제공되기도 하니, 설정 메뉴를 먼저 확인해보고 없으면 JSON을 직접 편집하면 돼요.

한국 사용자가 처음 등록 시 자주 하는 실수가 환경변수 누락이에요. 서버 코드 안에서 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 필수.

인증을 어디에 붙일지는 두 갈래예요. 첫째, SDK가 제공하는 인증 기능을 쓰는 방식. 이 부분은 SDK 버전에 따라 제공 형태와 이름이 계속 달라지고 있어서, 설치한 버전의 공식 문서에서 인증 항목을 직접 확인하고 맞추는 게 정확해요. 둘째, 서버 앞단에 리버스 프록시나 API 게이트웨이를 두고 거기서 토큰을 검증한 뒤 통과된 요청만 MCP 서버로 넘기는 방식. 사내 인프라에 이미 게이트웨이가 있다면 두 번째가 손이 덜 가고 SDK 업그레이드 영향도 안 받아요.

발급자·오디언스·서명 키 위치 세 가지는 어느 방식을 택하든 결국 설정해야 하는 값이니, 인증 서버 쪽 메타데이터 주소를 먼저 확보해두면 진행이 빨라집니다.

회사 내부용 서버는 ‘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 서버 인기 패턴.

절감 체감은 그 업무를 얼마나 자주 반복하느냐에 달렸으니 본인 상황에 대입해서 보세요. 가장 본전 분기 빠른 게 ‘사내 봇 통합’. 한 번 만들어두면 팀원 전체가 같이 쓰기 때문에 개인 단위 자동화보다 효과가 빠르게 누적돼요.

한국 IT 회사에서 자주 마주치는 자동화 영역이 ‘반복적인 데이터 조회 → 슬랙 보고’ 패턴이에요. 매일 오전 마케팅팀이 ‘어제 광고 성과 데이터 정리’, 개발팀이 ‘어제 발생한 에러 로그 정리’, 운영팀이 ‘어제 결제 실패 건수 정리’ 같이 반복 작업을 수동으로 처리하는 경우가 많은데, MCP 서버 한 번 만들어두면 ‘슬랙에 명령 한 줄’로 자동 처리 가능해요. 이런 반복 보고 업무는 회사 규모와 상관없이 어디서나 나오기 때문에 MCP 서버 도입 효과가 가장 먼저 체감되는 영역이에요.

본업 자동화 ROI 계산은 단순해요. 그 업무를 한 주에 몇 번 반복하는지 세고 회당 걸리는 시간을 곱한 다음 본인 시급을 대입하면 끝. MCP 서버 1개 만드는 데 1~2일 작업이라, 매일 반복하던 업무라면 회수 기간이 아주 짧게 잡히니까 의사결정이 명확해져요. 인프라 비용도 거의 들지 않아서 도입 부담이 없고요.

5월 신규 변경 사항 정리

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

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

기존 SSE 서버 운영 중이라면 여유 있을 때 Streamable HTTP 마이그를 준비해두는 게 좋아요. 마이그 자체는 SDK 업그레이드와 transport 지정 변경 수준이라 부담이 크지 않아요.

추가로 Resources가 한국 사용자에게 의미가 큰 기능이에요. Resources는 ‘툴 실행 없이 데이터 읽기’가 가능한 기능인데, 이를 지원하는 호스트가 늘면서 ‘회사 내부 문서 검색 → AI가 자동으로 컨텍스트로 활용’ 패턴을 쓰기 좋아졌어요. 이전에는 ‘툴 호출 → 답변 받기 → 다시 LLM에 전달’ 2단계를 거쳤는데 Resources를 쓰면 한 번에 처리. 왕복이 줄어드는 만큼 응답도 체감상 빨라져요.

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

흔한 실수 5가지

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

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

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

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

실수 5 — SSE 마이그 미준비 호스트와 SDK가 Streamable HTTP 중심으로 옮겨가는 흐름이라 전환을 계속 미루면 신규 호스트 연동에서 막힐 수 있어요. 여유 있을 때 미리 준비해두세요.

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

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 두 곳에 등록. 설정 메뉴에 등록 경로가 있으면 화면에서, 없으면 설정 파일을 직접 편집하면 돼요. 등록 후 Claude 채팅에 ‘[도구명] 써서 X 처리해줘’ 한 줄로 테스트. 정상 작동 확인되면 동료에게 ‘이거 등록하면 너도 쓸 수 있어’ 공유 가능해서 팀 단위로 자동화 효과 확산되는 패턴이 자연스럽게 시작돼요.

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

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

앞으로는 엔터프라이즈 인증·게이트웨이 쪽 논의가 이어질 분위기라 회사 차원의 정식 도입을 검토한다면 지금 미리 익숙해두는 게 유리해요. 다만 구체적인 로드맵과 발표 일정은 공식 채널에서 직접 확인하시고요. 미리 익혀두면 회사에 도입 제안할 때 본인이 리더 역할 가능해요. 본전 회수가 굉장히 빠른 영역이라 망설이지 마시고 시작하세요.

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