> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryvox.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

> Claude Code에 vox.ai MCP를 연결해 통화 중 음성 에이전트의 질문에 답하게 할 수 있어요.

Claude Code에 vox.ai 원격 MCP 서버를 연결해요. 연결하면 [AI 에이전트에게 전화기 주기](https://docs.tryvox.co/docs/ai/phone/overview.md)의 음성 에이전트 준비와 전화 걸기를 Claude Code에 맡길 수 있어요. 서버 주소와 인증 헤더 두 값으로 연결해요.

* **서버 주소**: `https://mcp.tryvox.co/mcp`
* **헤더**: `Authorization: Bearer sk_...`

키를 쓰는 대신 [vox.ai 계정으로 로그인](#키-대신-로그인으로-연결하기)해 연결할 수도 있어요.

## 준비물

* **Claude Code**: MCP 서버를 추가할 Claude Code가 필요해요.
* **서버용 API 키**: `sk_`로 시작하는 서버용 키가 필요해요. 만드는 방법은 [API 키](https://docs.tryvox.co/docs/workspace/api-keys.md)에서 확인하세요.
* **발신번호**: 전화를 걸려면 워크스페이스에 발신에 쓸 [전화번호](https://docs.tryvox.co/docs/operate/deploy/phone-numbers.md)가 있어야 해요.
* **통화 요금**: 실제 발신에는 통화 요금이 들어요. 요금과 동시 통화·운영 한도는 [요금](https://docs.tryvox.co/docs/start/pricing.md)에서 확인하세요.

## API 키로 연결하기

**1. 환경 변수에 API 키 설정하기**

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

```bash theme={null}
export VOX_API_KEY="sk_..."
```

**2. MCP 서버 추가하기**

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

```bash theme={null}
claude mcp add --transport http vox-ai https://mcp.tryvox.co/mcp \
  --header "Authorization: Bearer $VOX_API_KEY" --scope user
```

**3. 서버 연결 상태 확인하기**

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

```bash theme={null}
claude mcp list
```

**4. vox.ai 도구 허용하기**

Claude Code 사용자 설정 파일 `~/.claude/settings.json`의 `permissions.allow`에 `mcp__vox-ai__*`를 넣으세요. 넣지 않으면 기본 권한 모드가 도구를 만드는 `save_tool` 호출을 막아 음성 에이전트를 준비할 수 없어요.

```json theme={null}
{
  "permissions": {
    "allow": ["mcp__vox-ai__*"]
  }
}
```

파일에 다른 설정이 있으면 `allow` 배열에 항목만 더하세요. 설정을 바꾼 뒤에는 Claude Code를 다시 실행하세요.

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

API 키 없이 vox.ai 계정으로 로그인해 연결할 수도 있어요. 인증 헤더를 빼고 서버 주소만 추가하세요.

```bash theme={null}
claude mcp add --transport http vox-ai https://mcp.tryvox.co/mcp
```

Claude Code에서 `/mcp`를 열고 `vox-ai`를 골라 로그인하세요. 브라우저가 열리면 vox.ai 계정으로 로그인하고 **연결 승인**을 누르세요.

로그인 연결은 계정이 속한 워크스페이스를 대화로 바꿀 수 있어요. 자세한 연결 절차와 워크스페이스 전환 방법은 [MCP](https://docs.tryvox.co/docs/ai/mcp.md)에서 확인하세요.

## 연결 확인

Claude Code 대화에서 에이전트 목록을 조회해 연결을 확인하세요.

```text theme={null}
vox.ai에 연결된 에이전트 목록을 보여줘
```

목록이 보이면 [AI 에이전트에게 전화기 주기](https://docs.tryvox.co/docs/ai/phone/overview.md)의 음성 에이전트 준비하기 단계로 돌아가세요.

## 문제가 생겼을 때

> [accordion] claude mcp list에서 연결에 실패해요
>
> 서버용 API 키가 맞는지 확인하고 기존 연결을 지운 뒤 다시 추가하세요. `sk_`로 시작하는 서버용 키가 아니거나 잘못된 값이 들어가면 연결되지 않아요. `claude mcp remove vox-ai --scope user`로 서버를 지우고 새 키로 `claude mcp add`를 다시 실행하세요.

> [accordion] 연결에 쓴 API 키를 바꾸고 싶어요
>
> `claude mcp remove vox-ai --scope user`로 기존 서버를 지운 뒤 새 키로 다시 추가하세요. 키 값은 추가할 때 펼쳐져 Claude Code 설정 파일에 저장되기 때문에 셸의 `VOX_API_KEY` 환경 변수만 바꿔서는 반영되지 않아요.

> [accordion] ask\_brain 도구를 만들지 못했다고 해요
>
> `~/.claude/settings.json`의 `permissions.allow`에 `mcp__vox-ai__*`가 있는지 확인하고 Claude Code를 다시 실행하세요. 허용 규칙이 없으면 권한 검사가 `save_tool` 호출을 계정 설정 변경으로 보고 막아요.

> [accordion] 통화 중에 curl 실행 승인을 물어요
>
> 승인을 기다리는 동안 음성 에이전트의 질문에 답하지 못해요. 통화 전에 승인 창에서 같은 명령을 다시 묻지 않게 허용하거나, `/permissions`에서 `Bash(curl:*)`를 허용하세요.

> [accordion] 다른 워크스페이스로 바꾸고 싶어요
>
> 바꿀 워크스페이스에서 만든 서버용 API 키로 다시 연결하거나 [로그인 연결](#키-대신-로그인으로-연결하기)을 쓰세요. API 키로 붙은 연결은 키를 만든 워크스페이스 하나에서만 일하고 다른 워크스페이스로 바꿀 수 없어요.

## 관련 문서

* [AI 에이전트에게 전화기 주기](https://docs.tryvox.co/docs/ai/phone/overview.md): 중계 서버를 띄우고 통화 중 질문에 답하게 하기
* [MCP](https://docs.tryvox.co/docs/ai/mcp.md): 로그인으로 연결하고 워크스페이스 전환하기
* [MCP 도구](https://docs.tryvox.co/docs/ai/mcp-reference.md): 전체 도구 목록과 입력 규칙 보기
* [API 키](https://docs.tryvox.co/docs/workspace/api-keys.md): 서버용 API 키 만들고 관리하기


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.