Model Context Protocol (MCP) Server + Access OAuth

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

자체 Cloudflare 계정에 배포할 수 있으며, 자체 Access for SaaS OIDC 앱을 만든 후에는 이를 기반으로 구축할 수 있는 완전한 기능을 갖춘 원격 MCP 서버를 갖게 됩니다. 사용자는 연결된 Access Identity Provider로 로그인하여 MCP 서버에 연결할 수 있습니다.

Cloudflare Workers로 구동되는 MCP 서버:

• MCP 클라이언트에 대한 OAuth 서버 역할을 수행합니다

• 실제 OAuth 서버(이 경우 Access)에 대한 OAuth 클라이언트 역할을 수행합니다

시작하기

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

프로덕션용

새 Access for SaaS OIDC App을 만듭니다:

• Authorization callback URL에는 https://mcp-access-oauth.<your-subdomain>.workers.dev/callback을 지정하고, 로컬에서 개발하는 경우에는 http://localhost:8788/callback을 지정합니다.

• Client ID와 Client secret을 기록해 둡니다.

• Wrangler를 통해 secrets를 설정합니다

wrangler secret put ACCESS_CLIENT_ID
wrangler secret put ACCESS_CLIENT_SECRET
wrangler secret put ACCESS_TOKEN_URL
wrangler secret put ACCESS_AUTHORIZATION_URL
wrangler secret put ACCESS_JWKS_URL
wrangler secret put COOKIE_ENCRYPTION_KEY # add any random string here e.g. openssl rand -hex 32

KV 네임스페이스 설정

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

• Wrangler 파일에 KV ID를 업데이트합니다

배포 및 테스트

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

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

npx @modelcontextprotocol/inspector@latest

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

이제 원격 MCP 서버가 배포되었습니다!

액세스 제어

이 MCP 서버는 인증에 Access를 사용합니다. 인증된 모든 Access 사용자는 "add"와 같은 기본 도구에 액세스할 수 있습니다.

"generateImage" 도구는 ALLOWED_USERNAMES 구성에 나열된 특정 Access 사용자로 제한됩니다:

// Add user emails for image generation access
const ALLOWED_EMAILS = new Set(["employee1@mycompany.com", "teammate1@mycompany.com"]);

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-access-oauth.<your-subdomain>.workers.dev/mcp"
      ]
    }
  }
}

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

로컬 개발용

MCP 서버를 반복 개선하며 테스트하려면 로컬 개발에서 수행할 수 있습니다.

• Homepage URL에는 http://localhost:8788을 지정합니다

• Authorization callback URL에는 http://localhost:8788/callback을 지정합니다

• Client ID를 기록해 두고 Client secret을 생성합니다.

• 프로젝트 루트에 다음 내용으로 .dev.vars 파일을 만듭니다:

ACCESS_CLIENT_ID=<your client id>
ACCESS_CLIENT_SECRET=<your client secret>
ACCESS_TOKEN_URL=<your Access for SaaS token url>
ACCESS_AUTHORIZATION_URL=<your Access for SaaS authorization url>
ACCESS_JWKS_URL=<your Access for SaaS JWKS url>
COOKIE_ENCRYPTION_KEY=COOKIE_ENCRYPTION_KEY

개발 및 테스트

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

로컬 서버를 테스트하려면 Inspector에 http://localhost:8788/mcp을 입력하고 연결을 누릅니다. 프롬프트를 따르면 "List Tools"를 실행할 수 있습니다.

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

Claude를 사용하여 원격 MCP 서버에 연결할 때 일부 오류 메시지가 표시될 수 있습니다. Claude 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 서버를 사용해야 함).

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

작동 방식

OAuth Provider

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

• 서버에 연결되는 MCP 클라이언트 인증

• Access의 OAuth 서비스에 대한 연결 관리

• KV 스토리지에 토큰과 인증 상태를 안전하게 저장

Durable MCP

Durable MCP는 Cloudflare의 Durable Objects를 사용하여 기본 MCP 기능을 확장하며 다음을 제공합니다:

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

• 요청 간 인증 컨텍스트의 안전한 저장

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

• 사용자 ID에 기반한 조건부 도구 사용 가능 여부 지원

MCP Remote

MCP Remote 라이브러리를 사용하면 서버가 Inspector와 같은 MCP 클라이언트가 호출할 수 있는 도구를 노출할 수 있습니다. 이 라이브러리는:

• 클라이언트와 서버 간 통신을 위한 프로토콜 정의

• 도구를 정의하는 구조화된 방법 제공

• 요청 및 응답의 직렬화와 역직렬화 처리

• 클라이언트와 서버 간 Server-Sent Events (SSE) 연결 유지