대부분의 "사이트에 AI 고객 지원 에이전트 추가" 제품들은 사용자가 웹 대시보드에서 오후 시간을 보내기를 가정합니다. 계정을 생성하고, 마법사(wizard)를 따라 클릭하고, 파일을 업로드하고, 코드 스니펫(snippet)을 복사하는 과정 말이죠. 만약 당신이 이미 코딩 에이전트(coding agent) 환경에서 작업하고 있다면, 더 짧은 경로가 있습니다. 바로 에이전트에게 그 일을 시키는 것입니다.

SyntheticBrew는 네이티브 MCP 서버를 제공합니다. 이는 Claude Code가 OAuth를 통해 이에 연결할 수 있으며, 에이전트, 문서를 기반으로 지식을 제공하는 지식 베이스(knowledge base), 그리고 웹사이트용 임베디드 위젯(embeddable widget)까지 _에이전트가 스스로 전체를 프로비저닝(provision)할 수 있음_을 의미합니다. 당신이 할 일은 코드 한 줄을 붙여넣고 브라우저 프롬프트 하나를 승인하는 것뿐입니다.

이 글은 실제 운영 환경에서 실행한 바로 그 흐름에 대한 가이드입니다. 아래 내용은 실제로 일어나는 모든 과정이며, 마지막에 언급할 다소 거친 부분(rough edges)들도 포함되어 있습니다.

얻게 되는 것

이 튜토리얼을 마치면 다음을 갖게 됩니다:

• 당신의 제품에 맞춤화된 지침을 가진, SyntheticBrew Cloud에 호스팅된 고객 지원 에이전트 (support agent).
• 당신의 문서(마크다운 또는 일반 텍스트)로 구축된 지식 베이스 (knowledge base). 이를 통해 에이전트는 환각(hallucination) 현상을 일으키는 대신 당신의 콘텐츠를 바탕으로 답변하며, 답이 없을 때는 "모릅니다"라고 말합니다.
• 채팅 범위의 키(chat-scoped key)로 지원되는, 웹사이트 HTML에 붙여넣을 수 있는 임베디드 <script> 위젯 (embeddable <script> widget).
• 재현 가능한 설정: 전체 배포가 단 하나의 프롬프트로부터 이루어졌으므로, 동일한 채팅 세션에서 다시 실행하거나, 수정하거나, 제거할 수 있습니다.

데모 사이트에서의 완성된 결과물: 임베디드된 위젯이 업로드된 문서의 정확한 수치로 답변합니다. 환각 없이 지식 베이스에서 직접 가져온 답변입니다.

SyntheticBrew 자체는 소스 공개 에이전트 엔진(BSL 1.1)입니다. 직접 호스팅(self-host)할 수도 있지만, 이 튜토리얼은 5분 만에 끝낼 수 있는 경로인 호스팅된 클라우드를 사용합니다.

사전 요구 사항 (Prerequisites)

• Claude Code가 터미널에 설치되어 있고 작동하는 상태여야 합니다.
• syntheticbrew.ai 계정 (무료) — OAuth 단계에서 브라우저 로그인 화면으로 이동하며, 계정이 없는 경우 바로 가입(Sign Up) 링크가 제공됩니다.
• Markdown 또는 텍text 형식의 문서 — FAQ, README, 가격 페이지 등. 그라운딩 (Grounding)이 작동하는 것을 확인하기에는 파일 하나만으로도 충분합니다.

복사할 API 키도, 설치할 SDK도, 직접 수정할 설정 파일도 필요 없습니다.

Step 0 — 한 줄 명령어로 시작하기

아무 디렉토리에서나 Claude Code를 열고 다음을 붙여넣으세요:

Claude Code 복사 및 실행

Fetch https://syntheticbrew.ai/agent-setup/prompt.md and follow the instructions.

해당 URL은 일반 Markdown 형식의 지침 파일을 제공합니다. 에이전트가 수행할 작업을 미리 읽어보고 싶다면 브라우저에서 먼저 열어볼 수 있습니다 (읽어보는 것을 권장합니다; 내용은 짧습니다). 이 지침은 코딩 에이전트에게 SyntheticBrew의 MCP 서버에 연결하도록 지시한 다음, 지원 에이전트를 구축하는 과정을 단계별로 안내합니다. 지침에는 특정 단계에서 반드시 필요한 경우에만 사용자의 개입을 요청하도록 명시되어 있으므로, 이제부터 여러분은 주로 지켜보기만 하면 됩니다.

