Model Context Protocol (MCP) 서버 + Google OAuth

이는 Google OAuth가 내장된 원격 MCP 연결을 지원하는 Model Context Protocol (MCP) 서버입니다.

Cloudflare 계정에 직접 배포할 수 있으며, Google Cloud OAuth 클라이언트 앱을 직접 만든 후에는 원하는 대로 확장할 수 있는 완전한 기능의 원격 MCP 서버를 갖추게 됩니다. 사용자는 Google 계정으로 로그인하여 MCP 서버에 연결할 수 있습니다.

workers-oauth-provider 라이브러리를 사용하여 Cloudflare에 배포된 MCP 서버에 다른 OAuth 공급자를 통합하는 방법에 대한 참조 예시로 사용할 수 있습니다.

MCP 서버(Cloudflare Workers 기반):

• MCP 클라이언트에게는 OAuth 서버 역할을 합니다.

• 실제 OAuth 서버(GitHub의 경우 Google)에게는 OAuth 클라이언트 역할을 합니다.

[!WARNING] 이 데모 템플릿은 빠르게 시작할 수 있도록 설계된 데모 템플릿입니다. 여러 보안 제어를 구현했지만, 프로덕션에 배포하기 전에 모든 예방적 및 방어적 보안 조치를 반드시 구현해야 합니다. 포괄적인 보안 가이드를 검토하세요: Securing MCP Servers

시작하기

리포지토리를 클론하고 의존성을 설치합니다: npm install

프로덕션용

새 Google Cloud OAuth 앱을 만듭니다:

• 홈페이지 URL에 https://mcp-google-oauth.<your-subdomain>.workers.dev를 지정합니다.

• 인증 콜백 URL에 https://mcp-google-oauth.<your-subdomain>.workers.dev/callback을 지정합니다.

• 클라이언트 ID를 기록하고 클라이언트 시크릿을 생성합니다.

• Wrangler를 통해 시크릿을 설정합니다.

wrangler secret put GOOGLE_CLIENT_ID
wrangler secret put GOOGLE_CLIENT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY # add any random string here e.g. openssl rand -hex 32
wrangler secret put HOSTED_DOMAIN # optional: use this when restrict google account domain

KV 네임스페이스 설정

• KV 네임스페이스를 생성합니다: wrangler kv:namespace create "OAUTH_KV"

• KV ID로 Wrangler 파일을 업데이트합니다.

배포 및 테스트

MCP 서버를 배포하여 workers.dev 도메인에서 사용할 수 있게 합니다. wrangler deploy

Inspector를 사용하여 원격 서버를 테스트합니다:

npx @modelcontextprotocol/inspector@latest

https://mcp-google-oauth.<your-subdomain>.workers.dev/mcp를 입력하고 연결(connect)을 누릅니다. 인증 흐름을 거치면 Tools가 작동하는 것을 볼 수 있습니다:

이제 원격 MCP 서버를 배포했습니다!

액세스 제어

이 MCP 서버는 인증에 Google Cloud OAuth를 사용합니다. 인증된 모든 Google 사용자는 "add"와 같은 기본 도구에 액세스할 수 있습니다. 호스팅 도메인을 가진 사용자로 제한하려면 HOSTED_DOMAIN 환경 변수를 설정합니다.

Claude Desktop에서 원격 MCP 서버에 액세스

Claude Desktop을 열고 Settings -> Developer -> Edit Config으로 이동합니다. 그러면 Claude가 액세스할 수 있는 MCP 서버를 제어하는 구성 파일이 열립니다.

다음 구성으로 내용을 교체합니다. Claude Desktop을 다시 시작하면 OAuth 로그인 페이지가 표시된 브라우저 창이 열립니다. 인증 흐름을 완료하여 Claude에게 MCP 서버에 대한 엑세스 권한을 부여합니다. 권한을 부여하고 나면 도구를 사용할 수 있습니다.

{
  "mcpServers": {
    "math": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp-google-oauth.<your-subdomain>.workers.dev/mcp"
      ]
    }
  }
}

인터페이스에서 도구(Tools, 🔨 아래)가 표시되면 Claude에게 그 도구를 사용하도록 요청할 수 있습니다. 예: "수학 도구를 사용하여 23과 19를 더해 줄 수 있겠어요?" 그러면 Claude는 도구를 호출하여 MCP 서버에서 생성된 결과를 보여줍니다.

로컬 개발용

MCP 서버를 반복 개발하고 테스트하려면 로컬 개발 환경에서 수행할 수 있습니다. 그러려면 Google Cloud에서 다른 OAuth 앱을 만들어야 합니다:

• 홈페이지 URL에 http://localhost:8788을 지정합니다.

