MCP 서버: 개발자를 위한 완전 가이드 (2026)

MCP 서버 검색량은 월 60,000건을 넘어섰으며 계속해서 상승하고 있습니다. 만약 당신이 2026년에 AI 에이전트(AI agents)를 활용해 무언가를 구축하고 있다면, 이미 Cursor의 설정 패널, Claude Desktop의 설정 파일(config file), 또는 GitHub README에서 MCP를 접해 보았을 것입니다. 하지만 MCP 서버가 실제로 무엇인지, 언제 사용해야 하는지, 그리고 어떻게 직접 구축하는지에 대한 명확하고 실질적인 멘탈 모델(mental model)은 아직 갖추지 못했을 수도 있습니다.

이 가이드가 그 역할을 해줄 것입니다. 우리는 프로토콜(protocol) 자체와 현재의 생태계, Cosmic의 네이티브 MCP 서버가 노출하는 18가지 도구(tools), 그리고 이를 Claude Desktop 및 Cursor에 연결하는 과정을 단계별로 살펴볼 것입니다. 이 가이드를 마칠 때쯤이면, 당신은 MCP 기반의 작동하는 콘텐츠 워크플로우를 갖게 될 것이며, 어떤 데이터 소스 위에서도 커스텀 MCP 서버를 구축할 수 있는 탄탄한 기초를 다지게 될 것입니다.

MCP 서버란 무엇인가?

MCP는 Model Context Protocol의 약자입니다. MCP 서버는 도구(tools), 리소스(resources), 그리고 프롬프트 템플릿(prompt templates)을 표준화된 방식으로 AI 에이전트(AI agents)에게 노출하는 경량 서비스입니다.

핵심 단어는 _표준화(standardized)_입니다. MCP 이전에는 AI 에이전트를 위한 모든 도구 통합에 맞춤형 글루 코드(glue code)가 필요했습니다. 즉, 맞춤형 JSON 스키마(JSON schema), 일회성 API 래퍼(API wrapper), 그리고 산더미 같은 시스템 프롬프트(system prompt) 지침들이 필요했습니다. 각 AI 클라이언트(client)마다 고유한 형식을 가지고 있었기에, 그 무엇도 이식(portable)할 수 없었습니다.

MCP는 준수하는 모든 AI 클라이언트가 통신할 수 있는 공통 인터페이스를 통해 이 문제를 해결합니다. 서버를 한 번만 구축하면 됩니다. Claude, Cursor, Copilot, Codex 등 MCP를 지원하는 모든 클라이언트가 수정 없이 서버에 연결할 수 있습니다.

본질적으로 MCP 서버는 세 가지 역할을 수행합니다:

에이전트가 호출할 수 있는 _도구(tools)_를 노출합니다 ("이 객체를 가져오기", "새 페이지 생성하기", "태그로 게시물 검색하기")
에이전트에게 컨텍스트(context)를 제공하는 _리소스(resources)_를 제공합니다 (지식 베이스, 콘텐츠 스키마, 사용 가능한 타입 목록 등)
에이전트가 수신한 데이터에 대해 추론하는 방식을 형성하는 _프롬프트 템플릿(prompt templates)_을 수용합니다

이 프로토콜은 Anthropic에 의해 도입되었으며, 이후 개발자 생태계 전반에 걸쳐 널리 채택되었습니다. 이는 두 가지 전송 방식(transports)을 통해 작동합니다: HTTP/SSE (호스팅된 엔드포인트용) 및 stdio (로컬 프로세스용). 어떤 언어나 런타임(runtime)으로도 이를 구현할 수 있습니다.

왜 지금 MCP가 어디에나 있는가

지난 12개월 동안 세 가지 요소가 결합되면서 MCP는 틈새 사양(niche spec)에서 주류 표준(mainstream standard)으로 급부상했습니다.

1. 에이전트형 IDE (Agentic IDEs)에 범용 도구 계층이 필요했습니다

Cursor, Claude Code, Codex는 더 이상 자동 완성 도구가 아닙니다. 이들은 파일 읽기, 코드 편집, 테스트 실행, 변경 사항 커밋과 같은 다단계 작업을 수행하는 자율 코딩 에이전트(autonomous coding agents)입니다. 이러한 에이전트들이 사용자의 데이터, CMS, 데이터베이스, API에 접근하여 동작하려면, 데이터에 도달할 수 있는 표준화된 방법이 필요합니다. MCP 서버가 바로 그 연결 고리(hook) 역할을 합니다.

2. Claude의 네이티브 MCP 지원이 계산법을 바꾸었습니다