Step 1 — 연결하기 (OAuth, 브라우저 클릭 한 번으로 완료)

Claude Code가 가장 먼저 수행하는 작업은 MCP 서버를 등록하는 것입니다:

터미널 복사 및 실행

claude mcp add --transport http syntheticbrew https://app.syntheticbrew.ai/api/v1/mcp/rpc

그 다음 Claude Code 내부에서 /mcp를 실행하고 syntheticbrew를 선택하라는 요청을 받게 됩니다. 브라우저 창이 열리면 SyntheticBrew 계정에 로그인하고 액세스 권한을 승인하세요. 이것이 인증 절차의 전부입니다 — 키 생성이나 토큰 붙여넣기가 필요 없습니다.

동의 화면: 에이전트가 무엇을 요청하는지 정확히 확인할 수 있으며, 사용자가 직접 선택하지 않는 한 파괴적인 작업 (Destructive operations)은 비활성 상태로 유지됩니다.

내부적으로 이는 표준 OAuth 2.1 흐름(flow)입니다. Claude Code는 스스로를 클라이언트(client)로 동적으로 등록하고, PKCE 인증을 실행하며, provision manage 범위(scope)로 제한된 토큰과 리프레시 토큰(refresh token)을 수신합니다. 이를 통해 연결은 첫 세션 이후에도 유지됩니다. 이것이 왜 중요한지에 대해서는 "내부 동작(under the hood)" 섹션에서 더 자세히 다룹니다.

연결되면 Claude Code는 SyntheticBrew 도구 세트인 39개의 MCP 도구를 볼 수 있습니다. 이 도구들은 에이전트(agents), 지식 베이스(knowledge bases), 문서(documents), 모델(models), 그리고 임베딩 스니펫(embed snippet)을 다룹니다. 설정 프롬프트(setup prompt)에서는 이 중 7개만 필요합니다.

2단계 — 구축 과정 지켜보기

지침 파일(instruction file)은 당신에게 정확히 두 가지 질문을 던집니다: 당신의 제품은 무엇에 관한 것인가, 그리고 에이전트의 이름은 무엇으로 할 것인가 (기본값: support). 이 질문에 답하면 에이전트가 구축 과정을 진행합니다:

1. 에이전트 프로비저닝 (Provision the agent). provision_agent 호출을 통해 다음과 같은 기본 지침을 가진 에이전트를 생성합니다: 제품에 대한 고객의 질문에 답변할 것, 근거에 기반할 것(stay grounded), 그리고 답변을 지어내기보다 "모릅니다"라고 말하는 것을 선호할 것. 실제 실행(production run)에서는 새로운 에이전트의 ID를 반환하는 단 한 번의 호출로 이루어졌습니다.

2. 지침 정교화 (Refine the instructions). 당신이 제공한 제품 컨텍스트(context)를 사용하여, Claude Code는 admin_update_agent를 호출하여 일반적인 지원 템플릿이 아닌, 당신의 제품이 무엇인지 실제로 알고 있는 시스템 프롬프트(system prompt)를 작성합니다.

3. 문서로 근거 마련 (Ground it in your docs). 이 부분은 에이전트를 단순히 장식적인 존재가 아닌 유용한 존재로 만드는 핵심 단계입니다:

• admin_create_knowledge_base는 지식 베이스(knowledge base)를 생성합니다. 임베딩 모델(embedding model)은 자동으로 선택되므로 사용자가 직접 선택할 필요가 없습니다.
• admin_add_document는 마크다운(markdown)/텍스트 문서를 업로드합니다. Claude Code가 로컬 파일이나 가져오기를 원하는 페이지를 가리키도록 하면 됩니다. 인덱싱(Indexing)은 비동기(asynchronous)로 진행됩니다.
• admin_link_knowledge_base는 지식 베이스(KB)를 에이전트에 연결합니다. 연결 시 지식 활용 기능이 자동으로 활성화되며, 별도로 기억해야 할 토글(toggle)은 없습니다.
• 에이전트는 문서가 ready 상태로 보고될 때까지 admin_list_documents를 폴링(poll)합니다. 실제 실행에서는 작은 마크다운 문서가 첫 번째 폴링 시점에 인덱싱되었습니다. 약 5초 정도 소요되었습니다.

