MCP 전화 tool 설계 — make_call / hang_up / transfer / DTMF 패턴 정리

MCP 서버에 전화 기능을 노출할 때 tool 을 어떻게 쪼개느냐로 LLM 사용성이 갈린다. 너무 잘게 쪼개면 LLM 이 순서 헷갈리고, 너무 묶으면 통제 못 함. 실전 검증된 5-tool 셋.

권장 tool 셋

tool	역할	호출 시점
make_call	단방향 메시지 발신 (짧은 알림)	알림성 시나리오
make_call_with_prompt	대화형 통화 (AI 가 system_prompt 대로 응대)	예약/상담/cold call
hang_up	진행 중 통화 종료	AI 가 통화 중 목적 달성시
dtmf	진행 중 통화에 DTMF tone 보내기	ARS 응답, 본인인증
transfer	진행 중 통화를 다른 사람한테 warm/blind transfer	담당자 연결
get_call_summary	끝난 통화 요약·전사 조회	결과 보고

1. make_call — 단방향 메시지

@server.tool()
def make_call(to: str, message: str) -> dict:
    """짧은 알림 전달 후 즉시 종료. message 는 1-3 문장 권장."""
    call = client.calls.create(
        to=to, from_=DEFAULT_FROM,
        agent_config={
            "system_prompt": f"다음 메시지만 정확히 전달하고 즉시 끊으세요: '{message}'",
            "language": "ko-KR",
            "max_duration_seconds": 60,
        },
    )
    return {"call_id": call.id, "estimated_duration_seconds": 30}

LLM 이 헷갈리지 않게: message 가 그대로 전달된다고 명시. 시스템 프롬프트 작성을 LLM 한테 떠넘기지 말 것.

2. make_call_with_prompt — 대화형

@server.tool()
def make_call_with_prompt(
    to: str,
    system_prompt: str,
    max_duration_seconds: int = 300,
) -> dict:
    """대화형 통화. system_prompt 는 AI 가 따를 지시. 결과는 get_call_summary 로 조회."""
    call = client.calls.create(
        to=to, from_=DEFAULT_FROM,
        agent_config={
            "system_prompt": system_prompt,
            "language": "ko-KR",
            "max_duration_seconds": max_duration_seconds,
            "tools": ["hang_up", "dtmf", "transfer"],  # AI 가 통화 중에 호출 가능
        },
    )
    return {"call_id": call.id}

핵심: AI 가 통화 중에 hang_up/dtmf/transfer 를 사용할 수 있게 agent_config 에 활성화.

3. hang_up — 통화 중 종료

ClawOps SDK 에서는 AI 가 통화 안에서 자동 호출 (system_prompt 에 "목적 달성하면 hang_up" 박혀있으면 됨). MCP tool 로도 외부에서 강제 종료 가능:

@server.tool()
def hang_up(call_id: str) -> dict:
    """진행 중 통화 강제 종료."""
    client.calls.hangup(call_id)
    return {"call_id": call_id, "status": "ended"}

4. dtmf — ARS 응답

@server.tool()
def dtmf(call_id: str, digits: str) -> dict:
    """진행 중 통화에 DTMF tone 전송. digits 예: '1234' 또는 '*0#'."""
    client.calls.send_dtmf(call_id, digits)
    return {"sent": digits}

사용 예: 외부 ARS 메뉴 "1번 상담원" 누르기, 본인인증 응답.

5. transfer — Warm/Blind

@server.tool()
def transfer(call_id: str, to: str, mode: str = "warm", context: str = "") -> dict:
    """진행 중 통화를 다른 사람한테 전환.
    - mode='warm': AI 가 새 수신자한테 context 먼저 전달 후 연결
    - mode='blind': 즉시 전환
    """
    client.calls.transfer(call_id, to=to, mode=mode, context=context)
    return {"status": "transferred", "to": to, "mode": mode}

6. get_call_summary — 결과 조회

@server.tool()
def get_call_summary(call_id: str, wait_seconds: int = 0) -> dict:
    """통화 결과/요약/전사. wait_seconds > 0 이면 폴링."""
    import time
    deadline = time.time() + wait_seconds
    while True:
        call = client.calls.get(call_id)
        if call.status == "ended" or time.time() > deadline:
            return {
                "status": call.status,
                "duration_seconds": call.duration_seconds,
                "summary": getattr(call, "summary", None),
                "transcript_url": getattr(call, "transcript_url", None),
            }
        time.sleep(2)

wait_seconds 패라미터: LLM 이 "1분 통화니까 80초 기다리고 결과 가져와줘" 식으로 쓸 수 있음.

7. 안 권장 — 묶지 말 것

• make_call_and_get_summary (발신+대기+결과 묶기) — 통화 시간이 변동 큰데 동기 호출이라 timeout 위험
• start_recording/stop_recording 별도 tool — ClawOps 는 기본 자동 녹음이라 별도 tool 불필요
• set_caller_id 통화별 — from_number 를 agent_config 에 직접

8. tool description 작성 팁 (LLM 한테 잘 쓰이게)

• 한 문장 안에 언제 쓰는지 명시 ("짧은 알림용", "대화형 통화용")
• 파라미터 한국어 예시 ("010-1234-5678 형식")
• 부작용 명시 ("통화 종료 즉시 dispatcher 호출")
• 다른 tool 과의 관계 명시 ("get_call_summary 로 결과 조회")

LLM 은 description 만 보고 어떤 tool 을 쓸지 결정. 모호하면 wrong tool 선택.

9. 작동 원리

LLM
  ↓ MCP tool call
당신의 mcp 서버
  ↓ ClawOps SDK
api.claw-ops.com
  ↓
한국 070 → 대상 휴대폰

다음 단계

• MCP 음성 서버 직접 만들기 (코드 50줄)
• Call Transfer Warm/Blind 구현
• Claude Code 에 070 붙이기