Sanity Context와 MCP를 활용한 Basegent 및 Bucket Space의 AI 고객 지원 강화

이 글은 Sanity Challenge, Path One: 실제 콘텐츠를 질의하는 에이전트 배포하기에 대한 제출물입니다.

제가 구축한 것

지난 몇 달 동안 저는 현대적인 AI 고객 지원 및 운영 플랫폼인 **Basegent**을 구축해 왔습니다. Basegent는 개발자와 SaaS 팀에게 실제 고객 문제를 해결하고, 공식 문서를 인용하며, 신뢰도가 낮아지면 인간 상담원에게 원활하게 에스컬레이션할 수 있는 지능형 채팅 비서 기능을 제공합니다.

동시에 저는 스마트 북마킹, 콘텐츠 캡처 및 개인 라이브러리 구성을 위해 구축된 현대적인 웹 애플리케이션인 **Bucket Space**를 운영하고 있습니다.

당연히 저는 Bucket이 Basegent의 시험장이 되기를 바랐습니다. 하지만 프로덕션 환경에 AI 지원 봇을 배포해 본 사람이라면 아는 것처럼, 전통적인 검색 증강 생성(Retrieval-Augmented Generation, RAG)에는 치명적인 비밀이 있습니다:

전통적인 벡터 검색은 회사 문서를 단순한 텍스트 청크의 꾸러미처럼 취급합니다. 정책을 임의의 단락으로 잘라내고, 유사성 임베딩을 계산하며, LLM이 즉석에서 모순을 해결할 수 있기를 바랄 뿐입니다.

실제 고객 지원 환경에서 이 순진한 접근 방식은 치명적으로 실패합니다:

시간적 및 법적 선례: 만약 귀사가 2026년에 환불 정책을 14일에서 30일로 업데이트했다면, 두 단락 모두 벡터 데이터베이스에게는 의미론적으로 동일해 보입니다. 봇은 필연적으로 고객의 분노에 찬 질문에 구식 정책을 인용하게 될 것입니다.
다차원 권한: 지원 규칙은 고객 속성—플랜 등급(Free 대 Pro), 지리적 시장(US 대 EU), 또는 배포 유형(standard 대 custom)—에 따라 달라집니다. 유사성 검색에는 조건부 논리에 대한 개념이 없습니다.
일반 제품명에 대한 환각: 사용자가 _

Sanity가 Sanity Labs에서 Sanity Context MCP 및 Knowledge Base 베타를 발표했을 때, 저는 즉시 이해했습니다. Sanity는 단순히 또 다른 벡터 데이터베이스를 제공하는 것이 아니었습니다. 내장된 충돌 해결 기능과 개방형 프로토콜(Model Context Protocol - MCP)을 갖춘 관리되고 구조화되며 검증 가능한 진실의 원천(source of truth)으로서 컨텍스트 자체를 다루고 있었습니다.

저는 전체 루프를 연결하는 작업을 시작했습니다:

Basegent에 Sanity 통합: Basegent에 직접 SanityContextSourceAdapter라는 퍼스트파티 어댑터를 구축하여, Sanity의 호스팅된 MCP 엔드포인트와 다중 공급자 Bring-Your-Own-Key (BYOK) 추론 엔진을 연결했습니다.
Sanity Knowledge Base 및 Context MCP 설정: Bucket을 위한 전용 Sanity 조직 프로젝트를 구축하고, 구조화된 지원 정책을 모델링했으며, Sanity의 이슈 감지 시스템을 사용하여 실제 정책 충돌을 포착하고 영구적인 표준 지침으로 해결하는 데 사용했습니다.
Bucket Space에 프로덕션 배포: @basegent/react 채팅 위젯을 mybucket.space에 임베드하고, 인증된 사용자 토큰을 전달하여 에이전트가 검증된 사용자 신원을 실시간 Sanity 지식 기반 항목과 교차 참조할 수 있도록 했습니다.

작동 방식, Sanity Context가 우리의 가장 어려운 정책 딜레마를 어떻게 해결했는지, 그리고 여러분의 스택에 이 패턴을 어떻게 구현할 수 있는지에 대한 이야기입니다.

데모 및 라이브 배포

라이브 프로덕션 배포

Production Web Application (Bucket Space): https://mybucket.space 하단 바 또는 플로팅 액션 버튼에 도킹된 라이브 Basegent 어시스턴트를 테스트할 수 있습니다.
AI 고객 운영 플랫폼 (Basegent): https://basegent.space 다중 공급자 BYOK(Bring Your Own Key) 작업 공간 및 지식 소스를 탐색해 보세요.
Public Sanity Policy Query API: 실시간 Sanity 문서 검사하기 데이터셋 production의 라이브 구조화된 정책 문서를 검증하는 직접적인 공개 GROQ 엔드포인트입니다.
Published NPM Packages: @basegent/react 및 @basegent/client

