Provides OAuth authorization for the MCP server, supporting dynamic client registration and identity provider connections like Google and GitHub
Recommended as the JavaScript runtime and package manager for the MCP server implementation
Referenced as having implemented Workers OAuth MCP servers that could be extended in future versions of this project
이 저장소는 MCP 사양에 따라 OAuth로 인증된 Streamable HTTP 및 SSE 전송을 지원하는 원격 MCP 서버를 만드는 데 필요한 참조 구현을 제공합니다.
이 저장소의 MCP 서버는 SSE + HTTP 전송 보고서를 처리하는 애플리케이션과 OAuth와 논리적으로 분리되어 있습니다.
그 결과, 여러분은 이 저장소를 쉽게 포크하고, 여러분만의 기능을 갖춘 SSE/HTTP + OAuth MCP 서버에 여러분만의 MCP 서버와 OAuth 자격 증명을 추가할 수 있습니다.
하지만, 왜 그럴까?
좋은 질문입니다! MCP 사양은 2025년 3월 25일에 OAuth 기반 권한 부여 사양을 추가했습니다. 2025년 5월 1일 현재:
StreamableHttpClientTransport 클래스를 사용하여 JavaScript로 작성된 에이전트에 직접 통합될 수 있지만 Cursor 및 Claude 데스크톱과 같은 MCP 호스트 애플리케이션에서는 전반적으로 지원되지 않습니다.Naptha AI 에서는 스트리밍 가능한 HTTP 전송에서 OAuth 인증 MCP 서버를 구축하고 싶었지만, 참조 구현을 찾을 수 없어서 직접 구축하기로 결정했습니다!
빠른 올인원 JavaScript 런타임인 Bun 은 이 저장소에 권장되는 런타임이자 패키지 관리자입니다. npm + tsc 와의 호환성 테스트는 제한적으로 수행되었습니다.
이 저장소는 다음을 제공합니다.
이 익스프레스 애플리케이션은 자격 증명과 MCP 서버를 연결하는 것입니다.
이 Express 앱은 /authorize 및 Authorization Server Metadata 엔드포인트( RFC8414 )를 비롯한 필수 OAuth 엔드포인트를 구현하지만 OAuth 인증 서버는 구현하지 않습니다!
이 예제는 동적 클라이언트 등록( RFC7591 )을 지원하는 업스트림 OAuth 서버로 OAuth를 프록시합니다. 이 예제를 사용하려면 자체 권한 부여 서버를 사용해야 합니다. Auth0 사용을 권장합니다. 아래 "OAuth 설정" 섹션을 참조하세요.
이 예제를 사용하려면 OAuth 인증 서버가 필요합니다. 직접 구현하지 마세요! 데모를 만들기 위해 Auth0를 사용했습니다. 다른 옵션도 많지만, 이보다 훨씬 좋은 옵션입니다.
MCP 사양은 흔하지 않은 OAuth 기능, 특히 RFC7591 (동적 클라이언트 등록)에 대한 지원을 요구합니다. MCP 사양은 MCP 클라이언트와 서버가 동적 클라이언트 등록 프로토콜을 지원해야 한다고 명시하고 있습니다. 이를 통해 MCP 클라이언트(클라이언트 전송이 활성화되어 있는지 여부와 관계없이)는 사용자 등록 없이 클라이언트 ID를 얻을 수 있습니다. 이를 통해 새 클라이언트(에이전트, 앱 등)가 새 서버에 자동으로 등록됩니다. 이에 대한 자세한 내용은 MCP 사양의 권한 부여 섹션에서 확인할 수 있지만, 안타깝게도 Google이나 GitHub와 같이 동적 클라이언트 등록을 지원하지 않는 제공업체에 직접 프록시할 수는 없습니다(이러한 제공업체는 UI에서 클라이언트를 등록해야 합니다).
이렇게 하면 두 가지 옵션이 제공됩니다.
단순화를 위해 Auth0을 사용하는 이전 옵션을 선택했습니다.
[!메모]
이 구현은 업스트림 OAuth 서버를 프록시하므로, OAuth 서버에서 클라이언트로 액세스 토큰을 전달하는 기본 방식은 사용자의 업스트림 액세스 토큰을 다운스트림 클라이언트와 MCP 호스트에 노출시킵니다. 이는 많은 사용 사례에 적합하지 않으므로, 이 방식에서는 일부@modelcontextprotocol/typescript-sdk클래스를 다시 구현하여 이 문제를 해결합니다.
업스트림 권한 부여 서버를 프록싱하는 동안 최종 사용자의 인증 토큰을 MCP 클라이언트/호스트에 반환 하지 않습니다 . 대신 자체 인증 토큰을 발급하여 클라이언트/호스트가 해당 토큰을 사용하여 서버와 인증할 수 있도록 허용합니다. 이를 통해 악의적인 클라이언트나 호스트가 토큰을 악용하거나, 토큰이 유출될 경우 악용되는 것을 방지할 수 있습니다.
Auth0를 시작하려면:
이 모든 것이 설정되면 다음 정보가 필요합니다.
이 정보를 .env 파일에 반드시 입력하세요. .env.template 파일을 복사한 후 해당 값을 설정 및 비밀번호로 업데이트하세요.
이 저장소에는 두 개의 독립형 서버가 포함되어 있습니다.
src/app.stateless.ts 에 스트리밍 가능한 HTTP 서버의 상태 비저장 구현이 있습니다. 이는 스트리밍 가능한 HTTP 전송만 지원하며, (이론적으로) 서버리스 배포에 적합합니다.src/app.stateful.ts 에 SSE와 스트리밍 가능한 HTTP를 모두 구현 한 상태 저장 구현입니다. 이 앱은 두 가지 전송 방식을 모두 제공하지만, redis 스토리지 전략(연결은 메모리에 저장되어야 함)을 사용하더라도 메모리 내 상태를 유지하므로 서버리스 배포나 간단한 수평 확장에는 적합하지 않습니다.두 가지 모두 bun 으로 실행할 수 있습니다.
지엑스피1
스트리밍 가능한 HTTP 및 OAuth 지원 기능을 갖춘 MCP 서버를 테스트하려면 몇 가지 옵션이 있습니다.
위에서 언급했듯이 Python MCP SDK는 이러한 기능을 지원하지 않으므로 현재는 원격 서버를 Cursor나 Claude Desktop과 같은 MCP 호스트에 연결하거나 TypeScript/JavaScript 애플리케이션에 직접 연결할 수 있지만 Python 애플리케이션에 연결할 수는 없습니다.
대부분의 MCP 호스트는 스트리밍 가능한 HTTP(여러 면에서 SSE보다 우수함) 나 OAuth를 지원하지 않으므로 OAuth 인증을 처리하고 원격 전송을 호스트의 STDIO 전송으로 연결하는 mcp-remote npm 패키지를 사용하는 것이 좋습니다.
명령은 다음과 같습니다.
--transport 옵션에는 몇 가지 옵션이 있습니다.
http-first (기본값): 먼저 HTTP 전송을 시도하고 HTTP가 404 오류로 실패하면 SSE로 대체합니다.sse-first : 먼저 SSE 전송을 시도하고 SSE가 405 오류로 실패하면 HTTP로 대체합니다.http-only : HTTP 전송만 사용하며, 서버에서 지원하지 않으면 실패합니다.sse-only : SSE 전송만 사용하며, 서버에서 지원하지 않으면 실패합니다.[!NOTE]
src/app.stateless.ts사용하여 서버의 상태 비저장 버전을 실행하면 SSE 전송을 사용할 수 없으므로--transport http-only사용해야 합니다. 이 진입점을 사용하면 SSE 전송이 작동하지 않을 수 있습니다.
StreamableHTTPClientTransport 사용하여 Streamable HTTP 서버를 JS/TS 에이전트에 연결할 수 있습니다. 하지만 OAuth로 보호되는 서버에서는 작동하지 않습니다. 대신, 클라이언트 측에서 Authorization 헤더를 사용하고 서버 측에서 유효한 액세스 토큰을 사용해야 합니다.
클라이언트 인증 정보, API 키 또는 기타 다른 방법으로 이를 구현할 수 있습니다. 이 저장소에서는 해당 패턴이 지원되지 않지만, Vercel AI SDK를 사용하면 다음과 같습니다.
This server cannot be installed
OAuth 인증을 통해 Streamable HTTP 및 SSE 전송을 지원하는 MCP 서버를 생성하기 위한 참조 구현으로, 개발자는 최소한의 구성으로 OAuth 인증 MCP 서버를 구축할 수 있습니다.