MCP Authorization spec과 대부분의 MCP 클라이언트는 사람이 존재한다고 가정합니다. 즉, 브라우저를 열고, 동의하고, 토큰을 받고, 세션이 만료될 때까지 과정을 진행한 뒤 다시 반복하는 방식입니다. 이러한 모델은 키보드 앞에 사람이 없는 상태에서 OAuth로 보호된 MCP 서버와 통신해야 하는 자율 에이전트(autonomous agent), CI 작업, 데몬(daemon) 또는 기타 장기 실행 프로세스가 필요한 즉시 무너집니다.

**mcp-client-credentials-auth**는 이러한 공백을 메우기 위한 로컬 MCP 인증 프록시(proxy)입니다. 이 프록시는 MCP 클라이언트와 원격 MCP 서버 사이에 위치하여, OAuth client_credentials 승인 방식(MCP OAuth Client Credentials extension 초안)으로 토큰을 획득하고, Bearer 토큰과 함께 MCP 트래픽을 전달합니다. 사용자의 MCP 클라이언트는 인증되지 않은 일반 MCP 방식으로 계속 통신하고, 프록시가 인증을 처리합니다.

이 포스트는 두 부류의 독자를 대상으로 합니다. 현재 원격 MCP 서버에 대한 머신 액세스(machine access)가 필요한 사람들과, 해당 액세스를 위해 추천할 수 있는 준비된 클라이언트 경로를 원하는 MCP 서버 제공자들입니다.

이를 사용하려면 MCP 서버 제공자가 OAuth client_credentials를 통한 머신 인증을 지원해야 합니다. 실제로 이는 해당 승인 방식에 대해 OAuth 설정이 허용하는 client_id 및 client_secret을 가진 서비스 계정(때로는 "API key", "machine-to-machine application" 또는 유사한 명칭으로 표시됨)이 있음을 의미합니다. 이러한 자격 증명(credentials)을 생성하는 것은 종종 제공자의 계정이나 개발자 포털에서 셀프 서비스로 이루어지거나, 요청 시 제공됩니다. 대화형 전용 서버(브라우저 로그인 / 사용자 동의만 가능)는 이 프록시의 범위를 벗어납니다.

사용 사례 (The use case)

호출자가 사람이 아닌 머신이며, 동시에 원격 MCP 제공자가 해당 서비스 계정 스타일의 액세스를 제공하는 경우라면 언제든 사용하십시오:

• 보호된 원격 MCP로부터 도구(tools), 리소스(resources) 또는 프롬프트(prompts)를 가져와야 하는 자율 에이전트(Autonomous agents) 및 백그라운드 워커(background workers)
• CI/CD 파이프라인 및 운영 자동화(ops automations)
• 사람이 키보드 앞에 없을 수도 있는 서버 간 통합(Server-to-server integrations) 및 장기 실행 프로세스(long-running processes)

또한, MCP 클라이언트의 최적화되지 않은 대화형 인증 UX에 지쳤을 때, MCP 서버가 인증되지 않았다는 사실을 쉽게 놓쳐 더 이상 도구에 접근할 수 없게 되는 상황을 방지하고 싶을 때도 사용할 수 있습니다.

제공자로부터 자격 증명(credentials)을 받았다면, 프록시(proxy)를 원격 MCP URL로 지정하고 MCP 클라이언트 설정에 넣기만 하면 됩니다. 프록시는 액세스 토큰(access tokens)을 획득하고, 선제적으로 이를 갱신(refresh)하며, 원격 MCP 서버가 불안정할 때(flaps) 재연결을 수행하고, 프로토콜에 대해 투명성(transparent)을 유지합니다.

단순함을 유지하는 설치 (디스커버리 기능 덕분에)

