Cloudflare에서 MCP 서버 배포하는 방법

Lynn Mikami·2025년 4월 1일
1

개발자들이 API 테스트와 관리에 많은 시간을 소비하는 현실에서, Apidog는 Postman의 대안으로 주목받고 있습니다. API 개발 팀에 최적화된 Apidog는 실시간 업데이트, 무제한 컬렉션 실행, 시각적 API 명세 생성 등 다양한 기능을 제공하여 개발 워크플로우를 향상시킵니다. 바이브 코딩처럼 효율적인 개발을 추구한다면 Apidog를 활용해 보는 것이 좋겠습니다.

Apidog

소개

Model Context Protocol(MCP)은 인공지능 에이전트가 단순한 텍스트 생성을 넘어서 외부 도구와 서비스에 접근하여 실제 행동을 취할 수 있게 해주는 프로토콜입니다. 최근까지 MCP 서버는 주로 로컬 환경에서 실행되어 사용이 제한적이었지만, Cloudflare에서 원격 MCP 서버를 배포할 수 있게 되면서 더 넓은 사용자층에게 이 기술을 제공할 수 있게 되었습니다. 이 글에서는 Cloudflare를 통해 MCP 서버를 배포하고, 인증 및 권한 부여 시스템을 설정하는 전체 과정을 자세히 알아보겠습니다.

MCP 서버란?

MCP(Model Context Protocol)는 AI 에이전트(MCP 클라이언트)가 이메일 전송, 코드 변경 배포, 블로그 게시 등과 같은 외부 도구와 리소스에 접근할 수 있도록 해주는 프로토콜입니다. 이전까지 MCP는 주로 로컬 기기에서만 실행 가능했기 때문에, 웹 기반 인터페이스나 모바일 앱에서 MCP를 사용하기 어려웠습니다. Cloudflare의 원격 MCP 서버 지원은 이러한 제약을 극복하고, 일반 사용자들도 쉽게 MCP 기술을 활용할 수 있는 길을 열어줍니다.

원격 MCP 서버의 장점

  1. 더 넓은 접근성: 로컬 소프트웨어를 설치할 필요 없이 웹 기반으로 사용 가능
  2. 기기 간 작업 연속성: 다양한 기기에서 동일한 작업을 이어서 할 수 있음
  3. 인증 및 권한 부여 기능: 사용자 인증과 안전한 권한 관리 지원
  4. 확장성: Cloudflare의 글로벌 네트워크를 통한 높은 성능과 확장성

Cloudflare에 MCP 서버 배포하기

1. 첫 번째 MCP 서버 배포하기

Cloudflare는 MCP 서버 배포를 매우 간단하게 만들었습니다. 다음과 같은 방법으로 시작할 수 있습니다:

명령줄을 이용한 방법:

# npm 사용 시
npm create cloudflare@latest -- my-mcp-server --template=cloudflare/ai/demos/remote-mcp-server

# pnpm 사용 시
pnpm create cloudflare@latest my-mcp-server --template=cloudflare/ai/demos/remote-mcp-server

# yarn 사용 시
yarn create cloudflare my-mcp-server --template=cloudflare/ai/demos/remote-mcp-server

# 프로젝트 폴더로 이동
cd my-mcp-server

2. 로컬 개발 환경 설정

프로젝트를 생성한 후, 로컬 개발 서버를 실행하여 MCP 서버를 테스트해 볼 수 있습니다:

# 개발 서버 실행
npm start

이제 MCP 서버가 http://localhost:8787/sse 주소에서 실행됩니다. MCP 인스펙터를 사용하여 서버에 연결하고 테스트할 수 있습니다:

# MCP 인스펙터 실행
npx @modelcontextprotocol/inspector@latest

# 브라우저에서 인스펙터 열기
open http://localhost:5173

