MCP Server 처음부터 개발하기:
AI 도구 호출 완전 가이드

Model Context Protocol(MCP)은 AI 클라이언트와 외부 시스템 간 통신을 표준화하는 개방 프로토콜입니다. JSON-RPC 2.0 위에 양방향 메시지를 교환하며, 아키텍처는 3계층으로 구성됩니다.

Host(호스트)는 Cursor, Claude Desktop, VS Code 등 사용자가 상호작용하는 애플리케이션입니다. MCP Client는 Host 내부에서 각 Server와 1:1 세션을 유지합니다. MCP Server는 Tools, Resources, Prompts를 노출하고 데이터베이스·API·파일 시스템에 연결합니다.

전송 계층에는 STDIO(표준 입출력, 로컬 자식 프로세스)와 HTTP(Streamable HTTP·SSE, 원격·팀 공유) 두 모드가 있습니다. Agent 시작 시 Client가 tools/list를 호출해 런타임에 도구를 발견하므로, REST API처럼 엔드포인트를 하드코딩할 필요가 없습니다.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_knowledge_base",
    "arguments": { "query": "MCP HTTP transport", "limit": 5 }
  },
  "id": 42
}

FastMCP는 Python MCP Server를 데코레이터 기반으로 빠르게 작성하는 프레임워크입니다. pip install fastmcp 후 아래 Hello World로 STDIO Server를 즉시 기동할 수 있습니다.

from fastmcp import FastMCP

mcp = FastMCP("hello-mcp")

@mcp.tool()
def greet(name: str) -> str:
    return f"Hello, {name}! MCP Server is running."

if __name__ == "__main__":
    mcp.run()

Cursor MCP 설정에 python server.py를 등록하고 Agent를 재시작하면 greet 도구가 tools/list에 나타납니다. 실무에서는 아래 5가지 도구 패턴을 조합합니다.

from fastmcp import FastMCP

mcp = FastMCP("company-tools")

@mcp.tool()
def search_knowledge_base(query: str, limit: int = 5) -> list[dict]:
    return [{"title": "MCP Guide", "snippet": "..."}]

@mcp.tool()
def query_database(sql: str) -> str:
    return "[]"

@mcp.tool()
def create_support_ticket(title: str, body: str, idempotency_key: str) -> str:
    return "TICKET-1001"

@mcp.tool()
def send_slack_message(channel: str, text: str) -> str:
    return "ok"

@mcp.tool()
def run_safe_script(script_name: str, args: list[str]) -> str:
    return "done"

Resources는 읽기 전용 컨텍스트를 URI로 노출합니다. Wiki 페이지, 최근 배포 로그, 환경 변수 스냅샷 등 Agent가 참조만 하면 되는 데이터에 적합합니다.

@mcp.resource("wiki://pages/{page_id}")
def get_wiki_page(page_id: str) -> str:
    return "# Architecture\n\n..."

@mcp.resource("logs://deploy/latest")
def get_latest_deploy_log() -> str:
    return "2026-06-16T09:00:00Z deploy succeeded"

Prompts는 반복되는 Agent 지시문을 템플릿으로 묶습니다. 코드 리뷰, 장애 RCA, 릴리스 노트 초안 등 팀 표준 워크플로를 Server에서 중앙 관리할 수 있습니다.

@mcp.prompt()
def code_review(diff: str, language: str) -> str:
    return f"Review this {language} diff:\n\n{diff}"

@mcp.prompt()
def incident_rca(summary: str, timeline: str) -> str:
    return f"Write RCA for:\n{summary}\n\nTimeline:\n{timeline}"

로컬 Cursor 연동에는 STDIO가 가장 단순합니다. 팀 공유·원격 Agent·Docker 배포에는 HTTP 전송이 필요합니다. 2026년 MCP 사양은 Streamable HTTP를 권장하며, SSE 기반 레거시 모드도 호환됩니다.

if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="0.0.0.0", port=8000)

Cursor MCP 설정에서 URL을 http://localhost:8000/mcp로 지정하면 원격 Server에 연결됩니다. 프로덕션에서는 TLS 종료(Nginx·Caddy), Bearer Token 또는 OAuth 2.1 인증, rate limit을 앞단에 배치합니다.

디버깅은 세 단계로 진행합니다.

사내 Wiki·Notion·Confluence를 Agent가 검색·인용하게 하려면 지식베이스 MCP Server를 구축합니다. 아키텍처는 「수집 → 청킹 → 임베딩 → 벡터 저장 → MCP Tools 노출 → HTTP 배포」로 구성됩니다.

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "server.py"]

Docker Compose로 MCP Server, Qdrant(벡터 DB), Redis(캐시)를 한 스택으로 묶으면 로컬과 프로덕션 환경을 동일하게 유지할 수 있습니다. healthcheck로 /health 엔드포인트를 주기적으로 확인하고, 무중단 배포 시 세션 드레인 시간을 확보합니다.

아래 6단계 Runbook은 평가에서 프로덕션까지 닫힌 루프를 완성합니다.

2026년 MCP 생태계는 10,000개 이상의 Server, Cursor·Claude Desktop·ChatGPT·Gemini·VS Code 네이티브 지원, Linux Foundation AAIF 거버넌스로 성숙 단계에 진입했습니다. Server를 한 번 작성하면 LLM 공급자를 전환해도 도구 계층을 재작성할 필요가 없습니다.

지식베이스 MCP Server는 임베딩 갱신, HTTP 세션 유지, 다중 Agent 동시 접속을 요구합니다. 노트북 슬립·메모리 부족·네트워크 지터에 부딪히면 Agent가 도구 호출 중 세션이 끊깁니다. 저가 Linux VPS는 Apple Silicon 네이티브 추론·Xcode CI와 MCP Server를 동일 머신에서 실행하기 어렵습니다.

7×24 MCP Server 상주, iOS CI/CD, Ollama 로컬 추론이 필요한 프로덕션 환경에서는 MESHLAUNCH Mac Mini 클라우드 임대가 일반적으로 더 나은 선택입니다. 전용 Apple Silicon, 일·주·월 유연 주문으로 MCP Server와 Cursor·Claude Code의 안정적 호스트 역할을 수행하며, 팀 통합 자산을 특정 공급자 종속에서 이식 가능한 자산으로 전환합니다. 요금은 대여 요금 페이지에서, 배포·네트워크 문의는 고객 센터를 참고하십시오.