kavilo
로그인

가이드

자체 MCP 서버 연결하기

에이전트는 보통, 당신이 Context에 쓴 내용으로 답합니다. 답이 살아 있는 시스템 — CRM, 재고 서비스, 데이터베이스 — 안에 있다면, 대신 당신이 운영하는 MCP 서버를 가리킬 수 있습니다. 에이전트가 질문이 있을 때 그 서버를 호출하고, 반환된 것으로 계속 진행합니다. 소스 시스템은 당신의 네트워크에 남고, 도구 요청과 응답만, 그 대화를 위해 우리의 호스팅 서비스를 지나갑니다.

kavilo를 어떻게 실행하느냐에 따라, 두 가지 방식이 있습니다:

  • 호스팅 Enterprise 플랜 — 포털에서 context 프로바이더를 구성합니다. 방문자의 서명 토큰에 context 키가 담겨 있으면, 에이전트는 답하기 전에 MCP 도구 하나를 호출해, 서버가 그 방문자에게 해당하는 데이터를 반환하게 합니다. 키가 없는 방문자는 호출을 건너뜁니다.
  • 셀프 호스팅 — config.json의 tools.mcpServers에 MCP 서버 하나 이상을 추가합니다. 그러면 에이전트가 추론 중에 호출할 수 있는 도구가 됩니다. 내장 도구가 동작하는 방식과 같습니다.

호스팅 Enterprise: context 프로바이더

포털에서 봇 설정을 열고, MCP context provider로 스크롤하세요. 네 가지를 설정합니다:

  • Endpoint URL — MCP 서버의 HTTP 또는 HTTPS 주소. 우리의 클라우드에서 도달 가능해야 합니다. 로컬 주소나 private IP는 동작하지 않습니다 — 개발 중에는 공개 호스트명이나 터널(Cloudflare Tunnel, Tailscale Funnel, ngrok)을 쓰세요.
  • Tool name — 호출할 MCP 도구의 이름. 서버가 노출하는 도구의 이름으로, 고르는 것은 당신입니다.
  • Header carrying the visitor key (선택) — 백엔드가 발행한 방문자 토큰의 불투명 context 키를 전달할 때 쓰는 헤더 이름. 기본값은 X-Context-Key입니다. 토큰에 키가 있을 때만 도구가 호출되고, 공개 키로 온 방문자는 호출을 건너뜁니다.
  • Auth header and credential (선택) — 서버가 당신에게 kavilo임을 알리는 헤더와 고정 값. 예: X-API-Key와 당신이 만든 비밀. context 키와 별개입니다: 인증 자격 증명은 호출자를, context 키는 방문자를 식별합니다. 자격 증명은 쓰기 전용입니다 — 당신은 설정하고, 우리는 절대 반환하지 않습니다.

저장한 뒤, Test connection으로 에이전트가 서버에 도달하고 도구를 호출할 수 있는지 확인하세요. 테스트는 서버가 노출하는 도구를 나열합니다 — 지정한 도구가 그 목록에 없으면, 런타임에서 봇이 쓸 수 없습니다.

런타임에서, context 키를 가진 방문자의 요청이 답 이전에 도구를 트리거합니다. 반환된 것은, 그 턴의 에이전트 context에 주입됩니다. 호출이 타임아웃(기본 5초)되거나 에러를 반환하면, 에이전트는 답을 거절하기보다, 없이는 계속 진행합니다 — 도구가 빨리 반환하고, 실패해도 그럭저럭 동작하도록 설계하세요.

도구의 원시 응답은 봇의 영구 Context에 추가되지 않지만, 거기서 나온 사실은 답변에 — 따라서 저장된 대화와 전사본에 — 나타날 수 있습니다.

셀프 호스팅: tools.mcpServers

config.json에서 tools.mcpServers 아래에 각 서버를 추가하세요. 키가 alias가 되고, 에이전트는 mcp_<alias>_<tool> 이름의 도구를 봅니다.

HTTP 서버:

"tools": { "mcpServers": { "inventory": { "url": "https://internal.example.com/mcp", "enabled": true } } }

로컬 프로세스 (stdio):

"tools": { "mcpServers": { "crm": { "command": "npx", "args": ["-y", "@example/crm-mcp"], "env": { "CRM_API_KEY": "sk_…" }, "enabled": true } } }

에이전트는 추론 중, 내장 도구를 호출하는 방식과 똑같이, 스스로 이 도구들을 호출합니다. enabledTools를 설정해, 서버의 도구 중 노출할 것을 제한할 수도 있습니다.

config.json의 변경은 다음 kavilo start에 적용됩니다. kavilo mcp 명령은, 파일을 손으로 편집하지 않고 서버 항목을 관리하는 데 도움을 줍니다.

네트워크를 나가는 것

호스팅 Enterprise 플랜에서는, 대화, MCP 요청, 도구 응답이 우리의 클라우드에서 처리됩니다. 기반 시스템은 당신의 네트워크에 남지만, 요청, 선택적인 서명 방문자 토큰, 반환된 로우나 객체는 경계를 넘습니다. 그것을 받아들일 수 없다면, 에이전트를 셀프 호스팅하고 로컬 추론을 써서, 대화도 도구 데이터도 나가지 않게 하세요.

활용하기

MCP context는 Enterprise 플랜에서 제공됩니다. 더 낮은 플랜에서는 설정이 숨겨집니다. 플랜 업그레이드 — 또는, 배포를 고르기 전에 데이터 경계에 대해 이야기하고 싶다면 문의하기.