인스펙터에서 MCP 서버 URL(http://localhost:8787/sse)을 입력하고 "Connect"를 클릭하면, 예제 OAuth 로그인 페이지로 리디렉션됩니다. 아무 사용자 이름과 비밀번호를 입력하여 로그인한 후, 인스펙터에서 MCP 서버가 제공하는 도구 목록을 볼 수 있습니다.

3. Cloudflare에 MCP 서버 배포하기

로컬 개발 후 Cloudflare에 서버를 배포하려면 Wrangler CLI를 사용합니다:

npx wrangler@latest deploy

배포가 완료되면, 배포된 MCP 서버 URL을 MCP 인스펙터에 입력하여 연결할 수 있습니다. 이제 Cloudflare에 배포된 원격 MCP 서버가 준비되었습니다.

MCP 서버에 인증 추가하기

예제 MCP 서버는 기본적으로 간단한 인증 로직을 포함하고 있지만, 실제 환경에서는 보다 강력한 인증 시스템이 필요합니다. GitHub를 인증 제공자로 사용하는 방법을 살펴보겠습니다.

1. GitHub OAuth 인증이 포함된 새 MCP 서버 만들기

# GitHub OAuth가 포함된 MCP 서버 템플릿 사용
npm create cloudflare@latest -- my-mcp-server-github-auth --template=cloudflare/ai/demos/remote-mcp-github-oauth

# 프로젝트 폴더로 이동
cd my-mcp-server-github-auth

2. GitHub OAuth 앱 생성하기

두 개의 GitHub OAuth 앱을 생성해야 합니다 - 로컬 개발용과 프로덕션용입니다.

로컬 개발용 OAuth 앱:

  1. github.com/settings/developers로 이동하여 새 OAuth 앱 생성
  2. 애플리케이션 이름: "My MCP Server (local)"
  3. 홈페이지 URL: http://localhost:8787
  4. 인증 콜백 URL: http://localhost:8787/callback
  5. 생성된 클라이언트 ID와 시크릿을 .dev.vars 파일에 저장:
touch .dev.vars
echo 'GITHUB_CLIENT_ID="your-client-id"' >> .dev.vars
echo 'GITHUB_CLIENT_SECRET="your-client-secret"' >> .dev.vars

프로덕션용 OAuth 앱:

  1. 새 OAuth 앱 생성
  2. 애플리케이션 이름: "My MCP Server (production)"
  3. 홈페이지 URL: 배포된 Workers URL (예: worker-name.account-name.workers.dev)
  4. 인증 콜백 URL: /callback 경로가 포함된 Workers URL (예: worker-name.account-name.workers.dev/callback)
  5. 클라이언트 ID와 시크릿을 Wrangler CLI로 설정:
wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET

3. MCP 서버 배포 및 테스트

이제 GitHub 인증이 활성화된 MCP 서버를 배포하고 테스트할 수 있습니다:

npx wrangler@latest deploy

배포 후에는 MCP 인스펙터나 다른 MCP 클라이언트를 사용하여 서버에 연결하고, GitHub를 통해 인증할 수 있습니다.

Cloudflare의 MCP 서버 아키텍처

Cloudflare에 배포된 MCP 서버는 다음과 같은 핵심 구성 요소로 이루어져 있습니다:

1. workers-oauth-provider

Cloudflare의 workers-oauth-provider는 OAuth 2.1 프로토콜을 구현한 TypeScript 라이브러리로, MCP 서버에 인증 및 권한 부여 기능을 추가합니다. 이 라이브러리는 MCP 서버가 OAuth 제공자 역할을 할 수 있게 해주며, 사용자 인증 관리를 단순화합니다.

MCP OAuth 흐름은 다음과 같습니다:
1. 사용자가 MCP 클라이언트에서 MCP 서버에 연결 요청
2. MCP 서버가 사용자를 인증 페이지로 리디렉션
3. 사용자가 인증 후, MCP 서버가 자체 토큰을 발행하여 MCP 클라이언트에 전달
4. MCP 클라이언트가 이 토큰을 사용하여 MCP 서버의 도구에 접근

2. McpAgent 클래스

McpAgent 클래스는 Cloudflare의 Agents SDK의 일부로, 원격 전송 계층을 처리합니다. 이 클래스는 Durable Objects를 사용하여 지속적인 연결을 유지하고, 서버 전송 이벤트(SSE)를 통해 MCP 클라이언트와 통신합니다. 개발자는 전송 및 직렬화를 직접 처리할 필요 없이, 단순한 API를 통해 MCP 서버를 구현할 수 있습니다.

McpAgent를 사용한 최소한의 MCP 서버 예제:

import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export class MyMCP extends McpAgent {
  server = new McpServer({
    name: "Demo",
    version: "1.0.0",
  });

  async init() {
    this.server.tool("add", { a: z.number(), b: z.number() }, async ({ a, b }) => ({
      content: [{ type: "text", text: String(a + b) }],
    }));
  }
}

3. 상태 유지 MCP 서버

Cloudflare의 MCP 서버는 Durable Objects를 통해 각 세션마다 상태를 유지할 수 있습니다. 이를 통해 단순한 도구 제공을 넘어서, 게임, 쇼핑 카트, 지식 그래프 등 상태를 유지해야 하는 복잡한 애플리케이션을 구현할 수 있습니다.

상태 유지 카운터 예제:

import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

type State = { counter: number }

export class MyMCP extends McpAgent<Env, State, {}> {
  server = new McpServer({
    name: "Demo",
    version: "1.0.0",
  });

  initialState: State = {
    counter: 1,
  }

  async init() {
    this.server.tool('add', 'Add to the counter', { a: z.number() }, async ({ a }) => {
      this.setState({ ...this.state, counter: this.state.counter + a })
      return {
        content: [{ type: 'text', text: String(`추가됨: ${a}, 현재 총합: ${this.state.counter}`) }],
      }
    })
  }
}

로컬 MCP 클라이언트와의 연결

현재 많은 MCP 클라이언트들은 원격 연결이나 인증을 지원하지 않지만, Cloudflare는 mcp-remote라는 도구를 제공하여 이러한 클라이언트가 원격 MCP 서버와 통신할 수 있도록 합니다.

Claude Desktop과 같은 MCP 클라이언트에 원격 MCP 서버를 연결하는 방법:

{
  "mcpServers": {
    "math": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-worker-name.your-account.workers.dev/sse"
      ]
    }
  }
}

결론

Cloudflare의 원격 MCP 서버 지원은 MCP 기술을 개발자를 넘어 일반 사용자들에게도 접근 가능하게 만드는 중요한 발전입니다. 인증 및 권한 부여 기능, 상태 유지 기능, 그리고 글로벌 확장성을 갖춘 Cloudflare의 MCP 서버는 AI 에이전트가 더 다양한 서비스와 도구에 접근할 수 있는 길을 열어줍니다.

원격 MCP는 데스크톱 소프트웨어에서 웹 기반 소프트웨어로의 전환과 같은 패러다임 전환을 의미합니다. 사용자들은 기기 간에 작업을 계속하고, 로그인하여 바로 사용할 수 있는 환경을 기대합니다. Cloudflare를 통해 원격 MCP 서버를 배포함으로써, AI 도구와 에이전트를 사용하는 수백만 명의 사용자들에게 여러분의 서비스를 제공할 수 있습니다.

지금 바로 Cloudflare에서 원격 MCP 서버를 구축하고 배포하여, AI 에이전트의 세계에 여러분의 서비스를 통합해보세요!

profile
Lynn Mikami
이전 포스트

Figma MCP 서버: 디자인 협업의 새로운 패러다임

다음 포스트

Ollama를 활용한 로컬 MCP 서버 배포 가이드

0개의 댓글