Anthropic이 Claude Desktop과 Claude API에 MCP 지원을 직접 구축했을 때, 채택률이 폭발적으로 증가했습니다. 커스텀 도구 정의(custom tool definitions)를 직접 연결하던 개발자들은 MCP로 전환했습니다. 왜냐하면 이식성(portability)의 이점이 즉각적이었기 때문입니다. 서버를 한 번만 구축하면, 호환 가능한 어떤 클라이언트와도 연결할 수 있습니다.

3. 스킬 모델 (Skills model)이 승리하고 있습니다

초기 에이전트형 도구는 개발자가 모든 도구를 평면적인 JSON 스키마(JSON schema)로 설명해야 했으며, 이는 확장성(scale)이 떨어졌습니다. MCP는 에이전트가 동적으로 발견하고 호출할 수 있는 개별적이고 조합 가능한 기능(discrete, composable capabilities)이라는 개념을 도입합니다. 이는 프로덕션 에이전트 워크플로(production agentic workflows)를 위한 더 나은 사고 모델(mental model)이며, 생태계가 수렴하고 있는 방향입니다.

MCP 프로토콜: 실제로 작동하는 방식

내부적으로 MCP 서버는 정의된 프로토콜을 통해 MCP 클라이언트와 통신하는 프로세스(로컬 또는 호스팅됨)로 실행됩니다.

전송 방식 (Transports)

MCP는 두 가지 전송 방식을 지원합니다:

HTTP/SSE (Server-Sent Events): 클라이언트가 서버의 엔드포인트로 HTTP POST 요청을 보냅니다. 서버는 SSE를 통해 응답을 스트리밍하여 다시 보냅니다. 이는 호스팅된 MCP 서버의 표준입니다. 모든 HTTPS 연결을 통해 작동하며, 로컬 설치가 필요하지 않고, 다른 웹 서비스와 마찬가지로 확장(scale)이 가능합니다.

stdio: 클라이언트가 서버를 로컬 프로세스로 생성하고 표준 입출력 (standard input/output)을 통해 통신합니다. 이는 IDE (Cursor, 로컬 모드의 Claude Desktop) 내부에서 실행되는 개발자 도구에서 흔히 사용되는 방식입니다. 지연 시간 (latency)은 낮지만, 서버가 로컬에 설치되어 있어야 합니다.

세 가지 기본 요소 (The Three Primitives)

**도구 (Tools)**는 에이전트가 호출할 수 있는 함수입니다. 각 도구는 이름, 설명 (에이전트가 언제 호출할지 결정하는 데 사용됨), 그리고 입력 파라미터를 위한 JSON 스키마 (JSON schema)를 가집니다. 에이전트가 도구를 호출하면, 서버가 함수를 실행하고 결과를 반환하며, 에이전트는 그 결과를 다음 단계에서 사용합니다.

**리소스 (Resources)**는 서버가 컨텍스트 (context)를 위해 노출하는 데이터 객체입니다. 리소스는 사용 가능한 콘텐츠 유형 목록, 브랜드 가이드라인 문서, 또는 스키마 정의 (schema definition) 등이 될 수 있습니다. 에이전트는 세션 시작 시 자신이 무엇을 다루고 있는지 이해하기 위해 리소스를 읽습니다.

**프롬프트 템플릿 (Prompt templates)**은 특정 작업을 위해 에이전트의 행동을 형성하는 재사용 가능한 지침 조각입니다. 템플릿은 에이전트가 콘텐츠 업데이트 요청을 어떻게 형식화해야 하는지, 또는 검색 쿼리 (search query)를 어떻게 구조화해야 하는지를 정의할 수 있습니다.

디스커버리 (Discovery)

MCP 클라이언트가 서버에 처음 연결될 때, list_tools, list_resources, 그리고 list_prompts 엔드포인트 (endpoints)를 호출합니다. 서버는 자신의 전체 기능 매니페스트 (capability manifest)를 반환합니다. 클라이언트는 이를 캐싱 (cache)하고 도구들을 사용 가능한 함수로서 에이전트에게 제시합니다. 수동 설정은 필요하지 않습니다.

현재 MCP 생태계

2026년 중반 기준으로, 대부분의 주요 개발자 도구 및 데이터 소스에 대한 MCP 서버가 존재합니다. 가장 활발하게 사용되는 것들은 다음과 같습니다:

콘텐츠 및 데이터:

Cosmic (콘텐츠 관리: 읽기, 쓰기, 스키마, AI 생성)
Notion, Airtable, Linear (구조화된 데이터 및 프로젝트 관리)
GitHub (저장소, 이슈, PR)
Postgres, SQLite (직접적인 데이터베이스 액세스)

