Python 또는 TypeScript 기초는 있지만 Claude·GPT·Cursor에서 자사 API·DB·지식베이스를 안전하게 호출하는 방법에 막혀 있다면, 본문은 Hello World부터 프로덕션 배포까지의 MCP Server 개발 전 경로를 제공합니다. 프로토콜 원리, Tools/Resources/Prompts 3대 핵심 기능, HTTP+SSE 원격 전송, MCP Inspector 디버깅, Docker 배포, 지식베이스 실전 프로젝트, Mac 클라우드 launchd 7×24 5단계 Runbook과 호스팅 환경 결정 매트릭스를 포함합니다.

1. MCP 프로토콜 원리와 3계층 아키텍처

Model Context Protocol(MCP)는 Anthropic이 2024년 11월 오픈소스화한, AI Host(Cursor, Claude Desktop 등)와 외부 도구/데이터 간 통합 JSON-RPC 2.0 통신 규격입니다. 2026년 기준 OpenAI, Google Gemini, Microsoft 모두 채택했으며, 공개 MCP Server는 10,000개를 넘습니다.

┌─────────────────────────────────┐
│  Host（Cursor / Claude Desktop） │
│  ┌───────────────────────────┐  │
│  │  MCP Client（1:1 세션）    │  │
│  └───────────────────────────┘  │
└─────────────────────────────────┘
             ↕ JSON-RPC 2.0
┌─────────────────────────────────┐
│  MCP Server（개발 중인 서버）     │
│  Tools │ Resources │ Prompts     │
└─────────────────────────────────┘
             ↕
┌─────────────────────────────────┐
│  외부 시스템（API, DB, 파일）    │
└─────────────────────────────────┘

Server는 tools/list + tools/call(실행), resources/list + resources/read(읽기 전용 컨텍스트), prompts/list + prompts/get(프롬프트 템플릿)을 구현합니다. 전송 계층은 STDIO(로컬 자식 프로세스)와 HTTP+SSE(원격 공유)가 주류입니다.

2. 3대 개발 페인포인트

도구 정의 파편화. AI 클라이언트마다 Function Calling Schema를 하드코딩하면 Cursor → Claude Desktop 전환 때마다 재작성. MCP는 tools/list로 런타임 자기 기술, 한 번 작성하면 어디서나 동작.
로컬 개발과 프로덕션 괴리. 노트북에서 STDIO 조정 후 덮으면 연결 끊김. Linux Docker에는 Apple 툴체인이 없어 트러블슈팅 비용 급증.
보안과 가시성 부족. 약 1,000개 공개 MCP Server가 무인증 노출. 프로덕션에서는 Token 중앙 관리와 tools/call 지연 기준선 기록 필수.

3. 환경 준비

TypeScript와 Python 경로를 모두 제공합니다. 하나만 선택하면 됩니다.

TypeScript 경로

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx
npx tsc --init

Python 경로

mkdir my-mcp-server && cd my-mcp-server
python3 -m venv .venv && source .venv/bin/activate
pip install "mcp[cli]" httpx

권장: Node.js 20+ 또는 Python 3.10+. Mac 로컬 검증 후 10절 Runbook으로 프로덕션 상주.

4. Hello World: 첫 MCP Server

다음 TypeScript 예제는 STDIO Server를 만들고 ping 도구를 노출합니다:

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: "hello-mcp", version: "1.0.0" });

server.tool("ping", "Health check", { message: z.string().optional() },
  async ({ message }) => ({
    content: [{ type: "text", text: `pong: ${message ?? "ok"}` }]
  })
);

const transport = new StdioServerTransport();
await server.connect(transport);

npx tsx src/index.ts로 실행. Python 버전은 mcp.server.Server + stdio_server()로 동일 로직.

5. Tools 개발: 5가지 실전 도구

프로덕션 Server는 보통 3–8개의 고가치 도구를 노출합니다. 아래 5예는 일반 시나리오를 커버합니다:

도구명	용도	주요 파라미터
`query_database`	읽기 전용 SQL	`sql: string`
`search_docs`	지식베이스 전문 검색	`query: string, limit?: number`
`create_ticket`	티켓 생성	`title, body, priority`
`fetch_weather`	외부 REST API 호출	`city: string`
`run_script`	샌드박스 실행	`lang, code`(화이트리스트 필수)

각 도구에 JSON Schema 파라미터 설명과 부작용(read-only / destructive)을 부여해 Agent가 tools/list에서 자율 선택하도록 합니다.

6. Resources: 읽기 전용 리소스

Resources는 설정 파일, Schema 정의, API 스펙 등 읽기 전용 컨텍스트용입니다. Agent는 resources/read로 필요 시에만 가져와 Prompt 비대화를 방지합니다.

server.resource("config://app/settings", "Application settings JSON",
  async (uri) => ({
    contents: [{ uri: uri.href, mimeType: "application/json",
      text: await fs.readFile("config/settings.json", "utf8") }]
  })
);

7. Prompts: 재사용 가능한 템플릿

Prompts는 팀 베스트 프랙티스를 발견 가능한 템플릿으로 캡슐화합니다. 예: 「코드 리뷰 Checklist」「Incident 보고 형식」.