규칙을 잘 준수하는 MCP 서버는 MCP 인증(MCP Authorization) 메타데이터(RFC 9728 / RFC 8414)를 게시합니다. 프록시는 해당 디스커버리(discovery) 경로를 따르므로, 일반적으로 토큰 엔드포인트(token endpoint)를 수동으로 구성하거나 스코프(scopes)를 임의로 만들 필요가 없습니다.

Cursor 또는 Claude Code와 같은 MCP 클라이언트에서의 일반적인 설정은 세 개의 환경 변수입니다:

{
  "mcpServers": {
    "my-remote-server": {
...

이것이 일반적인 경로를 위한 설치의 전부입니다: 원격 MCP 서버 URL + client_id + client_secret. 디스커버리를 통해 IdP 토큰 엔드포인트와 기본 스코프(baseline scopes)를 찾아냅니다. 프록시는 시작 시 인증이나 원격 연결을 준비할 수 없는 경우 'fail closed'(실패 시 차단) 방식으로 작동하므로, 첫 번째 실제 호출에서 끊겨버리는 가짜 로컬 세션(green local session)을 갖게 되는 일을 방지합니다.

npx는 게시된 패키지를 사용자의 머신에 다운로드하여 실행하므로, 신뢰할 수 있는 패키지만 사용하십시오 (다른 모든 npx MCP 서버와 동일한 주의 사항).

만약 서버가 Bearer 토큰을 수락하지만 discovery(탐색) 정보를 공개하지 않는 경우에도, 수동 토큰 엔드포인트(token endpoint)와 스코프(scopes) (MCP_CC_PROXY_TOKEN_ENDPOINT 및 일반적으로 MCP_CC_PROXY_SCOPES)를 사용하여 실행할 수 있습니다. 해당 값들은 반드시 MCP 서버 제공업체의 문서에서 가져와야 하며, 임의로 만들어내려 하지 마십시오. MCP 서버가 지원하는 경우에는 auto-discovery (자동 탐색)를 사용하는 것이 좋습니다.

두 가지 배포 옵션

1. Local stdio (기본값): 하나의 클라이언트, 하나의 프록시 프로세스

이것이 위의 설치 경로입니다. 귀하의 MCP 클라이언트는 동일한 머신에서 stdio를 통해 프록시를 생성하며(프록시가 로컬 MCP Server 역할을 수행), 프록시는 Bearer 인증을 사용하여 원격 서버와 아웃바운드 HTTPS 통신을 합니다. 각 사용자(또는 에이전트 호스트)는 모든 노트북 설정에 복사되는 조직 전체의 공유된 secret(비밀값)이 아니라, 자신만의 서비스 계정(service-account) 자격 증명을 사용해야 합니다.

적합한 경우:

• 단일 MCP 클라이언트(IDE, 에이전트 호스트, CLI)가 로컬 MCP Server 프로세스를 생성할 수 있는 경우
• 각 사용자가 자신만의 client_credentials 클라이언트를 획득(또는 발급)할 수 있는 경우
• 가장 작은 공격 표면(attack surface)을 원하는 경우: 로컬 네트워크 리스너가 없음
• 자격 증명이 해당 머신 또는 해당 클라이언트의 secret store(비밀 저장소)에 머무는 경우

하나의 클라이언트가 프록시의 생명주기(lifecycle)를 관리할 수 있다면 언제든 stdio를 선호하십시오. 이는 Cursor, Claude Desktop, Claude Code 및 유사한 로컬 설정에 적합한 기본값입니다.

2. On-premises HTTP: 하나의 공유 프록시와 여러 클라이언트를 위한 ID

MCP_CC_PROXY_TRANSPORT=http를 설정하세요. 이 프로세스는 Streamable HTTP를 수신 대기하므로, 프라이빗 네트워크(private network) 상의 여러 MCP 클라이언트가 하나의 아웃바운드 client_credentials 신원을 공유할 수 있습니다. 또한, HTTP를 기본 전송 방식(transport)으로 사용하고 k8s 스타일의 상태 확인(health checks)을 지원하여 배포가 용이한 컨테이너 이미지도 제공됩니다.

적합한 상황:

• 신뢰할 수 있는 프라이빗 네트워크 상의 여러 MCP 클라이언트가 하나의 머신 신원(machine identity)을 공유해야 할 때
• 모든 워크스테이션에 프록시를 설치하거나 실행하고 싶지 않을 때
• 단일 MCP 클라이언트(IDE, 에이전트 호스트, CLI)가 로컬 MCP 서버 프로세스를 실행할 수 없지만 원격 서버를 사용해야 할 때

HTTP 모드는 프록시 자체에 TLS나 인바운드 인증이 없습니다. 보안 고려 사항(Security considerations)을 참조하세요.

"연결됨" 그 이상의 기능

• 투명한 양방향 MCP 포워딩 (bidirectional MCP forwarding)
• 신원 및 기능 포워딩 (클라이언트가 샘플링(sampling) 및 유도(elicitation)와 같은 서버-클라이언트 기능을 포함하여, 원격 서버의 실제 이름과 기능을 볼 수 있음)
• 선제적인 액세스 토큰 갱신(access token refresh) 및 401 재시도 동작
• 원격 서버가 403 insufficient_scope로 요청할 때의 범위 단계 격상 (Scope step-up)
• 연결 클래스 오류 발생 시 SSE 폴백(fallback)을 지원하는 Streamable HTTP
• 자동 재연결 및 만료된 원격 세션 복구
• 선택적 호출 감사 로그 (HTTP 모드에서는 기본적으로 활성화됨)
• 문제 해결을 용이하게 하기 위해 상세 메시지를 포함한 카테고리별 오류 (authentication / connection / remote)
• Fail-closed 시작: 로컬 전송 방식은 인증이 준비되고 원격 MCP 서버에 도달 가능한 상태가 된 후에만 바인딩되므로, MCP 클라이언트가 정확한 상태를 표시할 수 있음

보안 고려 사항 (Security considerations)

기능 목록보다 더 중요한 몇 가지 원칙이 있습니다:

• 서비스 계정을 강력한 권한을 가진 것으로 취급하십시오. client_id / client_secret을 보유한 사람(또는 이미 이를 보유한 HTTP 모드 프록시에 접근할 수 있는 사람)은 해당 원격 권한을 얻게 됩니다. stdio의 경우 사용자별 클라이언트 (per-user clients)를 선호하고, 침해 사고 발생 시 교체(rotate)하십시오.
• 평문 MCP 설정 대신 Vault 사용을 권장합니다. 위의 설치 스니펫은 간결함을 위해 환경 변수에 비밀 정보를 표시했습니다. 프로덕션 환경에서는 client_id / client_secret을 디스크 상의 MCP 설정 파일에 남겨두는 대신, 실행 시 1Password, Bitwarden, 클라우드 비밀 저장소 (cloud secret store) 또는 이와 유사한 도구로부터 주입하십시오.
• 프록시를 비공개로 유지하십시오. stdio는 네트워크 리스너 (network listener)가 없습니다. HTTP 모드는 신뢰할 수 있는 사설 네트워크 (private networks) 전용입니다. 리버스 프록시 (reverse proxy), 인그레스 (ingress) 또는 MCP 게이트웨이에서 TLS 종료 및 인바운드 인증을 처리하는 것을 권장합니다. 리스너를 공용 인터넷에 절대 공개하지 마십시오.
• HTTP 모드는 하나의 공유된 머신 ID (machine identity)입니다. 모든 MCP 클라이언트는 동일한 아웃바운드 Bearer 토큰과 스코프 (scopes)를 재사용합니다. 이는 멀티 테넌트 (multi-tenant) 엣지가 아니므로, 신뢰 경계 (trust boundary)마다 별도의 배포를 사용하십시오.
• 프록시가 아웃바운드 Authorization 헤더를 소유합니다. 액세스 토큰 (access tokens)은 메모리에 머물며 절대 로그에 남지 않으며, 로컬 MCP 클라이언트는 원격 서버로 사용되는 Bearer 토큰을 제공하거나 재정의할 수 없습니다.

더 자세한 내용은 리포지토리의 Security 섹션에 있습니다.

MCP 서버 제공자를 위한 안내 (For MCP server providers)

이미 대화형 클라이언트를 위해 OAuth로 MCP 서버를 보호하고 있다면, 사용자들은 에이전트, CI 및 기타 헤드리스 호출자 (headless callers)가 어떻게 인증해야 하는지 여전히 물어볼 것입니다. 모든 IDE와 에이전트 호스트를 위해 맞춤형 M2M 클라이언트를 배포할 필요는 없습니다. 이 프록시를 서비스 계정 액세스를 얻는 지원되는 방식으로 문서화하십시오. 사용자는 client_id / client_secret을 생성(또는 수령)하고, 프록시를 귀하의 MCP URL로 지정하기만 하면 기존의 일반 MCP 클라이언트를 계속 사용할 수 있습니다.

이 방식은 귀하의 제품이 이미 머신 자격 증명 (machine credentials)과 표준 MCP Authorization discovery를 제공할 때 가장 효과적입니다:

• 보호된 리소스(protected resource) / 권한 부여 서버(authorization server) 메타데이터를 게시하여 프록시가 토큰 엔드포인트(token endpoint)와 기본 스코프(baseline scopes)를 찾을 수 있도록 합니다.
• client_credentials를 위해 해당 기본 스코프가 부여된 서비스 계정(service account, 또는 그에 상응하는 것)을 제공합니다.
• 직접 OAuth 클라이언트를 구축하는 과정을 설명하기보다, 원격 URL + 자격 증명 (+ 이 프록시)과 같은 짧은 설정 가이드를 선호합니다.

사용자는 토큰 획득 과정을 직접 구축하지 않고도 보안이 유지되는 장기적이고 비대화형(non-interactive)인 서비스 계정 액세스를 얻을 수 있습니다. 개발자는 인간의 동의 흐름(human consent flows)과 머신 호출자(machine callers) 모두를 위해 하나의 OAuth로 보호된 MCP 접점(surface)을 유지할 수 있으며, 머신 경로를 파편화된 일회성 스크립트 대신 탐색 친화적인(discovery-friendly) 알려진 클라이언트로 지정할 수 있습니다.

만약 아직 탐색(discovery) 기능을 사용할 수 없다면, 여전히 프록시를 추천할 수 있지만 필요한 설정값들을 직접 문서화해야 합니다: 즉, IdP 토큰 엔드포인트 URL과 요청할 스코프(MCP_CC_PROXY_TOKEN_ENDPOINT 및 MCP_CC_PROXY_SCOPES)입니다. 사용자는 여러분의 안내 없이는 이를 탐색할 수 없습니다. 탐색 기능을 게시할 수 있는 상황이라면 자동 탐색(Auto-discovery)이 여전히 더 매끄러운 방식입니다.

더 자세한 내용은 MCP 서버 개발자를 위한 노트를 참조하세요.

링크 (Links)

• GitHub: velias/mcp-client-credentials-auth
• npm: mcp-client-credentials-auth
• Container: ghcr.io/velias/mcp-client-credentials-auth
• Spec: MCP Authorization
• Spec: MCP OAuth Client Credentials

결론 (Conclusion)

에이전트나 파이프라인을 위해 OAuth로 보호된 MCP를 실행하거나, MCP 서버를 운영하면서 사용자에게 쉬운 M2M 클라이언트 경로를 제공하고 싶다면, 탐색(discovery)과 서비스 계정 자격 증명(service-account credentials)부터 시작하여 나머지 부분은 프록시가 클라이언트 측에서 처리하도록 하세요. 피드백과 이슈는 리포지토리(repo)를 통해 언제든 환영합니다.