개발 도구:

Vercel (배포, 로그, 환경 변수)
Sentry (에러 트래킹)
Datadog (관측성/Observability)

통신:

Slack (채널, 메시지, 스레드)
Gmail, Outlook (이메일)

검색 및 웹 (Search and web):

Brave Search, Exa (웹 검색)
Firecrawl (웹 스크래핑 및 추출)

Anthropic MCP 저장소는 공식 서버 목록을 유지 관리합니다: github.com/modelcontextprotocol/servers.

MCP 서버 vs. 직접 API (Direct API): 각각 언제 사용해야 하는가

MCP는 귀하의 REST API를 대체하는 것이 아닙니다. 이는 REST API 위에 구축된 레이어이며, 에이전트(Agent)가 소비하기에 최적화되어 있습니다.

다음의 경우 REST API를 직접 사용하세요:

정해진 일정에 따라 엔드포인트(Endpoint)를 호출하는 애플리케이션 코드를 작성할 때
요청 파라미터(Request parameters)에 대한 저수준 제어(Low-level control)가 필요할 때
AI가 아닌 시스템과 통합할 때
자동 완성 및 에러 핸들링(Error handling) 기능이 포함된 타입 지정 SDK 메서드를 원할 때

다음의 경우 MCP 서버를 사용하세요:

AI 에이전트가 도구(Tools)를 동적으로 발견하고 호출하기를 원할 때
AI 어시스턴트(Claude, Cursor, Copilot)를 귀하의 데이터에 연결할 때
통합 코드를 다시 작성하지 않고도 여러 AI 클라이언트 간의 이식성(Portability)을 확보하고 싶을 때
에이전트가 컨텍스트(Context)를 기반으로 어떤 도구를 호출할지 결정하는 워크플로우를 구축할 때

Cosmic의 경우 특히 다음과 같습니다: 애플리케이션 코드에서는 TypeScript SDK를 사용하고, Claude Desktop, Cursor 또는 기타 MCP 호환 클라이언트에서의 에이전트 주도 워크플로우에는 MCP 서버를 사용하세요.

Cosmic의 MCP 서버: 4개 카테고리에 걸친 18개의 도구

Cosmic은 네이티브 MCP 서버를 핵심 기능(First-class feature)으로 제공합니다. 이는 Cosmic 팀에 의해 구축 및 유지 관리되며, 4개의 카테고리에 걸쳐 18개의 도구를 노출합니다.

객체 (Objects) (5개 도구)

list_objects — 유형, 상태 또는 로케일(Locale)별로 콘텐츠 객체 목록을 나열하거나 검색
get_object — ID 또는 슬러그(Slug)를 통해 단일 객체 가져오기
create_object — 새로운 객체(블로그 포스트, 페이지, 제품 등) 생성
update_object — 기존 객체의 콘텐츠 또는 메타데이터 편집
delete_object — 객체를 영구적으로 삭제

미디어 (Media) (4개 도구)

list_media — 미디어 파일을 탐색하며, 선택적으로 특정 폴더로 범위를 제한할 수 있음
get_media — 단일 에셋의 메타데이터와 imgix URL을 가져옴
upload_media — URL 또는 base64 페이로드를 통해 파일을 업로드함
delete_media — 미디어 파일을 삭제함

객체 유형 (Object Types) (5개 도구)

list_object_types — 버킷 내의 모든 콘텐츠 모델을 나열함
get_object_type — 단일 유형의 전체 스키마 (Schema)를 가져옴
create_object_type — 새로운 콘텐츠 모델을 정의함
update_object_type — 기존 스키마를 진화시킴
delete_object_type — 콘텐츠 모델과 해당 모델의 모든 객체를 삭제함

AI 생성 (AI Generation) (4개 도구)

generate_text — 버킷 자체의 콘텐츠를 컨텍스트 (Context)로 사용하여 문구를 초안 작성, 재작성, 요약 또는 번역함
generate_image — 이미지를 생성하고 미디어 라이브러리에 저장함
generate_video — 짧은 비디오 클립을 생성함 (Google Veo)
generate_audio — 텍스트로부터 나레이션 오디오를 생성함 (OpenAI TTS를 통한 13가지 음성)

Cosmic의 MCP 서버를 Claude Desktop에 연결하기

호스팅된 엔드포인트 (Endpoint)를 사용하는 것이 가장 빠른 연결 방법입니다. 로컬 설치가 필요하지 않습니다.

1단계: Cosmic 자격 증명 (Credentials) 가져오기

