MCP 커넥터

언어 값을 지정하려면 통화 언어 코드에서 전체 코드 표와 REST 생성·통화 중 변경·MCP 요청 예시를 확인하세요.

gateway는 MCP(Model Context Protocol) 서버를 함께 제공합니다. Claude 같은 MCP 클라이언트에 번호를 붙이면 대화로 전화를 걸고, 결과를 조회하고, 통화를 끊을 수 있습니다.

서버 주소

https://vox-gateway-prod.fly.dev/mcp/

끝 슬래시가 계약입니다. /mcp로 접속하는 클라이언트도 있어 서버가 정규화해 주지만, 설정에는 슬래시까지 넣으세요.

연결하기

연결 방법은 셋이고, 클라이언트가 헤더를 넣을 수 있는지에 따라 갈립니다. 헤더를 지정할 수 있으면 번호 API 키 하나로 끝나고, 그렇지 않은 클라이언트(Claude 웹·데스크톱의 커넥터 화면에는 임의 헤더 칸이 없습니다)를 위해 나머지 둘이 있습니다.

헤더에 번호 API 키

인증은 REST와 같은 번호 API 키입니다. 그대로 Bearer로 넘기면 됩니다.

{
"mcpServers": {
  "vox-gateway": {
    "url": "https://vox-gateway-prod.fly.dev/mcp/",
    "headers": { "Authorization": "Bearer tg_live_..." }
  }
}
}

계정으로 로그인 (OAuth)

커넥터가 OAuth로 연결되면 키가 아니라 여러분의 계정이 정체성이 됩니다. 접근 가능한 워크스페이스의 번호가 모두 보이고, 도구에 번호 선택 인자가 추가됩니다(from_number · number). 이 방식은 플랫폼에서 켜져 있을 때만 나타납니다 — 커넥터를 추가해도 로그인 화면으로 넘어가지 않으면 꺼져 있는 것입니다.

커넥터 전용 주소

기본적으로 닫혀 있는 제한 기능입니다. 운영자가 번호 단위로 열어 준 경우에만 동작하고, 열려 있지 않은 번호의 주소는 형식이 맞아도 404입니다. 열려 있는지는 번호 상세에서 확인하세요 — 주소가 보이지 않으면 아직 열려 있지 않은 것이고, 주소를 직접 만들어 붙여넣는 것으로는 열리지 않습니다.

https://vox-gateway-prod.fly.dev/mcp/t/{번호 API 키}/

번호 상세 › 아웃바운드에서는 앞부분만 마스킹되어 보이고, 복사를 누르면 그때 완성 주소를 가져옵니다(워크스페이스 관리자만, 가져간 기록이 남습니다). 2026년 8월 20일 이전에 발급한 키는 복사할 수 없어 재발급이 필요합니다.

제공 도구

make_call.language는 이번 통화에만 적용됩니다. 생략하면 번호 → 워크스페이스 → 한국어 순으로 설정을 사용합니다. 중국어(zh)는 xAI를 사용할 수 있습니다. 태국어(th)처럼 xAI 사용 불가능 언어를 지정하면 OpenAI STT·Google TTS로 전환하므로 해당 공급자의 키가 필요합니다. 자세한 조합과 통화 중 변경 제한은 언어별 공급자를 참고하세요.

• REST와 달리 make_call은 instruction이 필수입니다. MCP는 "임무를 말로 시키는" 표면이라 임무 없이 거는 것이 의미가 없기 때문입니다. 반대로 REST는 agent가 이미 임무를 아는 연동을 상정해 to만 필수입니다(Create Call).
• end_call은 통화 밖에서 부르는 도구라 기다리지 않고 즉시 끊습니다. 통화 중인 agent가 작별 인사를 하고 끊으려면 MCP가 아니라 Hang Up Call을 쓰세요 — MCP로 부르면 인사가 잘립니다.
• 조회 도구(get_call · list_my_calls · get_transcript · get_recording_link)는 그 키의 번호로 건 통화만 돌려줍니다. 남의 통화는 존재 여부도 알려주지 않고 call not found가 됩니다.
• summary는 통화 전체를 한 줄로 줄인 값입니다. "상대가 뭐라고 했어?"처럼 실제로 오간 말(날짜·금액·약속)을 물으면 요약에서 추측하지 말고 get_transcript를 부르게 하세요.

