MCP 서버 OAuth 인증 설정 방법 5단계
- 보호된 원격 MCP 서버는 보통 Streamable HTTP에서 OAuth 리소스 서버로 동작하며, 토큰을 직접 발급하지 않고 검증합니다.
- 보호 리소스 메타데이터와 인증 서버 메타데이터를 통해 클라이언트가 인증 서버와 권한 정보를 찾습니다.
- 토큰의 유효성뿐 아니라 대상 리소스와 필요한 권한 범위를 확인하고, 도구별 최소 권한을 적용해야 합니다.
MCP 서버에 OAuth를 설정하려면 인증 서버를 정하고, MCP 서버가 보호 리소스 메타데이터를 제공하도록 구성한 뒤, 요청에 포함된 액세스 토큰을 검증해야 합니다. 일반적인 구성에서 인증 서버는 로그인과 토큰 발급을 담당하고 MCP 서버는 보호 리소스 서버로서 토큰을 확인합니다. 아래 절차는 OAuth로 보호하는 원격 MCP 서버를 기준으로 설명합니다.
MCP OAuth 인증에서 먼저 구분할 역할
인증 서버와 MCP 서버는 역할이 다릅니다
OAuth 인증 서버(Authorization Server)는 사용자를 인증하고 토큰을 발급합니다. MCP 서버는 보호 리소스 서버(Resource Server)로서 토큰의 유효성과 대상 리소스, 요청에 필요한 권한을 확인합니다. 기존 조직의 ID 공급자나 OAuth 서비스를 인증 서버로 사용할 수 있습니다. MCP 서버가 인증 서버 역할까지 맡는 구성도 가능하지만, 두 역할을 분리할 수 있습니다.
원격 HTTP와 로컬 stdio를 구별합니다
원격 MCP 인증 명세는 HTTP 기반 요청에서 OAuth 토큰을 사용하는 흐름을 정의합니다. Streamable HTTP를 쓰는 경우 토큰은 보통 HTTP의 Authorization 헤더로 전달됩니다. stdio는 HTTP 요청 헤더를 사용하지 않으므로 이 OAuth 흐름이 그대로 적용되지 않습니다. 로컬 서버에서는 실행 프로세스의 신뢰 경계와 파일·자원 접근 권한도 함께 관리해야 합니다.
설정 전에 공개 엔드포인트, 인증 서버의 발급자(issuer) 정보, 필요한 권한 범위를 정하세요. MCP 서버는 OAuth 보호 리소스 메타데이터를 제공해 클라이언트가 사용할 인증 서버를 찾도록 해야 합니다.
설정 전 인증 방식을 선택하세요
사용자별 데이터 접근은 사용자 위임 흐름으로
각 사용자의 계정 권한으로 캘린더나 저장소에 접근해야 한다면 사용자 인증과 동의를 거치는 위임 흐름을 검토하세요. 서버는 토큰에 담긴 사용자 정보와 권한을 확인하고, 요청한 도구가 그 권한 안에서 실행되는지 검사해야 합니다. 모든 요청에 서버 공용 API 키 하나만 사용하는 구성은 사용자별 접근 경계를 표현하지 못할 수 있습니다.
서버 간 자동화는 인증 서버와 클라이언트 지원을 확인합니다
사람의 로그인 없이 예약 작업이나 서버 간 통신만 수행하는 경우에는 OAuth client credentials 방식 같은 기계 간 인증을 검토할 수 있습니다. MCP의 OAuth Client Credentials 확장은 선택 사항이며 문서에서 초안으로 표시되므로, 적용하려는 클라이언트와 인증 서버가 실제로 지원하는지 확인하세요. 이 방식은 사용자 동의나 사용자별 권한을 자동으로 제공하지 않습니다. 운영 환경의 비밀값은 코드 저장소나 설정 파일에 평문으로 두지 말고 비밀 관리 시스템 등으로 보호하세요.
| 사용 사례 | 검토할 방식 | 주의할 점 |
|---|---|---|
| 개인 계정 데이터에 접근 | 사용자 OAuth 위임 | 사용자와 권한 범위 확인 |
| 서버 간 정기 작업 | 인증 서버가 지원하는 서비스 인증 | 클라이언트 호환성, 비밀값 보호, 최소 권한 |
| 로컬 개인 도구 | stdio와 로컬 자격 증명 관리 | 프로세스 및 운영체제 접근 권한 제한 |
MCP 서버 OAuth 인증 설정 5단계
1단계: HTTPS 엔드포인트와 인증 서버를 준비합니다
클라이언트가 접근할 MCP 엔드포인트를 정하고, 원격 운영 환경에서는 HTTPS를 적용합니다. 인증 서버가 발급자 정보와 인증·토큰 엔드포인트를 메타데이터로 제공하는지 확인하세요. 인증 코드 흐름을 사용하는 클라이언트의 리다이렉트 URI는 등록된 값과 정확히 일치해야 합니다. 로컬 테스트 주소와 운영 도메인을 구분하고 배포 후 등록값을 확인하세요.
2단계: 권한 범위를 설계합니다
scope(토큰이 허용하는 작업 범위)를 도구 기능에 맞춰 설계합니다. 예를 들어 조회 기능과 데이터 수정 기능에 같은 권한을 부여하지 않도록 읽기와 쓰기 권한을 나눌 수 있습니다. 어떤 도구가 어떤 범위를 요구하는지 정하고, 서버가 실제 도구 호출 때 해당 권한을 검사해야 합니다. 메타데이터에 범위를 표시하는 것만으로 접근 제어가 완성되지는 않습니다.
3단계: 보호 리소스 메타데이터를 제공합니다
MCP 서버의 보호 리소스 메타데이터는 리소스 주소와 연결된 인증 서버 등의 정보를 클라이언트에 알립니다. 메타데이터의 well-known 경로는 리소스 URI와 서버 라우팅에 따라 달라질 수 있으므로, 고정된 단일 URL이라고 가정하지 말고 MCP 명세와 사용 중인 SDK 문서를 확인하세요. 클라이언트는 이 정보를 바탕으로 인증 서버 메타데이터를 조회하고 인증 흐름을 진행합니다.
4단계: 토큰 검증과 요청별 권한 검사를 연결합니다
토큰 검증기는 서명 검증이나 인증 서버의 토큰 인트로스펙션 등 신뢰할 수 있는 방법으로 토큰을 확인해야 합니다. 만료, 발급자, 대상 리소스(audience 또는 resource), 사용자 정보와 권한 범위를 검증하세요. 유효하지 않은 토큰은 거부하고, 토큰은 유효하지만 해당 도구에 필요한 권한이 부족한 요청도 허용하지 않아야 합니다. JWT(JSON Web Token)는 내용을 디코딩하는 것만으로 유효하다고 판단할 수 없습니다.
5단계: 클라이언트의 인증 흐름을 점검합니다
토큰이 없는 요청에 MCP 서버가 401 응답과 인증 정보를 제공하고, 클라이언트가 보호 리소스 메타데이터를 조회해 인증 서버를 찾는지 확인합니다. 인증 코드 흐름에서는 PKCE를 포함한 명세상 보호 절차와 클라이언트·인증 서버의 호환성을 점검하세요. 인증을 마친 뒤 토큰이 요청에 전달되는지, 서버가 이를 검증하고 요청을 처리하는지도 확인합니다.
점검 기준: 토큰을 받았다는 사실만으로 접근을 허용하지 마세요. 토큰이 해당 MCP 서버를 대상으로 발급됐는지, 만료되지 않았는지, 요청에 필요한 권한이 있는지 확인해야 합니다.
연결 테스트와 자주 발생하는 오류
배포 전에 정상 권한 사용자, 권한이 부족한 사용자, 만료되었거나 잘못된 토큰으로 각각 점검합니다. 도구 목록 조회뿐 아니라 실제 도구 호출에도 서버 측 권한 검사가 적용되는지 확인하세요.
- 401이 계속 발생함: 토큰이 전달되는지, 보호 리소스 메타데이터와 인증 서버 정보가 일치하는지 확인합니다.
- 로그인은 되지만 도구가 거부됨: 토큰의 대상 리소스와 scope, 도구별 권한 매핑을 확인합니다.
- 리다이렉트 단계에서 중단됨: 등록된 URI와 클라이언트가 보내는 URI가 일치하는지 확인합니다.
- 로컬에서는 되지만 배포 후 실패함: HTTPS 프록시 설정과 외부에서 보이는 공개 주소, 경로별 메타데이터 구성을 확인합니다.
로그에는 오류 유형과 요청 추적 정보만 남기고 액세스 토큰, 클라이언트 시크릿, 인증 코드 전체를 기록하지 마세요. 갱신 토큰은 안전하게 보관하고, 사용자가 연결을 해제하거나 권한을 회수할 때 처리할 경로도 마련하세요. 데이터 수정 도구에는 필요한 권한만 부여하고 제품의 승인 절차도 함께 설계합니다.
운영 환경에 적용하기 전 최종 확인
- 원격 엔드포인트가 HTTPS로 제공되고 메타데이터가 올바르게 조회되는가
- scope가 필요한 권한을 나타내며 도구 호출 시 실제 검사되는가
- 토큰의 발급자, 대상 리소스, 만료, 권한을 검증하는가
- 시크릿과 토큰이 소스 코드, 오류 로그, 사용자에게 노출되지 않는가
- 만료, 철회, 인증 서버 장애 시 요청을 안전하게 거부하는가
SDK를 사용할 때는 선택한 프레임워크와 버전의 공식 문서를 확인하세요. 예를 들어 MCP 공식 Python SDK 서버 인증 문서는 토큰 검증기와 보호 리소스 메타데이터의 역할을 설명합니다. SDK가 로그인 화면이나 토큰 발급까지 제공한다고 가정하지 말고, 사용할 인증 서버와 연동 지점을 확인하세요.
자주 묻는 질문
Q. MCP 서버 자체에서 OAuth 토큰을 발급해야 하나요?
일반적인 구성에서는 인증 서버가 로그인과 토큰 발급을 맡고 MCP 서버는 토큰을 검증하는 보호 리소스 서버로 동작합니다. 두 역할을 한 서비스에 배치할 수도 있지만, MCP 명세는 인증 서버를 별도 구성 요소로도 허용합니다.
Q. OAuth 인증은 stdio MCP 서버에서도 그대로 적용되나요?
아닙니다. HTTP 헤더로 토큰을 전달하는 원격 MCP 인증 흐름은 stdio에 그대로 적용되지 않습니다. 로컬 프로세스를 누가 실행할 수 있는지, 프로세스가 어떤 파일과 자원에 접근하는지 운영체제 수준에서 제한해야 합니다.
Q. 액세스 토큰이 유효하면 모든 MCP 도구를 허용해도 되나요?
아닙니다. 토큰이 해당 서버를 대상으로 발급됐는지와 scope, 사용자별 권한을 확인하고 도구 호출마다 필요한 권한을 검사해야 합니다. 조회와 변경 기능은 가능한 범위를 나눠 관리하세요.
Q. MCP 클라이언트마다 OAuth 설정을 다시 해야 하나요?
클라이언트가 MCP 인증 명세와 서버 메타데이터를 지원하는지, 인증 서버의 클라이언트 등록 방식을 지원하는지에 따라 설정이 달라질 수 있습니다. 연결 전에 해당 클라이언트의 원격 MCP·OAuth 지원 방식과 공식 문서를 확인하세요.
