옥타퓨즈 게이트웨이 2.18.0, MCP OAuth 접속 지원

OctaFuse Gateway 2.18.0은 MCP 클라이언트 접속과 공급자 고정(스티키) 바인딩 관리 방식을 중점적으로 개선했다.

연동이 완료된 OAuth 인증 서버와 함께라면 사용자는 OAuth를 지원하는 MCP 클라이언트에서 로그인하고 인증할 수 있으며, API Key를 수동으로 입력할 필요가 없다. 관리자는 사용자 또는 애플리케이션별로 인증을 조회·취소할 수 있고, 요청 로그에서 호출 출처를 추적할 수 있다.

라우팅 백엔드에서는 이제 공급자별 바인딩 분포와 사용자 상세 내역을 바로 확인할 수 있으며, 바인딩 유효 기간 조정, 건별 해제 또는 일괄 삭제를 지원한다. 스트리밍 요청의 타임아웃 판단도 개선되어, 업스트림이 계속 하트비트만 보내면서 실제 내용이 없을 때 오래 대기하는 상황을 피한다.

01｜MCP 접속: 로그인 인증, 애플리케이션별 접근 관리

MCP 서비스를 외부 Agent에 접속할 때 이제 OAuth를 통해 로그인 인증을 완료할 수 있다. 사용자가 클라이언트에서 연결을 시작하면 비즈니스 계정 시스템으로 이동해 로그인하고 인증에 동의하며, 이후 클라이언트는 별도의 액세스 토큰으로 MCP 서비스를 호출한다.

이 토큰은 사용자의 API Key와 분리해 관리된다. MCP 접근만 허용되며 채팅, 모델 목록 등 다른 인터페이스에는 사용할 수 없다. 호출 비용은 토큰이 속한 게이트웨이 사용자에게 청구된다. 관리자는 'OAuth 액세스 토큰'에서 애플리케이션 또는 사용자별로 인증을 조회·취소할 수 있고, 사용자 상세 페이지에서도 해당 기록을 확인할 수 있다. 요청 로그에는 호출이 어느 OAuth 애플리케이션에서 왔는지 표시되어 사용량 추적과 문제 진단이 용이하다.

활성화 방법

경로는 MCP 서비스 → 클라이언트 접속 및 인증 이다. 'OAuth 2.0 인증 로그인(선택)'을 켜고 인증 서버 주소를 입력한 뒤 저장한다. 주소는 HTTPS를 사용해야 하며, 로컬 개발 시에는 HTTP localhost가 허용된다. 같은 페이지의 '접속 가이드'는 API Key와 OAuth 두 가지 방식, 그리고 ChatGPT 커넥터, Cursor, VS Code, Claude Code, Codex의 접속 절차를 제공한다.

활성화 전에 게이트웨이와 연동이 완료된 OAuth 인증 서버를 준비해야 한다. OctaFuse Gateway는 MCP 서비스 접근과 토큰 검증을 담당하며, 로그인 및 인증 서버를 제공하지 않는다. 비즈니스 계정 시스템은 게이트웨이의 Admin API를 통해 액세스 토큰을 발급·교체해야 하며, 로그인 페이지 주소만 입력해서는 안 된다. 연동 경계는 MCP OAuth 아키텍처 설명을 참고한다.

MCP 서비스 페이지에서 인증 서버를 구성하고 클라이언트에 OAuth 접속 안내를 제공한다.

액세스 토큰은 기본 1시간 동안 유효하다. 만료 후 클라이언트는 인증 서버를 통해 토큰을 갱신할 수 있으며, 재로그인 필요 여부는 클라이언트와 인증 서버의 처리에 달려 있다. 위 설정을 끄면 OAuth 인증 검색이 꺼진다. 이미 발급된 토큰을 무효화하려면 'OAuth 액세스 토큰'에서 취소해야 한다.

02｜공급자 고정 바인딩: 분포를 확인하고 직접 조정

공급자 고정은 동일 사용자가 동일 모델, 라우팅 그룹, 프로토콜에서 마지막으로 성공한 공급자를 우선 재사용하게 하여 캐시 연속성을 유지하는 데 도움을 준다. 이번 버전은 바인딩의 시각적 관리를 추가했다. 라우팅 페이지에서 'Provider 고정'을 열면 분포를 확인하고 사용자를 찾아 바인딩을 처리할 수 있다.

