MCP 서버 구축 시 인증 구현 경험 공유: API 키와 OAuth의 차이

실용적 조언

Claude.ai 웹 사용자를 타겟팅한다면 처음부터 OAuth 구현을 우선순위에 두어야 한다.
Nginx 설정 시 proxy_buffering off와 proxy_set_header Connection '' 등을 적용하여 SSE 스트림 끊김을 방지해야 한다.
API 키와 OAuth를 동시에 지원하도록 토큰 로더에서 폴백 로직을 구현하면 다양한 클라이언트를 수용할 수 있다.

섹션별 상세

Claude Desktop용으로 가장 먼저 API 키 방식의 인증을 구현했다. 사용자가 설정에서 생성한 API 키를 MCP 클라이언트 설정의 Bearer 토큰으로 추가하면, 서버가 DB에서 이를 검증하여 사용자를 식별하는 방식이다. 하루 만에 구현 가능할 정도로 간단하지만, Claude.ai 웹 UI의 커넥터 시스템에서는 정적 API 키를 지원하지 않는다는 한계가 있다. 기술적으로는 단순한 헤더 검증 로직만으로 작동하므로 초기 개발 단계에서 유용하다.

Claude.ai 웹 사용자를 위해 OAuth 흐름을 추가로 구현했다. MCP SDK가 제공하는 엔드포인트(authorize, token 등)를 활용하되, 사용자 동의 페이지는 기존 인증 서비스인 Clerk과 통합하여 구현했다. 이를 통해 사용자가 플랫폼에 로그인되어 있다면 '허용' 버튼 클릭만으로 인증 코드가 발급되고, Claude가 이를 토큰으로 교환하여 도구 호출 시마다 인증을 수행한다. 웹 환경의 보안 요구사항을 충족하면서도 기존 사용자 세션을 재활용할 수 있는 구조이다.

현재 프로덕션 환경에서는 API 키와 OAuth 두 가지 인증 방식을 병행하여 운영 중이다. 토큰 로더가 OAuth 토큰을 먼저 확인하고 없으면 API 키로 폴백하는 구조를 채택하여, 사용자가 접속하는 클라이언트에 관계없이 동일한 사용자 경험을 제공한다. 두 방식 모두 내부적으로는 동일한 사용자 ID로 매핑되어 속도 제한이나 사용량 분석이 통합 관리된다. 이는 클라이언트 파편화 문제를 서버 측 로직으로 해결한 사례이다.

MCP의 전송 방식인 SSE를 처리하기 위해 Nginx 프록시 설정에서 특이사항이 발견됐다. proxy_buffering off 설정을 하지 않으면 스트림이 응답 없이 멈추는 현상이 발생하며, 프록시 경로의 끝에 슬래시(/)가 포함될 경우 POST 요청이 오류 없이 실패하는 문제가 있었다. 이러한 인프라 설정 오류는 명시적인 에러 메시지가 없어 추적에 상당한 시간이 소요됐다. 실시간 데이터 전송이 핵심인 MCP 서버에서 네트워크 계층의 최적화가 필수적임을 시사한다.

용어 해설

모델 컨텍스트 프로토콜(MCP): — LLM이 외부 데이터 소스나 도구에 안전하게 접근할 수 있도록 돕는 개방형 표준 프로토콜이다. 서버와 클라이언트 간의 통신 규약을 정의하여 AI 에이전트의 기능을 확장하는 데 핵심적인 역할을 한다.
서버 전송 이벤트(SSE): — 서버에서 클라이언트로 실시간 데이터를 스트리밍하는 기술이다. MCP에서 도구 호출 결과나 상태를 실시간으로 전달하기 위해 사용되며, 단방향 통신에 최적화되어 있다.
오픈 인증(OAuth): — 사용자가 비밀번호를 직접 공유하지 않고도 제3자 애플리케이션에 자신의 데이터 접근 권한을 부여할 수 있게 하는 개방형 인증 표준이다. 웹 서비스 간 안전한 연동을 가능케 한다.
베어러 토큰(Bearer Token): — HTTP 요청 헤더에 포함되어 리소스 접근 권한을 증명하는 토큰이다. '이 토큰을 소지한 자'에게 접근을 허용하는 방식으로, API 키 인증 시스템에서 널리 사용되는 표준 방식이다.
프록시 버퍼링(Proxy Buffering): — 프록시 서버가 백엔드 응답을 클라이언트에 전달하기 전 임시로 저장하는 기능이다. SSE와 같은 스트리밍 통신에서는 데이터가 즉시 전달되지 않고 끊기는 문제를 유발하므로 비활성화가 필요하다.

언급된 도구

Clerk추천

Authentication provider

Nginx중립

Reverse proxy for SSE

MCP SDK추천

OAuth plumbing and server implementation

언급된 리소스

DemoGammaHero MCP API Endpoint