• 인증 콜백 URL에 http://localhost:8788/callback을 지정합니다.

• 클라이언트 ID를 기록하고 클라이언트 시크릿을 생성합니다.

• 프로젝트 루트에 .dev.vars 파일을 만들고 다음 내용을 입력합니다:

GOOGLE_CLIENT_ID=your_development_google_cloud_oauth_client_id
GOOGLE_CLIENT_SECRET=your_development_google_cloud_oauth_client_secret

개발 및 테스트

서버를 로컬로 실행하여 http://localhost:8788에서 접근할 수 있게 합니다. wrangler dev

로컬 서버를 테스트하려면 Inspector에 http://localhost:8788/mcp를 입력하고 연결(connect)을 누릅니다. 다음 프롬프트(지시)를 따라가다 보면 "List Tools"를 사용할 수 있습니다.

Claude Desktop 및 기타 MCP 클라이언트 사용하기

Claude를 사용하여 원격 MCP 서버에 연결할 때 오류 메시지가 표시될 수 있습니다. Claude Desktop Desktop는 원격 MCP서버를 아직 지원하지 않기 때문에 혼동이 생길 수 있습니다. MCP 서버가 연결되어 있는지 확인하려면 Claude 인터페이스의 🔨 아이콘(우측 하단)에 마우스를 올리세요. 도구들이 표시된 것을 확인할 수 있습니다.

Cursor 및 기타 MCP 클라이언트 사용하기

Cursor를 MCP 서버에 연결하려면 Type에서 "Command"를 선택하고 Command 필드에 command와 args 필드를 하나로 합치세요(예: npx mcp-remote https://<your-worker-name>.<your-subdomain>.workers.dev/mcp).

Cursor는 HTTP+SSE 서버를 지원하지만 인증은 지원하지 않습니다. 따라서 여전히 mcp-remote를 사용해야 하며(HTTP 서버가 아닌 STDIO 서버를 사용해야 함) 이 점에 유의하세요.

Windsurf와 같은 다른 MCP 클라이언트에도 MCP 서버를 연결할 수 있습니다. 해당 클라이언트의 구성 파일을 열어 보세요. 설정 파일에 Claude Desktop 설정에 사용한 것과 동일한 JSON을 추가하고 MCP 클라이언트를 다시 시작하면 됩니다.

작동 방식

OAuth Provider

OAuth Provider 라이브러리는 Cloudflare Workers를 위한 완전한 OAuth 2.1 서버 구현입니다. 토큰 발급, 검증, 관리를 포함한 OAuth 흐름의 복잡한 처리를 담당합니다. 이 프로젝트에서는 다음과 같은 역할을 double로 수행합니다:

• 서버에 연결하는 MCP 클라이언트를 인증합니다.

• Google Cloud OAuth 서비스와의 연결을 관리합니다.

• 토큰과 인증 상태를 KV 저장소에 안전하게 저장합니다.

Durable MCP

Durable MCP는 Cloudflare의 Durable Objects로 기본 MCP 기능을 확장하며, 다음을 제공합니다:

• MCP 서버를 위한 영구 상태 관리.

• 요청 간에 인증 컨텍스트를 안전하게 저장.

• this.props를 통한 인증된 사용자 정보 액세스.

• 사용자 ID에 기반한 조건부 도구 활성화 지원.

MCP Remote

MCP Remote 라이브러리는 Inspector 같은 MCP 클라이언트가 호출할 수 있는 도구를 서버가 외부에 노출시킬 수 있게 합니다. 이 라이브러리는:

• 클라이언트와 서버 간 통신 프로토콜을 정의힙니다.

• 도구를 정의하는 구조화된 방법을 제공합니다.

• 요청과 응답의 직렬화/역직렬화를 처리합니다.

• 점Ⓛ 클라이언트 통신을 위해 Streamable HTTP(권장) 및 Server-Sent Events(SSE) 프로토콜을 모두 지원합니다.

전송 프로토콜 마이그레이션

이 예제는 더 이상 사용되지 않는 Server-Sent Events (SSE) 프로토콜을 대체하는 새 Streamable HTTP 전송 프로토콜을 지원하도록 업데이트했습니다. 이제 서버는 다음과 같은 두 엔드포인트를 모두 노출합니다:

• /mcp - 권장됨: 새 Streamable HTTP 프로토콜 사용

• /sse - 더 이상 사용되지 않음: 기존 SSE 프로토콜(하위 호환성을 위해 유지)

새로운 통합은 모두 /mcp 엔드포인트를 사용해야 합니다. SSE 엔드포인트는 이후 버전에서 제거될 예정입니다.