바인딩 유효 기간 조정

'구성'에서 고정을 활성화하고 1시간(기본), 2시간, 6시간 또는 사용자 지정 유효 기간을 선택한다. 설정은 라우팅 풀 단위로 적용되며 해당 풀에 연결된 모든 진입점을 포괄한다.

라우팅 풀별로 고정 스위치와 바인딩 유효 기간을 구성한다.

공급자 분포 확인

'분포'는 우선순위별로 각 공급자의 가중치, 유효 바인딩 수, 전체 풀 대비 비중을 보여 주어 사용자가 현재 어떤 공급자에 배정되어 있는지 확인하기 쉽게 한다. 바인딩 수를 클릭하면 해당 공급자의 바인딩 상세 내역으로 바로 이동한다.

각 공급자의 바인딩 수와 비중을 확인하고 해당 상세 내역으로 이동한다. 바인딩 수는 바인딩 기록 수를 의미하며 요청량이나 독립 사용자 수와 같지 않다.

사용자 찾기 및 해제

'상세'는 사용자, 공급자, 남은 유효 시간을 보여 주며, 공급자별 필터링과 이메일 또는 사용자 ID 기반 정확 검색을 지원한다. 특정 사용자가 다시 경로를 선택하게 하려면 해당 기록을 바로 해제할 수 있고, 전체를 재분배하려면 '기타'에서 이 라우팅 풀의 유효 바인딩을 일괄 삭제할 수 있다.

바인딩 상세 내역에서 사용자를 찾아 남은 유효 시간을 확인하고 수동으로 해제한다.

해제 후 사용자의 다음 요청은 기존 라우팅 정책에 따라 공급자를 다시 선택하며, 여전히 원래 공급자가 선택될 수 있다. 일괄 삭제도 고정 스위치나 유효 기간 설정을 변경하지 않는다.

03｜스트리밍 요청: 하트비트가 더 이상 콘텐츠 대기를 연장하지 않음

일부 업스트림은 SSE 주석 하트비트를 계속 보내면서 실제 내용은 오랫동안 보내지 않는다. 이제 첫 패킷, 유휴, 첫 이벤트 타임아웃은 내용이 있는 SSE 이벤트만 인정하며, 주석 하트비트와 빈 줄은 대기 시간을 더 이상 연장하지 않는다.

기본적으로 첫 유효 이벤트를 60초 넘게 기다리고 있으면서 아직 회로가 차단되지 않은 후보 업스트림이 남아 있으면 게이트웨이는 다음 후보를 시도한다. 마지막 사용 가능 후보는 첫 패킷 타임아웃이 최종적으로 처리하며 더 긴 대기 기회를 남겨 둔다. 응답 헤더 대기에도 별도의 타임아웃 처리가 있어 요청이 응답 없는 업스트림에 계속 머무르는 것을 피한다.

장애 전환 로그에는 후보 업스트림, 실패 원인, 회로 차단 상태 등의 정보도 함께 보강되어 요청이 어느 단계에서 실패했는지, 다른 업스트림을 계속 시도했는지 판단하기 쉽다.

04｜요청 상세 시각화

요청 로그 상세는 '요청 인바운드 → 라우팅 및 변환 → 업스트림 시도 → 응답 결과 → 사용량 및 정산' 흐름으로 표시하도록 변경되었으며, 타임라인으로 각 업스트림 시도와 장애 전환을 보여 준다. 단계 또는 특정 시도를 클릭하면 요청 파라미터 변화, 업스트림 상태, 실패 원인, 정산 정보를 확인할 수 있어 문제 해결 시 위치를 파악하기가 더 쉽다.

개편 전 에는 요청 정보, 소요 시간, 원본 데이터가 평면적으로 표시되어 장애 전환을 추적하려면 JSON에서 각 시도를 찾아야 했다.

개편 전: 데이터가 여러 패널에 분산되어 요청이 어떤 단계를 거쳤는지 직관적이지 않았다.