server.prompt("code-review", "Structured code review prompt",
  { language: z.string(), focus: z.string().optional() },
  ({ language, focus }) => ({
    messages: [{
      role: "user",
      content: { type: "text",
        text: `Review this ${language} code. Focus: ${focus ?? "security, perf, readability"}.` }
    }]
  })
);

8. HTTP+SSE 원격 전송

팀 공유나 클라우드 배포 시 STDIO를 Streamable HTTP 또는 HTTP+SSE로 전환:

import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
app.get("/sse", async (req, res) => {
  const transport = new SSEServerTransport("/message", res);
  await server.connect(transport);
});

전송	적용	장점	주의
STDIO	Cursor / Claude Desktop 로컬	의존성 제로, 격리 양호	자식 프로세스 상주 필요
HTTP+SSE	원격 팀, 다중 Client 공유	네트워크 경유, 수평 확장	session affinity 필요

9. 디버깅과 테스트

MCP Inspector: npx @modelcontextprotocol/inspector node dist/index.js로 GUI 테스트.
Cursor 설정: 프로젝트 또는 전역 .cursor/mcp.json에 Server 등록.
로그 계층화: stderr에 구조화 로그(STDIO JSON-RPC 채널 오염 금지).
단위 테스트: 도구 handler mock 테스트로 매번 Host 기동 회피.

{
  "mcpServers": {
    "my-kb-server": {
      "command": "node",
      "args": ["/path/to/my-mcp-server/dist/index.js"],
      "env": { "KB_INDEX_PATH": "/data/kb.index" }
    }
  }
}

10. 프로덕션 배포와 5단계 Runbook

호스팅 환경 결정 매트릭스

호스팅	STDIO	7×24	네이티브 macOS	적합
MacBook 로컬	✅	❌ 덮으면 끊김	✅	개인 검증
Linux VPS + Docker	⚠️	✅	❌	순 HTTP Server
VPSMAC M4 Mac 클라우드	✅ launchd	✅	✅ 베어메탈 SSH	Cursor + MCP 동기 상주

5단계 Runbook

전송 계층 선택: IDE 통합은 STDIO, 팀 공유는 HTTP+SSE.
빌드와 패키징: 의존 버전 잠금.
Cursor / Claude 설정: mcp.json 작성, tools/list Schema 검증.
Docker(선택): HTTP 모드는 컨테이너화 가능. STDIO는 베어메탈 launchd 권장.
launchd 상주: Mac 클라우드 노드에서 plist 등록, 리소스 상한과 로그 설정.

11. 지식베이스 MCP 실전 프로젝트

사내 Markdown/Wiki를 벡터 인덱스화하고 3가지 능력을 노출:

Tool search_kb: 의미 검색 Top-K, 인용 출처 포함.
Resource kb://manifest: 문서 목록과 갱신 시각.
Prompt answer-with-citations: [doc_id:line] 인용 형식 강제.

Mac 클라우드 노드에서 OpenClaw Gateway와 동기 배포하면 Agent가 7×24 지식베이스를 호출합니다. 자세한 내용은 MCP 프로토콜 전경 참조.

12. 2026 생태계 전망

AAIF 거버넌스: MCP는 Linux Foundation Agentic AI Foundation으로 이관, 업계 공공 인프라화.
OAuth 2.1 표준화: 원격 Server 인증이 2026 로드맵에 포함.
레지스트리 공백: 통합 MCP Server 발견(DNS급)은 아직 진행 중, 단기적으로는 설정 파일 의존.
A2A와 보완: MCP는 수직 도구 통합, Google A2A는 Agent 수평 오케스트레이션.

13. 인용 가능한 기술 요점 (2026)

프로토콜 핵심: JSON-RPC 2.0 위 tools/list, tools/call, resources/read, prompts/get.
생태 규모: 공개 MCP Server 10,000+; 4대 모델 벤더 전원 채택.
비용 효과: MCP 표준화 후 기업 AI 통합 개발 비용 38–55% 절감(업계 조사 평균).
보안 기준선: 인증·파라미터 검증·tools/call 감사 로그 필수; STDIO Server 공인터넷 직접 노출 금지.

14. 결론

Hello World부터 지식베이스 실전까지, MCP Server의 본질은 「AI가 무엇을 발견하고 올바르게 호출하는가」를 표준화하는 것——한 번 작성하면 Cursor, Claude Desktop, VS Code 모두에서 재사용 가능합니다. 노트북은 검증용이지만, 덮으면 끊김·환경 드리프트·launchd 호스팅 부재로 STDIO 자식 프로세스는 프로덕션에서 불안정합니다. Linux Docker는 HTTP 모드를 돌릴 수 있으나 추상 계층 증가와 Apple 툴체인 부재가 장벽입니다.

Cursor, OpenClaw, Claude Desktop과 MCP Server를 장기 7×24 동기 상주시키고 네이티브 macOS와 launchd 호스팅이 필요하다면, VPSMAC M4 Mac 클라우드 노드 렌탈이 AI 자동화 프로덕션 환경에서 보통 더 수월한 선택입니다——도구 계층은 한 번 작성, 모델은 자유 전환, 노드는 항상 온라인.

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

목차