통화 결과 확인

통화가 끝나면 세 가지를 볼 수 있습니다 — 요약 한 줄(get_call), 오간 말 전문(get_transcript), 녹음(get_recording_link). 셋은 서로 대체재가 아닙니다.

전문 읽기

get_transcript은 turn 배열과 함께 통화의 status를 돌려줍니다. 빈 배열의 뜻이 그 값으로 갈립니다 — 진행 중이면 "아직 아무도 말하지 않았다"이고, 끝난 통화면 "전사본이 없는 통화"(받지 않았거나 말 없이 끝남)입니다. 후자를 "상대가 아무 말도 안 했다"고 옮기면 사실과 다릅니다.

상대 쪽 텍스트는 음성 인식 결과라 잘못 들은 말이 섞일 수 있고 숫자가 말로 풀려 나오기도 합니다 — 원문이 아니라 "들린 것"으로 다루세요. 진행 중에 불러도 그 시점까지의 턴을 돌려줍니다.

녹음 듣기

오디오는 커넥터로 오갈 수 없습니다 — 이 연결은 텍스트만 주고받습니다. 그래서 get_recording_link은 파일이 아니라 브라우저에서 열 링크를 돌려줍니다(url · expires_at). 녹음을 듣는 유일한 길입니다.

get_call과 list_my_calls의 각 통화에는 recording이 함께 옵니다. get_recording_link는 이 값이 available일 때만 링크를 내주므로, 링크를 찍어보기 전에 여기부터 읽는 편이 빠릅니다.

녹음은 번호 단위 설정입니다 — 번호 관리 › 번호 › 음성 탭의 "통화 녹음" 토글이고, 다음 통화부터 적용됩니다. 통화 한 건만 켜고 끌 수는 없습니다.

번호 결정

번호 API 키나 커넥터 전용 주소로 연결했다면 그 키의 번호로 고정됩니다 — 고를 것이 없고, 아래 인자도 나타나지 않습니다.

OAuth로 연결했다면 정체성이 계정이라 번호가 자동으로 정해지지 않습니다. 규칙은 다음 순서입니다.

1. 번호를 지정했으면 그 번호 — 거는 도구는 from_number, 끊는 도구는 number입니다. 접근 권한이 없으면 403 number_not_allowed.
2. 지정하지 않았고 접근 가능한 번호가 정확히 하나면 그 번호.
3. 둘 이상이면 임의로 고르지 않고 거절합니다 — 후보 목록을 함께 돌려주니 하나를 골라 다시 부르세요.

{
"ok": false,
"reason": "from_number_required",
"candidates": [
  { "number_id": "6b2e…", "phone": "07079193558", "workspace_name": "우리 팀" },
  { "number_id": "8c41…", "phone": "07079193559", "workspace_name": "지원팀" }
]
}

end_call도 같은 상황에서 같은 모양으로 거절하는데, 사유 이름만 number_required입니다 — 그 도구의 인자 이름이 number이기 때문입니다.

조회 도구는 접근 가능한 워크스페이스를 가로질러 통화를 찾지만, 끊는 표면은 번호 단위로 좁아집니다 — 그래서 list_my_calls로 찾은 통화를 끊을 때 번호를 함께 넘겨야 할 수 있습니다. 값은 후보 목록이나 조회 결과의 number_id를 그대로 쓰면 됩니다.

발신 번호가 없을 때는 422 no_number_available입니다. 전체 코드는 에러 코드를 보세요.

다음 단계