4. 위젯 전달하기. get_embed_snippet은 채팅 범위로 제한된 키(chat-scoped key)가 포함된, 바로 붙여넣을 수 있는 <script> 태그를 반환합니다. 이 키는 채팅 엔드포인트(endpoint)와만 통신할 수 있으며, 이는 공개된 HTML 환경에서 요구되는 보안 사항입니다.

5. 테스트 질문 제안하기. 프롬프트는 에이전트가 업로드된 문서에 답변이 포함된 질문을 제안하도록 지시하므로, 가장 먼저 확인하게 되는 것은 근거에 기반한(grounded) 답변입니다.

실제 프로덕션 E2E(end-to-end) 실행에서, 테스트 문서에는 업로드 제한 사양(upload-limit spec)이 포함되어 있었고, 테스트 질문은 이에 대해 물었습니다. 스트리밍된 답변은 문서에서 가져온 정확한 수치를 즉시 반환했습니다. 즉, 첫 시도에서 엔드투엔드(end-to-end)로 그라운딩(grounding)이 검증된 것입니다. "5분"이라는 시간에 대해 정확히 말씀드리자면, 엔진 측 단계는 매우 빠릅니다 (OAuth는 몇 초면 완료되며, 저희 실행 환경에서는 지식 베이스(knowledge-base) 인덱싱이 약 5초 만에 준비되었습니다). 실제 소요되는 시간의 대부분은 코딩 에이전트가 지침을 읽고 도구(tools)를 호출하는 데 사용되므로, 에이전트와 문서의 상태에 따라 전체 과정에 5분에서 10분 정도 소요될 것으로 예상하십시오.

3단계 — 사이트에 적용하기

이 과정이 완성되었다고 느끼게 만드는 부분은 다음과 같습니다. 만약 웹사이트 리포지토리(repo) 내부에서 프롬프트를 실행했다면, Claude Code는 단순히 스니펫(snippet)을 전달하는 데 그치지 않습니다. 에이전트는 해당 스니펫을 사이트 레이아웃에 직접 추가할 것을 제안하며, 정확히 어떤 변경이 일어나는지 보여준 뒤 사용자가 동의하면 이를 적용합니다. 한 줄의 디프(diff)를 검토하고 배포하면 채팅 위젯이 라이브 상태가 됩니다. (웹사이트 프로젝트 내부가 아니라면, </body 태그 앞에 직접 스니펫을 붙여넣으세요. 결과는 동일합니다.)

관리자 대시보드(admin dashboard)의 위젯 페이지 — 에이전트가 전달한 것과 동일한 스니펫에 외관 설정이 추가된 모습입니다.

에이전트가 구축한 모든 것은 SyntheticBrew 대시보드에서도 확인할 수 있습니다: 에이전트, 지식 베이스 (knowledge base), 문서 인덱싱 (document indexing) 상태, 그리고 실제 트래픽이 유입될 때의 대화 내용 등이 포함됩니다. 대시보드의 활성화 체크리스트는 각 구성 요소가 활성화됨에 따라 자동으로 체크됩니다. 설정 과정 중에는 직접 건드릴 필요가 없지만, 설정 이후에는 대화를 읽고, 문서를 업데이트하며, 지침 (instructions)을 조정하는 등 이곳에서 대부분의 작업을 수행하게 될 것입니다.

에이전트가 각 단계를 완료함에 따라 대시보드의 체크리스트가 완료됩니다.

또한 전체 배포가 단 하나의 프롬프트(prompt)로부터 이루어졌기 때문에 재현이 가능합니다. 프롬프트를 다시 실행하면 동일한 설정을 얻을 수 있으며, Claude Code에게 시스템 프롬프트를 업데이트하거나 문서를 교체해 달라고 요청하면 구축 시 사용했던 것과 동일한 도구들을 사용하여 작업을 수행합니다.

