Skip to main content
Claude Code에 vox.ai 원격 MCP 서버를 연결해요. 연결하면 AI 에이전트에게 전화기 주기의 음성 에이전트 준비와 전화 걸기를 Claude Code에 맡길 수 있어요. 서버 주소와 인증 헤더 두 값으로 연결해요.
  • 서버 주소: https://mcp.tryvox.co/mcp
  • 헤더: Authorization: Bearer sk_...
키를 쓰는 대신 vox.ai 계정으로 로그인해 연결할 수도 있어요.

​
준비물

  • Claude Code: MCP 서버를 추가할 Claude Code가 필요해요.
  • 서버용 API 키: sk_로 시작하는 서버용 키가 필요해요. 만드는 방법은 API 키에서 확인하세요.
  • 발신번호: 전화를 걸려면 워크스페이스에 발신에 쓸 전화번호가 있어야 해요.
  • 통화 요금: 실제 발신에는 통화 요금이 들어요. 요금과 동시 통화·운영 한도는 요금에서 확인하세요.

​
API 키로 연결하기

1

환경 변수에 API 키 설정하기

Claude Code를 실행할 셸에 서버용 API 키를 환경 변수로 설정하세요. sk_... 자리에 만든 키를 넣으면 다음 명령에서 헤더로 전달돼요.
2

MCP 서버 추가하기

claude mcp add 명령으로 vox-ai 서버를 등록하세요. --scope user는 모든 프로젝트에서 이 연결을 쓰게 해요. 환경 변수에 넣은 키 값은 추가할 때 펼쳐져 Claude Code 설정 파일에 저장돼요.
3

서버 연결 상태 확인하기

등록한 서버 목록을 조회하세요. 목록에서 vox-ai가 Connected로 보이면 연결이 끝나요.
4

vox.ai 도구 허용하기

Claude Code 사용자 설정 파일 ~/.claude/settings.json의 permissions.allow에 mcp__vox-ai__*를 넣으세요. 넣지 않으면 기본 권한 모드가 도구를 만드는 save_tool 호출을 막아 음성 에이전트를 준비할 수 없어요.
파일에 다른 설정이 있으면 allow 배열에 항목만 더하세요. 설정을 바꾼 뒤에는 Claude Code를 다시 실행하세요.

​
키 대신 로그인으로 연결하기

API 키 없이 vox.ai 계정으로 로그인해 연결할 수도 있어요. 인증 헤더를 빼고 서버 주소만 추가하세요.
Claude Code에서 /mcp를 열고 vox-ai를 골라 로그인하세요. 브라우저가 열리면 vox.ai 계정으로 로그인하고 연결 승인을 누르세요. 로그인 연결은 계정이 속한 워크스페이스를 대화로 바꿀 수 있어요. 자세한 연결 절차와 워크스페이스 전환 방법은 MCP에서 확인하세요.

​
연결 확인

Claude Code 대화에서 에이전트 목록을 조회해 연결을 확인하세요.
목록이 보이면 AI 에이전트에게 전화기 주기의 음성 에이전트 준비하기 단계로 돌아가세요.

​
문제가 생겼을 때

서버용 API 키가 맞는지 확인하고 기존 연결을 지운 뒤 다시 추가하세요. sk_로 시작하는 서버용 키가 아니거나 잘못된 값이 들어가면 연결되지 않아요. claude mcp remove vox-ai --scope user로 서버를 지우고 새 키로 claude mcp add를 다시 실행하세요.
claude mcp remove vox-ai --scope user로 기존 서버를 지운 뒤 새 키로 다시 추가하세요. 키 값은 추가할 때 펼쳐져 Claude Code 설정 파일에 저장되기 때문에 셸의 VOX_API_KEY 환경 변수만 바꿔서는 반영되지 않아요.
~/.claude/settings.json의 permissions.allow에 mcp__vox-ai__*가 있는지 확인하고 Claude Code를 다시 실행하세요. 허용 규칙이 없으면 권한 검사가 save_tool 호출을 계정 설정 변경으로 보고 막아요.
승인을 기다리는 동안 음성 에이전트의 질문에 답하지 못해요. 통화 전에 승인 창에서 같은 명령을 다시 묻지 않게 허용하거나, /permissions에서 Bash(curl:*)를 허용하세요.
바꿀 워크스페이스에서 만든 서버용 API 키로 다시 연결하거나 로그인 연결을 쓰세요. API 키로 붙은 연결은 키를 만든 워크스페이스 하나에서만 일하고 다른 워크스페이스로 바꿀 수 없어요.

​
관련 문서