한눈에 보는 아키텍처

Basegent는 주기적인 데이터 덤프를 복사하거나 중복된 콘텐츠를 저장하는 대신, MCP JSON-RPC를 통해 채팅 대화 중에 Sanity Context에서 라이브로 데이터를 조회합니다:

[ Bucket Space의 고객 (mybucket.space) ]
                     │
      인증된 쿼리 + 서명 토큰
...

프로세스 분석: 3가지 핵심 기둥

기둥 1: Sanity에서 콘텐츠, 지식 기반 및 Context MCP 모델링

Bucket의 지원 기능을 구현하기 위해, 저는 조직 Miracle Onyenma (oL4FZOkGh) 아래에 프로젝트 ID jk662cms와 데이터셋 production을 가진 전용 Sanity Labs 프로젝트를 생성했습니다.

Creating the Bucket project in Sanity Labs

1. 구조화된 지원 정책 설계

지원 정책은 단순한 텍스트 덩어리로 구성되어서는 안 됩니다. Sanity Studio에서, 우리는 명시적인 스키마 제약 조건을 가진 supportPolicy 문서를 모델링했습니다:

// schemas/supportPolicy.ts
import { defineType, defineField } from

-   **Canonical Pro US 정책:** 미국 내 Pro 사용자 대상 30일 환불 기간 (`priority: 100`, `authority: canonical`, 2026년 발효). 
-   **레거시 글로벌 정책:** 일반 구매 건에 대한 14일 환불 기간 (`priority: 10`, `authority: legacy`, 2025년 말 만료). 
-   **맞춤형 엔터프라이즈 예외:** 맞춤 제작된 엔터프라이즈 구성품에 대한 7일 환불 기간 (`priority: 90`).
-   **처리 기간:** 승인 후 5~7 영업일 내 이행 완료.
-   **제품 기능 가이드:** 공식 Apple iOS 공유 시트(Share Sheet) 단축키와 정확한 iCloud 설치 링크를 포함한 실제 단계별 설정 가이드.

#### 2. 지식 기반 컴파일 및 실제 충돌 감지하기

다음으로, Sanity Context Lab에서 **Basegent 지원 정책** 지식 기반(`kb3NuTkXw21o`)을 구축했습니다.

이곳에서 Sanity Context가 빛을 발합니다. 충돌하는 진술들을 단순히 평균 내는 대신, Sanity는 문서를 능동적으로 구문 분석(parsed)하고 도메인 경계를 분석하며 **Issues Review** 대시보드에서 중요한 모호성을 플래그 지정했습니다.

##### 충돌 1: 전체 지식 기반의 모순

Sanity는 맞춤형 배포 예외(7일)와 레거시 글로벌 규칙(14일) 간에 맞춤 제품과 관련하여 직접적인 충돌을 감지했습니다:

[![Sanity Context detecting conflicts across the whole knowledge base](https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/.%2Fimages%2Fsanity-context-basegent-support-policies-issues-review-whole-knowledgebase.png)](https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/.%2Fimages%2Fsanity-context-basegent-support-policies-issues-review-whole-knowledgebase.png)

##### 충돌 2: 환불 자격 기간 중첩

Sanity는 새로운 정책이 레거시 정책을 대체한다고 주장하지만, 그 적용 범위가 US Pro 티어에 엄격하게 한정되어 있어 무료 및 비(非) 미국 티어의 경우 잠재적으로 모호할 수 있음을 강조했습니다:

[![Reviewing the conflicting refund eligibility terms](https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/.%2Fimages%2Fsanity-context-basegent-support-policies-issues-review-refund-eligibility-windows-by-plan-market-and-date.png)](https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/.%2Fimages%2Fsanity-context-basegent-support-policies-issues-review-refund-eligibility-windows-by-plan-market-and-date.png)

##### 해결책: 영구적인 표준 지침(Durable Standing Instructions)

Sanity 인터페이스에서 원클릭으로 소스 기반의 정규 클레임(source-backed canonical claim)을 선택하여 문제를 해결했습니다. Sanity는 이 결정을 **영구적인 표준 지침(durable standing instruction)**으로 컴파일하여 향후 데이터셋 재구축에도 자동으로 유지되도록 했습니다!

[![Resolved conflict state with standing instruction applied](https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/.%2Fimages%2Fresolved-sanity-context-basegent-support-policies-issues-review-refund-eligibility-windows-by-plan-market-and-date.png)](https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/.%2Fimages%2Fresolved-sanity-context-basegent-support-policies-issues-review-refund-eligibility-windows-by-plan-market-and-date.png)

