상정 독자는, Claude Code로 사내 자체 호스트 API 등을 MCP를 통해 호출하고 싶지만, 로컬 실행 방식인 stdio 연결이 아니라 HTTP/SSE를 경유하는 **원격 MCP 서버 (Remote MCP Server)**에 OAuth로 연결할 필요가 생긴 엔지니어입니다.

전제 조건:

• Claude Code v2.x 계열 (claude --version으로 확인)

• 접속 대상은 OAuth 2.1 (Authorization Code + PKCE) 대응 원격 MCP 서버

• stdio 연결 방식의 MCP 서버는 구축 완료 및 이용 경험이 있다고 가정 (처음인 경우 먼저 로컬 stdio 버전으로 익숙해지는 것을 추천)

• 원격 MCP 서버의 인증은, Claude Code가 「브라우저에서 인가 → localhost에서 콜백 수신 → 토큰 저장 및 자동 갱신」까지 원스톱으로 처리해 줍니다.

• 단, 포트 충돌(Port Conflict) · 토큰 만료(Token Expiration) · 브라우저를 실행할 수 없는 환경의 3가지 상황에서 막히기 쉽습니다. 막혔을 때는 /mcp 명령어로 접속 상태를 확인하고 재인증하면 대부분 해결됩니다.

claude mcp add --transport http my-remote-server https://mcp.example.com/mcp

.mcp.json은 다음과 같은 형태가 됩니다.

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

해당 도구를 호출하는 타이밍에 서버 측에서 OAuth가 필수라고 판단하면, 인가 URL이 표시되거나 브라우저가 자동으로 실행됩니다.

$ claude
> 이 MCP 서버는 인증이 필요합니다. 브라우저에서 인가해 주세요:

브라우저에서 허가하면 http://localhost:PORT/callback?code=...로 리다이렉트(Redirect)되며, Claude Code가 백그라운드에서 띄운 임시 HTTP 서버가 이를 수신하여 토큰으로 교환합니다.

/mcp를 입력하면 서버별 접속 상태(Connected / Needs auth / Error)가 목록으로 나타납니다. Needs auth 상태라면 다시 인가가 필요하다는 신호입니다.

1. 포트 충돌 (Port Conflict)

redirect_uri가 고정 포트를 사용하는 구현일 경우, 다른 로컬 서버(Vite 개발 서버 등)가 동일한 포트를 점유하고 있으면 콜백이 도달하지 못해 타임아웃(Timeout)이 발생합니다.

Error: OAuth callback timeout - no response received on http://localhost:PORT/callback

→ 인증 전에 lsof -i :PORT로 빈 포트인지 확인합니다. 또한 여러 개의 Claude Code 세션을 동시에 인증 플로우로 진입시키지 마세요 (세션마다 임시 서버를 띄우기 때문에 드물게 충돌할 수 있습니다).

2. 토큰 만료 (Token Expiration)

한동안 사용하지 않은 머신이나 세션의 경우, 저장된 액세스 토큰(Access Token)뿐만 아니라 리프레시 토큰(Refresh Token)의 기한도 만료되었을 수 있습니다. 이 경우 에러가 OAuth 관련임을 한눈에 알 수 없어, 도구 호출 자체가 실패한 것처럼 보일 수 있습니다.

Error calling tool 'search_docs': 401 Unauthorized

→ 도구 호출이 원인 불명으로 401 에러가 난다면, 먼저 /mcp로 해당 서버의 상태를 확인합니다. Needs auth라면 재인가를 진행하고, Connected 상태인데도 401이 발생한다면 서버 측의 스코프(Scope) 변경을 의심해야 합니다.

3. 브라우저 실행 불가 환경

원격 서버에 SSH로 접속하여 그 안에서 Claude Code를 실행하고 있는 경우, 브라우저를 자동으로 실행할 수 없어 인가 플로우가 멈춥니다. 인가 URL을 로컬 PC의 브라우저에 복사하여 붙여넣어 열더라도, 리다이렉트 대상인 localhost가 SSH를 통한 환경과 일치하지 않아 실패합니다.

→ ssh -L PORT:localhost:PORT를 사용하여 콜백 포트를 로컬로 포워딩(Forwarding)한 후 인가 URL을 엽니다. 어떤 포트가 사용될지는 사전에 알 수 없으므로, 표시된 인가 URL 내의 redirect_uri 파라미터를 보고 포워딩할 포트를 결정하는 것이 요령입니다.

MCP의 인증 관련 사항은 사양 추가에 따라, OAuth 2.1 (PKCE 필수)이 원격 서버의 표준이 되었다. stdio 연결에서는 환경 변수로 API 키를 전달하는 것만으로 충분했지만, HTTP/SSE를 경유하여 원격으로 연결하는 경우에는 브라우저를 통한 인가(Authorization)가 전제되는 만큼, 위와 같은 "로컬 실행 환경 특유"의 난관이 늘어난다.

• 원격 MCP 서버는 .mcp.json에 type: http로 등록하는 것만으로 작동하기 시작하지만, OAuth 인증 관련해서는 환경 의존적인 난관이 많다. - 포트 충돌(Port conflict)·토큰 만료(Token expiration)·브라우저 실행 불가(Browser launch failure)의 3가지 패턴은 /mcp 명령어를 통한 상태 확인부터 해결해 나가는 것이 빠르다. - SSH를 통한 접속 등 특수한 실행 환경에서는 콜백 포트(Callback port)의 포트 포워딩(Port forwarding)을 잊지 말 것. - 동작은 Claude Code의 버전에 따라 달라질 수 있으므로, 문제가 발생하면 claude --version을 확인하는 습관을 들여두면 안심할 수 있다.