개편 후 에는 요청 흐름, 소요 시간 분포, 정산 요약이 한곳에 표시된다. 장애 전환이 발생하면 어느 시도가 실패했고 언제 전환되었으며 이후 업스트림의 처리 결과는 어떠했는지 바로 확인할 수 있고, 필요에 따라 해당 단계의 상세를 펼쳐 볼 수 있다.

개편 후: 요청 인바운드부터 사용량 및 정산까지 한눈에 볼 수 있다. 타임라인은 첫 시도가 429를 반환한 뒤 게이트웨이가 다른 업스트림으로 전환해 성공한 과정을 보여 준다. 이미지를 클릭하면 원본을 볼 수 있다.

05｜기타 업데이트

- Gemini 서명 호환 : Gemini 네이티브 진입점에서 과거 사고 서명이 유효하지 않은 특정 400 오류를 만나면 처리 가능한 서명을 정리하고 동일 업스트림에 한 번 재시도한다.

- MCP 호출 검증 : JSON-RPC 배치 배열 요청을 거부하여 호출당 제한을 우회하지 못하게 한다. 업스트림이 빈 응답을 반환하거나 MCP 구조에 맞지 않는 도구 결과를 반환하면 실패로 처리하고 과금하지 않는다. 리소스 템플릿 목록 조회를 보강했으며 현재는 빈 목록을 반환한다.

- 라우팅 목록 레이아웃 : 사용 가능한 너비에 따라 구역을 조정하고 상태, 가중치, 고정, 파라미터를 분리해 표시하여 구성을 확인하기 쉽게 했다.

- 모델 및 공급자 카탈로그 : 다음 프리셋을 추가했다. 가져온 후에도 해당 공급자와 라우팅을 구성해야 한다.

신규 프리셋 안내

GPT-6.1 Terra에 gpt-6.1-terra 모델 프리셋을 추가했으며, 단문·장문 컨텍스트 및 캐시 과금 설정을 포함합니다. 위안화 가격은 달러 정가 ×7의 자리표시자 값이므로 사용 전 실제 가격을 확인하시기 바랍니다.

바이두 클라우드 모델 서비스

광저우, 싱가포르, 캘리포니아, 프랑크푸르트 네 개 지역 템플릿을 추가했으며, 바이두 첸판과는 별도입니다. 광저우는 대화를 지원하고, 나머지 세 지역은 추가로 이미지 및 Gemini 텍스트, 이미지 생성 기능을 포함합니다. 벡터, 오디오, 비디오는 포함하지 않습니다. 각 지역의 Key는 혼용할 수 없습니다.

업그레이드 안내

2.17.0에서 2.18.0으로 업그레이드하려면 먼저 데이터베이스 마이그레이션 0034와 0035를 실행한 후 서비스를 업데이트해야 합니다. 더 이전 버전에서 업그레이드하는 경우 번호 순서대로 아직 적용되지 않은 모든 마이그레이션을 실행해야 합니다.

- 데이터베이스를 백업합니다.

- v2.18.0의 migrate 이미지를 사용하여 대기 중인 마이그레이션을 적용합니다. 수동으로 실행할 경우 먼저 0034를 실행한 후 0035를 실행합니다.

- 동일 버전의 Proxy와 Admin을 롤링 업데이트합니다.

0034는 스티키 바인딩의 사용자 상세 내역을 지원하고, 0035는 독립적인 OAuth 액세스 토큰 및 요청 로그 연관을 지원합니다. 0034가 없으면 신버전 스티키 바인딩 쓰기가 실패하고, 0035가 없으면 신버전 요청 로그 쓰기가 실패합니다. D1, Postgres, MySQL 모두 해당 마이그레이션을 실행해야 하며, 구체적인 작업은 0034 마이그레이션 설명 및 0035 마이그레이션 설명을 참고하십시오.

전체 변경 사항은 GitHub Release v2.18.0 및 업데이트 기록에서 확인할 수 있습니다.

- OctaFuse 공식 웹사이트

- GitHub 저장소

OctaFuse가 여러분의 프로젝트에 도움이 된다면 GitHub에서 Star로 응원해 주시고, PR 제출도 환영합니다. 또한 프로젝트에 관심 있는 파트타임 또는 풀타임 파트너를 찾고 있습니다.

프로그래머DD

프리랜서 프로그래머 @위챗 공식계정: 프로그래머DD

498

글

1.4m

읽음

19k

팬