AI 아키텍처 기술 블로그

원격 MCP 서버를 여러 클라이언트에 붙이기: URL 중심 OAuth 디스커버리와 등록 패턴

내부 기능을 원격 MCP 서버 (Remote MCP Server, Streamable HTTP) 로 노출하면, 하나의 서버를 여러 AI 클라이언트가 자연어로 함께 쓸 수 있습니다. Codex, Claude Code, claude.ai, Claude Desktop, ChatGPT — 클라이언트는 제각각이지만 서버는 하나입니다(같은 제품이라도 웹·데스크톱 표면이 커넥터를 공유하기도 합니다). 그런데 막상 붙이려고 하면 "클라이언트마다 등록 방법이 다른데?"라는 벽에 부딪힙니다.좋은 소식은, 클라이언트와 서버가 호환되는 MCP Authorization 사양과 클라이언트 등록 방식을 지원하면, 등록은 대체로 URL 중심으로 수렴한다는 점입니다. 클라이언트가 서버에 처음 접속하면 메타데이터 디스커버리 (Disco..

AI 코딩 에이전트를 팀 표준에 가두기: 재사용 하네스 플러그인과 3겹 강제 훅

팀이 AI 코딩 에이전트 (AI Coding Agent, 예: Claude Code)를 도입하면 생산성은 분명히 오릅니다. 그런데 사람이 여럿, 프로젝트가 여럿, 세션이 수백 개가 되면 새로운 문제가 생깁니다. 에이전트마다 하는 방식이 제각각입니다. 어떤 세션은 커밋 메시지 컨벤션을 지키고 어떤 세션은 안 지킵니다. 어떤 세션은 리뷰를 꼼꼼히 하고 어떤 세션은 건너뜁니다. 그리고 아주 가끔, 시크릿을 커밋하거나 보호된 브랜치에 직접 push하는 사고가 납니다.이 글은 그 문제를 "에이전트를 더 똑똑하게 만드는 것"이 아니라 "팀의 표준을 에이전트가 벗어나지 못하게 강제하는 것" 으로 푸는 접근을 정리합니다. 핵심 발상은 팀의 엔지니어링 표준을 재사용 가능한 하네스 (Harness) 플러그인으로 패키징해,..

Java Server SDK, Android Kotlin SDK, iOS Swift SDK와 React JavaScript SDK가 모두 준비되면 다음 문제는 배포입니다.소스 코드가 정상적으로 Build됐다는 사실만으로 고객이 안전하게 업그레이드할 수 있는 것은 아닙니다. 같은 기능이 네 Package에 모두 들어갔는지, 기존 고객의 Binary가 깨지지 않는지, 실제 Registry에서 받은 Artifact가 검증한 파일과 같은지, 어떤 서비스 API와 호환되는지를 함께 증명해야 합니다.릴리스 자동화의 목적은 네 Package를 무조건 같은 Version으로 만드는 것이 아닙니다. 각 생태계에 맞는 Package Version을 유지하면서도 공통 계약, 호환성 범위와 검증 증거를 하나의 Release ..

같은 서비스를 Java Server SDK, Android Kotlin SDK, iOS Swift SDK와 React JavaScript SDK로 제공하면 네 개의 구현이 생깁니다. 그러나 고객에게 전달해야 할 업무 의미까지 네 개가 되어서는 안 됩니다.예를 들어 서버는 상태 코드를 정상적으로 반환했는데 Android에서는 재시도하고 iOS에서는 즉시 실패한다면, 또는 Web SDK만 큰 숫자 ID를 다른 값으로 읽는다면 각 SDK의 코드는 동작해도 제품 계약은 깨진 것입니다.공통 계약의 목적은 모든 언어에서 똑같은 Class와 Method 이름을 강제하는 것이 아닙니다. Java에는 Java다운 API를, Kotlin에는 Coroutine과 Flow를, Swift에는 async/await과 AsyncS..

앞선 글에서는 고객사가 Android·iOS 앱을 직접 설계하면서도 공통 업무 기능과 프라이빗 API 경계를 유지하는 Kotlin·Swift SDK를 살펴봤습니다. 이번 글은 같은 목적을 React 웹으로 확장합니다.웹 SDK의 목적은 완성된 화면이나 전역 상태 관리 방식을 고객사에 강제하는 것이 아닙니다. Router, 상태 관리 도구, 디자인 시스템, Form과 오류 문구는 고객사가 선택합니다. SDK는 고객사 공개 API를 호출하는 업무 기능을 JavaScript다운 계약으로 제공하고, React Adapter는 그 계약을 Hook과 외부 Store 구독으로 연결합니다.브라우저는 프라이빗 API Endpoint나 서버용 Secret을 갖지 않습니다. JavaScript SDK가 연결하는 대상은 고객..

앞선 글에서는 고객사가 Android·iOS 앱과 React 웹을 직접 설계하면서도 프라이빗 API를 노출하지 않는 멀티플랫폼 SDK 구조를 살펴봤습니다. Android 편에 이어 이번 글은 iOS Swift SDK의 공개 API와 실행 계약을 구체화합니다.iOS SDK의 목적은 완성된 화면을 고객에게 강제하는 것이 아닙니다. SwiftUI와 UIKit 선택, 화면 구성, 내비게이션, 디자인 시스템과 로그인 경험은 고객사 앱이 결정합니다. SDK는 고객사 서버와 통신하는 업무 기능을 Swift다운 계약으로 제공합니다.모바일 앱은 프라이빗 API Endpoint나 서버용 자격 증명을 갖지 않습니다. Swift SDK가 연결하는 대상은 고객사가 모바일 앱에 공개한 API입니다. 프라이빗 망 연결은 고객사 서..

앞선 글에서는 고객사가 Android·iOS 앱과 React 웹을 직접 설계하면서도 프라이빗 API를 노출하지 않는 멀티플랫폼 SDK 구조를 살펴봤습니다. 이번 글은 그중 Android Kotlin SDK의 공개 API와 실행 계약을 구체화합니다.Android SDK의 목적은 완성된 화면을 고객에게 강제하는 것이 아닙니다. 로그인 화면, 내비게이션, 디자인 시스템과 업무 흐름은 고객사 앱이 결정하고, SDK는 고객사 서버와 안전하게 통신하는 기능을 Kotlin다운 계약으로 제공합니다.모바일 앱은 프라이빗 API Endpoint나 서버 자격 증명을 갖지 않습니다. Kotlin SDK가 연결하는 대상은 고객사에 공개된 모바일용 API이며, 서버 간 프라이빗 연결은 고객사 서버와 Java Server SDK의..

앞선 글에서는 고객사가 Android·iOS 앱과 React 웹을 원하는 형태로 구현하면서도, 프라이빗 망의 API 서버를 직접 노출하지 않는 멀티플랫폼 SDK 구조를 살펴봤습니다.이 구조에서 Java Server SDK는 단순한 HTTP 호출 편의 라이브러리가 아닙니다. 고객사 서버가 프라이빗 API를 사용할 때 필요한 인증, 테넌트 문맥, 오류 변환, 재시도, 멱등성, 타임아웃과 관측 정책을 한곳에서 적용하는 신뢰 경계의 실행 구성요소입니다.구체적인 네트워크 기술은 배포 환경마다 달라질 수 있습니다. 중요한 원칙은 모바일 앱과 브라우저가 프라이빗 Endpoint나 서버 자격 증명을 직접 갖지 않고, 고객사 서버 안의 Java SDK가 통제된 경로를 통해 호출한다는 점입니다.이 글은 이 역할을 수행하는..

이미 운영 중인 API 서버와 웹 프런트 페이지, 모바일 앱이 있다고 가정해 보겠습니다. 표준 화면만 제공할 때는 이 세 구성요소만으로도 충분하지만, 고객사마다 업무 흐름·브랜드·화면 구성이 달라지면 하나의 UI를 그대로 제공하는 방식에는 한계가 생깁니다.이 문제를 해결하기 위해 고객사가 자신의 요구에 맞는 채널을 구현할 수 있도록 다음 SDK를 제공할 수 있습니다.Android 애플리케이션을 위한 Kotlin Mobile SDKiOS 애플리케이션을 위한 Swift Mobile SDK고객 맞춤형 웹을 위한 React·JavaScript Front SDK고객사 서버 환경을 위한 Java Server SDK와 Spring Boot Starter여기에는 중요한 네트워크 제약이 하나 더 있습니다. 핵심 API ..

앞선 두 글에서는 프라이빗 API를 호출하는 Java Server SDK의 모듈·전송 계층과, 이를 고객사 Spring Boot 애플리케이션에 연결하는 Starter를 설계했습니다.그러나 Client Bean이 정상 생성됐다는 사실만으로 운영 안정성이 보장되지는 않습니다. 프라이빗 망에서도 DNS 지연, TLS Handshake 실패, Gateway 과부하, Token 만료, 부분 응답, 연결 종료와 배포 중 순간 장애가 발생합니다. 이때 무제한 Timeout과 무분별한 재시도는 작은 장애를 전체 시스템의 자원 고갈로 확대할 수 있습니다.운영 가능한 Server SDK의 목표는 “모든 실패를 성공으로 바꾸는 것”이 아닙니다. 복구 가능한 실패만 제한된 예산 안에서 흡수하고, 복구할 수 없는 실패는 빠르고..