통화 중 고객사 시스템 조회: AI 상담원에 HTTP 도구·MCP 도구 붙이기
KAT Cloud AI 상담원은 HTTP 도구로 고객사 API 하나를, MCP 도구로 고객사의 Streamable HTTP MCP 서버를 통화 중에 불러 주문·예약을 조회하고 처리합니다. 등록 필드, 받는 요청, 쓰기 확인, tools/list와 refresh를 정리했습니다.

KAT Cloud AI 상담원이 통화 중에 고객사 시스템을 조회하게 하려면 상담원에 도구를 등록합니다. HTTP 도구는 고객사 API 하나를, MCP 도구는 고객사가 운영하는 Streamable HTTP 방식 MCP 서버 하나를 상담원이 직접 부르는 방식입니다. 상담원 하나에 HTTP와 MCP를 합쳐 10개까지 붙일 수 있고(AG012), 데이터를 바꾸는 도구는 손님께 내용을 되읽고 확인받은 뒤에만 부릅니다.
여기서 MCP 서버는 고객사 쪽에 있습니다. KAT Cloud가 외부 에이전트용 MCP 서버를 제공하는 것이 아니라, KAT Cloud 상담원이 MCP 클라이언트로서 고객사 서버를 호출합니다. 개념은 용어집의 도구 호출과 MCP를 참고하세요.
HTTP 도구와 MCP 도구, 무엇을 고를까
| 구분 | HTTP 도구 | MCP 도구 |
|---|---|---|
| 등록 단위 | API 주소 하나 | MCP 서버 하나(안의 도구 여러 개) |
| 인자 정의 | 등록할 때 inputSchema로 직접 | 서버의 tools/list에서 받아 옴 |
| 상담원에게 보이는 이름 | ext_<name> | mcp_<name>_<도구> |
| 쓰기 여부 | write: true로 지정 | 도구의 readOnlyHint: true만 조회용으로 봄 |
| 맞는 경우 | 조회 API 한두 개 | 이미 MCP 서버가 있거나 도구가 여러 개 |
HTTP 도구 등록하기
curl -X POST "https://studio-gateway.zerocall.kr/group/1/agent/7/tool" \
-H "x-api-key: $KAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"kind": "HTTP",
"name": "reservation_lookup",
"description": "손님 전화번호로 다가오는 예약을 조회한다. 손님이 내 예약을 확인하고 싶다고 하면 쓴다.",
"url": "https://api.example.com/reservations/upcoming",
"httpMethod": "GET",
"inputSchema": {
"type": "object",
"properties": { "date": { "type": "string", "description": "YYYY-MM-DD, 모르면 생략" } }
},
"authType": "BEARER",
"authSecret": "sk_live_your_secret",
"timeoutMs": 4000
}'description은 상담원이 도구를 고르는 근거이므로 "무엇을 하는지"와 "언제 쓰는지"를 함께 적습니다. 주소는 https 공인 주소만 받고 내부망·사설 주소는 거절합니다(AG011). 인증값(authSecret)은 암호화해 저장되고 응답에는 다시 나오지 않습니다. 전체 필드는 도구 등록 문서에 있습니다.
고객사 서버가 받는 요청과 답하는 법
상담원이 도구를 부르면 GET은 인자를 쿼리로, POST는 JSON 본문으로 보냅니다. 함께 오는 헤더로 통화와 손님을 확인할 수 있습니다.
app.get('/reservations/upcoming', async (req, res) => {
if (req.get('Authorization') !== `Bearer ${process.env.TOOL_SECRET}`) {
return res.status(401).json({ error: '인증 실패' });
}
const caller = req.get('X-Zerocall-Caller'); // 손님 발신번호
const callId = req.get('X-Zerocall-Call-Id'); // 통화 기록 ID
const list = await findUpcoming(caller, req.query.date);
if (list.length === 0) {
// 4xx 본문의 이유를 상담원이 그대로 안내합니다
return res.status(404).json({ message: '이 번호로 다가오는 예약이 없습니다' });
}
// 필요한 값만 짧게. 32KB를 넘으면 잘립니다
res.json(list.slice(0, 3).map((r) => ({ date: r.date, time: r.time, people: r.people })));
});응답 규칙에서 꼭 지킬 것은 세 가지입니다.
- `timeoutMs` 안에 답합니다. 상담원은 도구의 답을 받기 전까지 다음 말을 하지 않으므로, 늦으면 통화가 조용해집니다. 기본값은 5,000ms, 범위는 1,000~8,000ms입니다.
- 실패를 정직하게 돌려줍니다. 4xx면 상담원이 본문 내용을 지어내지 않고 안내하고, 5xx·시간 초과·연결 실패면 처리했다고 말하지 않고 확인이 필요한 건으로 남깁니다.
- 리다이렉트를 쓰지 않습니다. 3xx는 따라가지 않습니다.
쓰기 도구와 중복 방지
주문 취소, 예약 변경처럼 데이터를 바꾸는 HTTP 도구는 write: true로 등록합니다. 상담원은 보낼 내용을 되읽고 손님이 "네"라고 확인한 뒤에만 부르고, 같은 통화에서 이미 처리한 같은 요청은 다시 보내지 않습니다. 그래도 네트워크 재시도는 생길 수 있으므로 서버에서는 Idempotency-Key 헤더로 같은 요청을 한 번만 처리하세요. 이 키는 통화 ID와 도구, 인자로 만든 40자 값입니다. 원리는 용어집 멱등성에 있습니다.
MCP 도구 붙이기
이미 Streamable HTTP 방식의 MCP 서버가 있다면 kind: "MCP"로 서버 하나를 등록합니다.
{
"kind": "MCP",
"name": "shop",
"description": "주문 조회와 취소. 손님이 주문 건으로 문의하면 쓴다.",
"url": "https://mcp.example.com/mcp",
"authType": "BEARER",
"authSecret": "sk_live_your_secret",
"allowedTools": ["get_order", "cancel_order"]
}MCP 서버 문서의 동작은 이렇습니다.
- 1등록할 때 서버의
tools/list를 받아 저장합니다. 받지 못하면AG015가 반환됩니다. - 2통화 중에는 목록을 다시 받지 않습니다. 서버의 도구를 바꿨다면
POST .../tool/{toolId}/refresh를 불러야 상담원에게 반영됩니다. - 3
allowedTools에 적은 도구만 상담원에게 보입니다. 비우면(null) 쓸 수 있는 도구 전부입니다. 관리용 도구가 섞인 서버라면 꼭 좁혀 두세요. - 4
readOnlyHint: true인 도구만 조회용으로 보고, 나머지는 쓰기 도구처럼 되읽고 확인받은 뒤 부릅니다. - 5
anyOf·oneOf·$ref처럼 줄일 수 없는 스키마를 쓰는 도구는usable: false가 되고unusableReason에 이유가 담깁니다.
중복 방지 키는 tools/call의 _meta["zerocall/idempotencyKey"]로 오고, 시간 제한·32KB·주소 검사는 HTTP 도구와 같습니다.
등록 후 시험 호출하기
POST .../tool/{toolId}/test에 args와 callerPhoneNumber를 넣으면 실제로 불러 상태 코드, 걸린 시간(latencyMs), 응답 앞부분을 돌려줍니다. HTTP 쓰기 도구도 실제로 부르므로 시험 서버 주소로 해 보세요. MCP 도구는 서버에 연결해 도구 목록만 받습니다. latencyMs가 timeoutMs에 가깝다면 응답을 줄이거나 조회를 미리 캐시해 두는 편이 통화 품질에 낫습니다. 음성 대화에서 침묵이 왜 문제인지는 음성 AI 지연 시간에서 다룹니다.
KAT Cloud 가입하기로 시작하거나, 어떤 시스템을 도구로 열지 함께 정하려면 도입 상담을 신청하세요.
자주 묻는 질문
KAT Cloud가 MCP 서버를 제공하나요?
KAT Cloud는 외부 에이전트용 MCP 서버를 제공하지 않습니다. KAT Cloud의 MCP 도구는 반대 방향으로, AI 상담원이 통화 중에 고객사가 운영하는 Streamable HTTP 방식 MCP 서버를 호출하는 기능입니다.
도구 응답이 늦으면 통화는 어떻게 되나요?
KAT Cloud AI 상담원은 도구의 답을 받기 전까지 다음 말을 하지 않으므로 그동안 통화가 조용해집니다. 등록한 timeoutMs(1,000~8,000ms, 기본 5,000ms)를 넘기면 처리했다고 말하지 않고 담당자가 확인 후 연락드리겠다고 안내하며, 그 요청은 확인이 필요한 건으로 남습니다.
MCP 서버에 도구를 추가했는데 상담원이 쓰지 않습니다.
KAT Cloud는 MCP 도구를 등록할 때 받은 tools/list를 저장해 쓰고 통화 중에는 다시 받지 않습니다. 서버의 도구를 바꿨다면 refresh API를 불러 목록을 다시 받고, allowedTools를 지정해 두었다면 새 도구 이름도 추가해야 합니다.
- #AI 상담원
- #도구 호출
- #MCP
- #HTTP API
- #통화 중 조회