검증을 완료한 후, 조직 수준의 Context Viewer 토큰을 생성하고 Sanity가 호스팅하는 Context MCP 엔드포인트(`https://api.sanity.io/v1/context/organizations/oL4FZOkGh/mcp/context`)를 이 지식 기반(Knowledge Base)으로 지정했습니다.

### Pillar 2: Basegent에서 Sanity를 퍼스트파티 소스로 통합하기

Basegent에서는 모든 고객 지원 환경이 **Workspace**라고 불리는 격리된 테넌트 내에 존재합니다. 우리는 `basegent.space/Account`에 전용 **Bucket** 워크스페이스(`slug: bucket`)를 생성했습니다:

[![Creating the Bucket workspace in Basegent](https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/.%2Fimages%2Fbasegent-create-new-workspace-bucket.png)](https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/.%2Fimages%2Fbasegent-create-new-workspace-bucket.png)

#### 1. 소스 연결하기

Basegent의 Sources 대시보드(`/sources/new`)에서 **Sanity Context**를 퍼스트파티 지식 소스로 추가하고 다음 정보를 제공했습니다:

-   Sanity Context MCP URL
-   지식 기반 ID (`kb3NuTkXw21o`)
-   안전한 Sanity 조직 토큰 (저장 시 암호화되며, 클라이언트에게 절대 유출되지 않음)

#### 2. Sanity Context 소스 어댑터 구현하기

Basegent의 핵심 런타임은 제공자 중립적인 `ContentSourceAdapter`를 정의합니다. Sanity에 실시간으로 질의하려면 `SanityContextSourceAdapter`를 구현했습니다:

##### Step A: 동적 개요 검색 (`/initial-context`)

Basegent가 검색 레지스트리(retrieval registry)를 컴파일할 때, 가상 개요를 얻기 위해 Sanity Context에 요청합니다:

// lib/sources/sanity-context-adapter.ts
export interface SanityContextConfig {
mcpUrl: string;
...


##### Step B: MCP JSON-RPC를 통한 실시간 도구 호출

고객이 질문을 하면 Basegent는 관련 가상 경로를 선택하고 HTTP를 통해 `knowledge_base_read` 도구를 실시간으로 실행합니다:

export async function callKnowledgeBaseRead(
config: SanityContextConfig,
path: string,
...


#### 3. 다중 공급자 BYOI / BYOK 아키텍처

고객 지원 상담원은 다운타임이나 지역별 API 속도 제한을 감당할 수 없습니다. Basegent는 팀이 여러 공급자의 API 키를 연결하고 자동 폴백(fallback) 기능을 사용할 수 있도록 하는 **Bring Your Own Intelligence (BYOI / BYOK)** 엔진을 갖추고 있습니다:

// lib/ai/provider-resolver.ts
export const SUPPORTED_PROVIDERS = ["groq", "openai", "anthropic", "google"] as const;

...


**Groq**에서 번개처럼 빠른 추론을 실행하든, **Claude 3.5 Sonnet**에서 깊은 추론을 하든, 또는 **Gemini 2.0 Flash**에서 비용 효율적인 답변을 얻든, 근본적인 지식은 Sanity Context에 고정되어 있습니다.

### Pillar 3: Bucket Space(`mybucket.space`)에 배포하기

Sanity와 Basegent를 연결한 후, 마지막 단계는 지원 어시스턴트를 [mybucket.space](https://mybucket.space)에 통합하는 것이었습니다.

#### 1. 공식 NPM 패키지 설치

Basegent는 미리 빌드된 React 컴포넌트와 TypeScript 클라이언트를 npm에 직접 게시합니다:

npm install @basegent/react @basegent/client


#### 2. 고객 컨텍스트 인증

로그인한 사용자가 채팅을 열면, Bucket은 내부 API 경로를 통해 HMAC 서명된 고객 토큰을 발행합니다. 이를 통해 개인 고객 데이터를 노출하지 않으면서 사용자 플랜 티어, 시장 및 등록 타임스탬프에 대한 정보를 Basegent에 전달합니다:

// components/shared/BasegentWidget.tsx
"use client";

...


#### 3. 반응형 UI 통합

모바일 화면에서 일반적인 플로팅 채팅 버블은 중요한 하단 탐색 동작을 자주 가립니다. 우리는 사용자 경험(UI polish)을 iPhone, Android 및 데스크톱 뷰포트 전반에 걸쳐 유지하기 위해, Bucket의 `MobileBar.tsx`에 맞춤형 지원 트리거를 통합하여 사용자가 푸터 크레딧으로 스크롤할 때 동적으로 이 트리거를 숨기도록 했습니다.

## 실제 시나리오 적용 사례

### 시나리오 1: 다단계 정책 조정 및 충돌 해결