내부 작동 원리 (What's under the hood)

여기서는 두 가지 표준이 핵심적인 역할을 수행하며, 그 세부 사항이 매우 중요합니다. 이 표준들 덕분에 이 과정이 특정 벤더 종속 (vendor lock-in)을 유도하는 속임수처럼 느껴지지 않는 것입니다.

MCP (Model Context Protocol). SyntheticBrew의 MCP 서버는 공식 MCP 레지스트리에 등록된 일반적인 스트리밍 가능 HTTP 엔드포인트 (/api/v1/mcp/rpc)입니다. Claude Code는 단순한 MCP 클라이언트 (client)일 뿐입니다. 동일한 지침 파일(instruction file)에 Cursor, VS Code Copilot, Codex CLI, Windsurf, Zed, 그리고 Gemini CLI를 위한 연결 섹션이 포함되어 있습니다. 워크플로우의 어떤 부분도 Claude Code에만 국한되지 않습니다. 도구들은 데모용 래퍼 (shim)가 아니라 제품의 실제 관리 인터페이스 (admin surface)입니다.

동적 클라이언트 등록 (dynamic client registration)을 포함한 OAuth 2.1. 여러분의 코딩 에이전트는 장기 생존 API 키 (long-lived API key)를 절대 보지 않습니다. 에이전트는 스스로를 OAuth 클라이언트로 등록하고, PKCE를 실행하며, 프로비저닝 (provisioning) 및 관리에 범위가 제한된 토큰 (token)을 발급받습니다. 여러분은 브라우저의 개인 세션에서 한 번만 액세스를 승인하면 되며, 계정에서 이를 취소할 수도 있습니다. 이것이 바로 "관리자 키를 설정 파일에 붙여넣는 방식"과 "신뢰할 수 있는 모든 전문 SaaS에서 수용할 만한 인증 흐름 (auth flow)" 사이의 차이점입니다.

결과적으로, 여러분의 에디터는 문서화된 프로토콜에 따라 실제 인증 (auth)을 수행하는 관리 콘솔 (admin console)이 됩니다.

솔직한 한계점

거친 부분을 숨기는 튜토리얼은 여러분의 시간을 낭비하게 만듭니다. 따라서 다음과 같은 사항들을 미리 인지하시기 바랍니다:

• 가공되지 않은 검색 결과가 스트림에 노출됩니다. 최종 답변이 나오기 전, 현재 응답 스트림에는 에이전트가 검색한 가공되지 않은 "지식 검색 결과 (Knowledge search results)"가 포함되며, 이는 위젯에서도 확인 가능합니다. 최종 답변은 괜찮지만, 서문 (preamble)은 노이즈입니다. 이는 알려진 이슈입니다.
• MCP를 통한 지식 베이스 (knowledge-base) 삭제 불가. 도구 세트 (toolset)를 통해 문서와 에이전트는 삭제할 수 있지만, 지식 베이스는 삭제할 수 없습니다. 따라서 코딩 에이전트가 자신의 작업 내용을 완전히 되돌릴 수는 없습니다. 현재 지식 베이스를 삭제하려면 대시보드나 REST API를 사용해야 합니다.
• 도구 스키마 (tool schemas)가 엄격합니다. 필드 이름이 정확해야 합니다 (instructions가 아닌 system_prompt 사용, 세션 ID는 반드시 UUID여야 함). 코딩 에이전트는 도구 스키마를 읽기 때문에 대부분 스스로 수정하지만, 호출에 실패할 경우 에이전트가 완벽하게 통과하기보다는 수정된 인자 (arguments)로 한 번 더 재시도할 것을 예상해야 합니다.
• 그라운딩 (Grounding)이 핵심이며, 그 외에는 없습니다. 이 흐름은 문서에 기반한 (doc-grounded) Q&A 위젯을 제공합니다. SyntheticBrew에는 더 많은 메커니즘 (멀티 에이전트 위임, 메모리 등)이 있지만, 이 튜토리얼은 의도적으로 그것에 의존하지 않습니다. 문서 기반의 지원 에이전트야말로 오늘 당장 사용자 앞에 내놓을 수 있을 만큼 견고한 부분이기 때문입니다.
• 작은 문서는 몇 초 만에 인덱싱되지만, 큰 문서는 더 오래 걸립니다. 위에서 보여준 5초 인덱싱은 하나의 마크다운 (markdown) 파일 기준이었습니다. 실제 문서 세트의 경우에는 더 많은 시간을 할당하고, 폴링 (polling) 단계가 제 역할을 다하도록 기다려야 합니다.

시도해보기

한 줄의 명령어, 한 번의 브라우저 승인, 그리고 HTML에 붙여넣기 한 번이면 충분합니다:

Claude Code 복사 및 실행

Fetch https://syntheticbrew.ai/agent-setup/prompt.md and follow the instructions.

코드를 먼저 읽고 싶다면 엔진은 소스 공개 (source-available) 상태입니다. 또는 전체를 셀프 호스팅 (self-host)하여 여러분의 자체 배포 환경에서 동일한 흐름을 실행할 수도 있습니다.

계속 읽기