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

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

핵심 요약

Claude MCP 서버 구축 시 Claude Desktop(API 키)과 Claude.ai(OAuth)의 인증 방식 차이와 구현 노하우를 공유한다.

배경

옵션 분석 플랫폼 운영자가 사용자들이 Claude에서 실시간 시장 데이터를 조회할 수 있도록 MCP 서버를 구축하면서 겪은 인증 구현 과정과 시행착오를 정리했다.

의미 / 영향

MCP 서버 개발 시 타겟 클라이언트에 따라 인증 전략을 달리해야 하며, 특히 웹 UI 지원을 위해서는 OAuth와 SSE 최적화가 필수적이다. API 키는 개발 초기 검증용으로 유용하지만 확장성을 고려하면 처음부터 OAuth를 고려하는 것이 효율적이다.

커뮤니티 반응

작성자의 경험 공유에 대해 질문과 답변이 오가는 긍정적인 분위기이다.

주요 논점

01찬성다수

웹 UI 사용자를 위해 OAuth 구현이 반드시 필요하다

합의점 vs 논쟁점

합의점

Claude.ai 웹 UI는 OAuth만 지원한다
SSE 통신을 위해 Nginx 버퍼링을 꺼야 한다

논쟁점

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 서버에서 네트워크 계층의 최적화가 필수적임을 시사한다.

실무 Takeaway

Claude.ai 웹 UI는 OAuth만 지원하므로 대중적인 서비스를 목표로 한다면 OAuth 구현이 필수적이다.
Claude Desktop은 JSON 설정 파일을 통한 API 키 방식이 더 간편하고 효율적이며 개발 초기 검증에 유리하다.
Nginx 프록시 사용 시 SSE 지원을 위해 proxy_buffering 설정을 반드시 꺼야 하며 경로 처리에 주의해야 한다.

언급된 도구

Clerk추천

Authentication provider

Nginx중립

Reverse proxy for SSE

MCP SDK추천

OAuth plumbing and server implementation

언급된 리소스

DemoGammaHero MCP API Endpoint