Cosmic 대시보드에서 버킷으로 이동한 후 _Settings > API Access_로 이동합니다. 버킷 슬러그 (Slug), 읽기 키 (Read key), 쓰기 키 (Write key)를 복사하세요 (쓰기 키는 에이전트가 콘텐츠를 생성하거나 업데이트하기를 원하는 경우에만 필요합니다).

2단계: Claude Desktop 설정에 추가하기

Claude Desktop 설정 파일을 엽니다. macOS의 경우 경로는 ~/Library/Application Support/Claude/claude_desktop_config.json입니다.

{
  "mcpServers": {
    "cosmic": {
...

읽기 전용 액세스의 경우 x-write-key 헤더를 생략하세요. 쓰기 도구는 해당 헤더 없이 호출될 경우 명확한 에러를 반환합니다.

3단계: Claude Desktop 재시작하기

Claude Desktop을 종료하고 다시 엽니다. 도구 선택기(입력창의 망치 아이콘)에 Cosmic 도구들이 나타나는 것을 확인할 수 있습니다.

4단계: 자연어 명령으로 테스트하기

지난 7일 동안의 모든 블로그 포스트 초안 목록을 보여줘

Claude는 type을 blog-posts, status를 draft로 설정하여 list_objects를 호출하고, 그 결과를 구조화된 형식으로 반환합니다.

Cursor 연결하기

Cursor의 경우, 프로젝트 루트의 .cursor/mcp.json (프로젝트 범위) 또는 ~/.cursor/mcp.json (글로벌)에 설정을 추가하세요:

{
  "mcpServers": {
    "cosmic": {
...

연결되면 Cursor의 에이전트(agent)가 코드를 생성할 때 사용자의 콘텐츠 모델을 참조할 수 있어, 컴포넌트 프롭(props), TypeScript 타입, API 호출이 실제 버킷 스키마(bucket schema)와 일치하도록 보장합니다.

셀프 호스팅 옵션 (stdio)

개발 환경 내부에서 MCP 서버를 로컬로 실행하는 것을 선호한다면, npm 패키지에 포함된 stdio 바이너리를 사용할 수 있습니다:

npx @cosmicjs/mcp-server

stdio 바이너리는 환경 변수(environment variables)에서 인증 정보를 읽어옵니다:

export COSMIC_BUCKET_SLUG=your-bucket-slug
export COSMIC_READ_KEY=your-read-key
export COSMIC_WRITE_KEY=your-write-key  # 선택 사항

애플리케이션 코드에서 Cosmic SDK 사용하기

애플리케이션 코드에서는 MCP 서버 대신 TypeScript SDK를 사용하세요. SDK는 완전한 타입 안정성(type safety), 자동 완성(autocomplete), 그리고 모든 API 파라미터에 대한 직접적인 제어권을 제공합니다.

import { createBucketClient } from '@cosmicjs/sdk';

const cosmic = createBucketClient({
...

호출 지점(call site)을 직접 제어할 때는 SDK가 적절한 선택입니다. 반면, AI 에이전트가 호출 지점을 제어할 때는 MCP 서버가 적절한 선택입니다.

나만의 MCP 서버 구축하기

핵심 패턴은 간단합니다:

JSON 스키마(JSON Schema) 입력 정의를 가진 함수로 도구(tools)를 정의합니다.
도구 매니페스트(tool manifest)를 반환하는 list_tools 엔드포인트를 구현합니다.
호출을 함수로 라우팅하고 결과를 반환하는 call_tool 엔드포인트를 구현합니다.
HTTPS 엔드포인트(HTTP/SSE 전송 방식)로 배포하거나 npm 패키지(stdio 전송 방식)로 게시합니다.

MCP TypeScript SDK (@modelcontextprotocol/sdk)가 프로토콜의 상용구(boilerplate) 코드를 처리해주므로, 도구 구현에만 집중할 수 있습니다.

Cosmic MCP 서버로 시작하기

MCP는 빠르게 발전하고 있습니다. 지금 바로 프로덕션급 (production-grade) MCP 워크플로우를 구축하는 개발자들은 의미 있는 선점 효과를 누리게 될 것입니다.

Cosmic의 호스팅된 MCP 엔드포인트 (endpoint)는 인프라 작업을 제거하여, 여러분이 에이전트 (agent)가 실제로 수행하는 작업에만 집중할 수 있게 해줍니다.

무료로 가입하세요, 신용카드 정보는 필요하지 않습니다

이 기사는 원래 Cosmic 블로그에 게시되었습니다. Cosmic은 개발자와 AI 네이티브 (AI-native) 팀을 위해 구축된 YC W19 지원 헤드리스 CMS (headless CMS)입니다.