---
title: "ThunderPhone을 MCP 서버로 사용하기"
description: "Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code 또는 다른 Streamable HTTP MCP 클라이언트에서 ThunderPhone 음성 에이전트를 구축, 테스트, 검증 및 운영합니다."
---

ThunderPhone은 다음 위치에서 Streamable HTTP Model Context Protocol 서버를 제공합니다.

```text
https://api.thunderphone.com/v1/mcp
```

이는 [원격 MCP 서버를 음성 에이전트에 연결하는 것](/ko/guides/mcp-servers)과 반대 방향입니다.

| 방향 | 결과 |
| --- | --- |
| 원격 MCP 서버 → ThunderPhone 에이전트 | 음성 에이전트가 원격 서버의 도구를 호출할 수 있습니다. |
| ThunderPhone → MCP 클라이언트 | 코딩 에이전트가 ThunderPhone을 구축, 테스트, 운영할 수 있습니다. |

## 인증

디렉터리 클라이언트에서는 기본적으로 [OAuth](/ko/guides/oauth)를 사용합니다. 로그인하고, 조직을 선택한 다음, 요청된 권한을 승인합니다. **조직 → API 키 → 승인된 앱**에서 액세스를 취소합니다.

API 키로 구성된 클라이언트의 경우 **조직 → 키**에서 `sk_live_` 키를 생성하고 MCP 클라이언트에 `THUNDERPHONE_API_KEY`로 노출합니다. 이 키는 하나의 조직에 연결됩니다. 다른 조직이 소유한 ID는 찾을 수 없는 것으로 처리됩니다.

<Warning>
  `sk_live_` 키는 조직 데이터를 읽고 에이전트 배포, 통화 발신, 번호 구매, 캠페인 시작, 리소스 삭제와 같은 프로덕션 작업을 수행할 수 있습니다. 브라우저 코드, 리포지토리, 스크린샷, 채팅 로그에 포함하지 마세요. 클라이언트의 비밀 저장소 또는 환경 변수 지원을 사용하고, 노출된 키는 즉시 취소하세요.
</Warning>

## CLI 및 stdio 대안

[ThunderPhone CLI](/ko/guides/cli)는 관련 없는 서버를 유지하면서 클라이언트 구성을 작성할 수 있습니다.

```bash
npx -y @thunderphone/mcp setup --client cursor --api-key-env THUNDERPHONE_API_KEY
npx thunderphone mcp setup --client claude-desktop --scope user
```

`@thunderphone/mcp`를 전역 설치한 후에는 동일한 옵션으로 `thunderphone-mcp setup`을 사용합니다. 설정은 Claude Code, Codex, Cursor, VS Code, Gemini, Claude Desktop, Windsurf를 지원합니다. 직접 HTTP 사용이 권장되며, Desktop은 stdio를 사용합니다.

stdio를 지원하는 모든 클라이언트에서는 `command: "npx"`와 `args: ["-y", "@thunderphone/mcp"]`를 구성합니다. 래퍼는 먼저 `THUNDERPHONE_API_KEY`를 사용하고, 그다음 만료된 토큰을 갱신하면서 `thunderphone login`의 자격 증명을 사용한 후, `mcp-remote`를 통해 OAuth를 사용합니다. 기기 로그인과 OAuth를 사용하려면 해당 API OAuth가 출시되어 있어야 합니다. API 키 방식에는 필요하지 않습니다. 직접 HTTP 구성은 CLI 자격 증명 저장소를 읽지 않으므로, 기기 로그인을 재사용하려면 stdio 래퍼를 사용합니다.

이는 아래의 수동 클라이언트 구성에 대한 대안입니다.

## 클라이언트 구성

Claude와 ChatGPT는 [OAuth](/ko/guides/oauth)로 로그인하며 API 키는 사용하지 않습니다. 아직 ThunderPhone 계정이 없다면 로그인 페이지에서 **계정 만들기**를 선택하세요. 이메일 인증 후 승인 화면으로 돌아갑니다.

### Claude(웹, 데스크톱 및 모바일)

1. **사용자 지정 → 커넥터**를 엽니다(이전 버전에서는 **설정 → 커넥터**). 커넥터 디렉터리에 ThunderPhone이 표시되면 선택합니다. 그렇지 않으면 **사용자 지정 커넥터 추가**를 선택하고 이름을 `ThunderPhone`으로 지정한 후 `https://api.thunderphone.com/v1/mcp`를 입력합니다.
2. **연결**을 선택하고 ThunderPhone에 로그인한 다음 조직을 선택하고 권한을 승인합니다.
3. 채팅에서 도구 메뉴로 ThunderPhone을 활성화하고 필요한 작업을 요청합니다. 예: "내 에이전트 목록 표시".

Claude는 각 도구를 처음 사용하기 전에 요청합니다. 대부분의 프롬프트를 건너뛰려면 **사용자 지정 → 커넥터 → ThunderPhone**을 열고 **읽기 전용 도구**를 항상 허용으로 설정합니다. 이 도구는 에이전트, 통화, 트랜스크립트, 잔액, 문서만 조회합니다. 변경이 적용되기 전에 각각 확인하려면 **쓰기/삭제 도구**는 승인으로 유지합니다.

사용자 지정 커넥터를 사용하려면 유료 Claude 요금제가 필요합니다. Team 및 Enterprise 요금제에서는 먼저 소유자가 조직의 커넥터 설정에서 커넥터를 추가한 다음, 각 구성원이 자신의 ThunderPhone 계정을 연결합니다.

### ChatGPT

1. ChatGPT 앱 디렉터리에 ThunderPhone이 표시되면 선택하고 연결합니다.
2. 그렇지 않으면 **설정 → 앱 및 커넥터 → 고급 설정**을 열고 **개발자 모드**를 켠 다음, URL `https://api.thunderphone.com/v1/mcp` 및 OAuth 인증으로 커넥터를 만듭니다.
3. ThunderPhone에 로그인하고 조직을 선택한 다음 권한을 승인합니다. 도구 메뉴에서 ThunderPhone을 채팅에 추가합니다.

에이전트 또는 전화번호 삭제, 초안 폐기, 캠페인 시작, 외부 시스템에 쓸 수 있는 테스트 요청 전송은 어느 앱에서든 두 번째 확인을 요구합니다. [파괴적 작업 확인](#confirming-destructive-actions)을 참조하세요.

### Claude Code

```bash
claude mcp add --transport http thunderphone https://api.thunderphone.com/v1/mcp \
  --header "Authorization: Bearer $THUNDERPHONE_API_KEY"
```

### Codex

다음을 `~/.codex/config.toml`에 추가합니다.

```toml
[mcp_servers.thunderphone]
url = "https://api.thunderphone.com/v1/mcp"
bearer_token_env_var = "THUNDERPHONE_API_KEY"
```

### Cursor

`.cursor/mcp.json`을 만듭니다.

```json
{
  "mcpServers": {
    "thunderphone": {
      "url": "https://api.thunderphone.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:THUNDERPHONE_API_KEY}"
      }
    }
  }
}
```

### Claude Desktop

Claude Desktop 구성에 `mcp-remote` 브리지를 추가합니다.

```json
{
  "mcpServers": {
    "thunderphone": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.thunderphone.com/v1/mcp",
        "--header",
        "Authorization: Bearer ${THUNDERPHONE_API_KEY}"
      ],
      "env": {
        "THUNDERPHONE_API_KEY": "sk_live_YOUR_API_KEY"
      }
    }
  }
}
```

### VS Code

`.vscode/mcp.json`을 만들고 VS Code의 입력 프롬프트를 통해 키를 입력합니다.

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "thunderphone-api-key",
      "description": "ThunderPhone organization API key",
      "password": true
    }
  ],
  "servers": {
    "thunderphone": {
      "type": "http",
      "url": "https://api.thunderphone.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${input:thunderphone-api-key}"
      }
    }
  }
}
```

## 도구

모든 도구에는 MCP 주석이 포함됩니다. 표에서 **R**은 읽기 전용, **D**는 삭제적 작업, **I**는 멱등성, **O**는 오픈 월드/네트워크 상호작용을 의미합니다. 대시는 힌트가 설정되지 않았음을 의미합니다.

### 연결

| 도구 | 주요 인수 | 주석 | 기능 |
| --- | --- | --- | --- |
| `get_connection_identity` | — | R, I | 자격 증명을 검증하고 조직 및 안전한 자격 증명 메타데이터를 반환합니다. |

### 에이전트

| 도구 | 주요 인수 | 주석 | 기능 |
| --- | --- | --- | --- |
| `list_agents` | — | R, I | 에이전트를 나열합니다. |
| `get_agent` | `agent_id` | R, I | 에이전트 하나를 가져옵니다. |
| `create_agent` | 에이전트 구성 | — | 에이전트를 생성합니다. |
| `update_agent` | `agent_id`, 변경된 필드 | D | 에이전트 초안의 필드를 준비하고, 초안에 있던 내용을 대체합니다. 확인 단계 없이 실행됩니다. `deploy_agent`를 실행할 때까지 배포된 에이전트는 변경되지 않으며, `discard_agent_draft`는 초안을 되돌립니다. |
| `deploy_agent` | `agent_id`, 선택 사항인 `if_updated_at` | D, I | 초안을 프로덕션으로 승격합니다. |
| `discard_agent_draft` | `agent_id`, 선택 사항인 `if_updated_at`, 두 번째 요청 시 `confirmation_token` | D, I | 준비된 변경 사항을 폐기합니다. 2단계 작업입니다. [파괴적 작업 확인](#confirming-destructive-actions)을 참조하세요. |
| `duplicate_agent` | `agent_id`, 선택 사항인 `name` | — | 조직 내에서 에이전트를 복사합니다. |
| `delete_agent` | `agent_id`, 두 번째 요청 시 `confirmation_token` | D, I | 에이전트를 영구 삭제합니다. 2단계 작업입니다. |
| `list_agent_versions` | `agent_id` | R, I | 배포된 구성 버전을 나열합니다. |

### 전화번호 및 통신사

| 도구 | 주요 인수 | 주석 | 기능 |
| --- | --- | --- | --- |
| `list_phone_numbers` | — | R, I | 조직의 번호와 라우팅을 나열합니다. |
| `get_phone_number_limits` | — | R, I | 관리 번호 사용량과 한도를 가져옵니다. |
| `provision_phone_number` | 선택 사항 `area_code`, `city`, `state`, `idempotency_key` | D, O | ThunderPhone에서 관리하는 수신 번호를 구매합니다. |
| `list_voip_connections` | — | R, I | 연결된 고객 통신사를 나열합니다. |
| `search_voip_numbers` | `connection_id`, `country`, `type`, 선택 사항 `area_code` | R, I, O | 통신사 번호 인벤토리를 검색합니다. |
| `import_voip_numbers` | `connection_id`, `numbers` | D, O | 통신사에서 이미 소유한 번호를 가져옵니다. |
| `update_phone_number` | `phone_number_id`, 라우팅/라벨/웹훅 필드 | D | 에이전트 할당을 포함하여 번호 라우팅을 업데이트합니다. |
| `delete_phone_number` | `phone_number_id`, `confirm`, 선택 사항 `release_at_provider`, 두 번째 요청의 `confirmation_token` | D, I, O | 번호를 해제합니다. 두 단계로 진행됩니다. |

### SMS

| 도구 | 주요 인수 | 주석 | 기능 |
| --- | --- | --- | --- |
| `send_sms` | `from_number`, `to`, `body`, `idempotency_key` | D, I, O | 연결된 Twilio 또는 Telnyx 번호를 통해 일반 텍스트 SMS 한 건을 전송합니다. |

### 통화

| 도구 | 주요 인수 | 주석 | 기능 |
| --- | --- | --- | --- |
| `list_calls` | 선택적 필터, `limit`, `offset` | R, I | REST 통화 기록 필터로 통화를 나열합니다. |
| `get_call` | `call_id` | R, I | 통화 상태와 메타데이터를 가져옵니다. |
| `get_call_transcript` | `call_id`, 선택적 `live` | R, I | 통화 기록을 가져옵니다. |
| `get_call_audio_url` | `call_id`, 선택적 `download` | R, I, O | 서명된 오디오 URL을 반환합니다. MCP를 통해 오디오를 스트리밍하지 않습니다. |
| `get_call_grade` | `call_id` | R, I | 최신 통화 평가를 가져옵니다. |
| `place_call` | `agent_id`, `from_number`, `to_number` | D, O | 멱등성이 보장되지 않는 발신 통화 하나를 연결합니다. |
| `export_calls` | 통화 필터, `export_format` | R, I | REST 엔드포인트의 최대 한도까지 JSON 또는 CSV로 내보냅니다. |

### 테스트 및 검증

| 도구 | 주요 인수 | 주석 | 기능 |
| --- | --- | --- | --- |
| `list_test_scenarios` | `agent_id` | R, I | 테스트 시나리오를 나열합니다. |
| `create_test_scenario` | `agent_id`, `title`, `scenario_prompt`, 선택적 조건 | — | 시나리오를 생성합니다. |
| `generate_test_scenarios` | `agent_id`, 선택적 `count`, `include_edge_cases`, `locale` | O | 에이전트 프롬프트에서 시나리오를 생성합니다. |
| `run_agent_tests` | `agent_id`, `channel`, `consent_to_charge`, 선택적 선택 항목/매트릭스 | D, O | 웹 또는 전화 통화를 통해 시나리오를 실행합니다. |
| `get_test_run` | `agent_id`, `batch_id` | R, I | 배치 상태와 시나리오별 결과를 가져옵니다. |
| `list_validation_runs` | `agent_id` | R, I | 최근 초안 검증 실행을 나열합니다. |
| `get_validation_status` | `agent_id` | R, I | 최신 검증 상태와 초안 일치 여부를 가져옵니다. |

### 지식

| 도구 | 주요 인수 | 주석 | 기능 |
| --- | --- | --- | --- |
| `list_knowledge_bases` | — | R, I | 지식 베이스 목록을 반환합니다. |
| `create_knowledge_base` | `name`, 선택 사항 `description` | — | 지식 베이스를 생성합니다. |
| `add_knowledge_document` | `knowledge_base_id`, `name`, `content` | — | 텍스트 또는 Markdown을 추가합니다. |
| `import_knowledge_url` | `url`, 선택 사항 `name` | O | 안전한 수집을 위해 공개 페이지를 대기열에 추가합니다. |
| `search_knowledge` | `knowledge_base_id`, `query` | R, I | 프로덕션 검색을 통해 검색합니다. |

### 통합, 웹훅 및 원격 MCP 서버

| 도구 | 주요 인수 | 주석 | 기능 |
| --- | --- | --- | --- |
| `list_integrations` | — | R, I | HTTP 함수 통합을 나열합니다. |
| `create_integration` | `display_name`, 함수 `spec`, 선택적 엔드포인트 필드 | — | HTTP 도구를 생성합니다. 대시보드에서 인증 헤더를 추가합니다. |
| `test_integration` | `url`, 선택적 메서드/본문/시간 제한, `header_names`가 포함된 `integration_id`, 두 번째 요청의 `confirmation_token` | D, O | 제한되고 SSRF로 보호되는 테스트 요청을 보냅니다. 저장된 헤더 값은 통합에서 채워지며 해당 호스트로만 전송됩니다. `POST`(기본값), `PUT`, `PATCH`, `DELETE`는 2단계로 진행되며, `GET`은 즉시 실행됩니다. |
| `list_webhook_endpoints` | — | R, I | 서명된 웹훅 엔드포인트를 나열합니다. |
| `list_webhook_deliveries` | 선택적 `agent_id`, 선택적 `endpoint_id` | R, I | 페이로드 없이 최근 웹훅 전송 결과를 나열합니다. |
| `create_webhook_endpoint` | `label`, `url`, 선택적 이벤트/상태 | O | 서명된 웹훅 엔드포인트를 생성합니다. |
| `test_webhook_endpoint` | `endpoint_id` | O | 일반 전송을 통해 합성 이벤트를 보냅니다. |
| `list_mcp_servers` | — | R, I | 음성 에이전트가 호출할 수 있는 원격 서버를 나열합니다. |
| `create_mcp_server` | `display_name`, `url` | O | 원격 서버를 등록하고 동기화합니다. 인증 헤더가 필요한 서버는 대시보드에서 추가합니다. |
| `sync_mcp_server_tools` | `server_id` | D, O | 원격 서버의 도구 카탈로그를 새로 고칩니다. |

### 캠페인

| 도구 | 주요 인수 | 주석 | 기능 |
| --- | --- | --- | --- |
| `list_campaigns` | — | R, I | 발신 캠페인 목록을 반환합니다. |
| `create_campaign` | 캠페인 필드 | — | 초안 캠페인을 생성합니다. |
| `add_campaign_contacts` | `campaign_id`, `contacts` | — | 최대 5,000개의 JSON 연락처를 추가합니다. |
| `campaign_action` | `campaign_id`, `action`, 선택 사항 `consent_to_charge`, 두 번째 요청의 `confirmation_token` | D, O | `start`, `pause`, `resume` 또는 `stop`을 실행합니다. `start` 및 `resume`은 2단계 작업이며, `pause` 및 `stop`은 즉시 실행됩니다. |
| `get_campaign_stats` | `campaign_id` | R, I | 카운터 및 최근 결과를 가져옵니다. |

### 음성, 청구 및 문서

| 도구 | 주요 인수 | 주석 | 기능 |
| --- | --- | --- | --- |
| `list_voices` | — | R, I | 음성과 지원 언어를 나열합니다. |
| `preview_voice` | `voice`, `language`, `text` | O | 샘플을 생성하고 서명된 URL을 반환합니다. |
| `list_voice_clones` | — | R, I | 사용자 지정 음성 복제를 나열합니다. |
| `get_billing_summary` | — | R, I | 잔액과 권위 있는 티어 가격을 가져옵니다. 결제 변경 기능은 노출되지 않습니다. |
| `search_docs` | `query`, 선택 사항 `limit` | R, I, O | 공개 문서 색인을 검색합니다. |
| `get_doc_page` | `path` | R, I, O | 공개 Markdown 문서 페이지 하나를 가져옵니다. |

모든 제품 도구는 공개 API와 동일한 REST 코드 경로를 사용합니다. 따라서 REST 검증, 조직 범위 지정, 역할, 청구 승인, 할당량, TCPA 확인, 제공업체 안전 조치 및 감사 동작이 변경 없이 적용됩니다.

## 파괴적 작업 확인

D로 표시된 도구는 항목을 변경하거나 삭제하거나 실제 사람에게 전화를 걸기 시작합니다. 되돌릴 수 없는 작업에는 두 번의 요청이 필요합니다. 첫 번째 요청은 아무것도 변경하지 않으며 다음을 반환합니다:

```json
{
  "status": "confirmation_required",
  "action": "Delete agent",
  "target": { "id": 195, "name": "Front Desk Receptionist" },
  "confirmation_token": "…",
  "expires_in_seconds": 600,
  "next_step": "…"
}
```

어시스턴트는 영향을 받는 항목을 사용자에게 보여 주고 승인을 요청합니다. 그런 다음 동일한 인수에 `confirmation_token`을 추가하여 요청을 반복합니다. 토큰은 10분 동안 유효하며 하나의 조직, 하나의 도구, 하나의 정확한 인수 집합에 적용되므로 에이전트 세 명을 삭제하려면 세 번의 확인이 필요합니다. `pause` 또는 `stop`을 사용하는 `campaign_action`은 이 단계를 건너뛰므로 실행 중인 캠페인은 항상 즉시 중지할 수 있습니다. `GET`을 사용하는 `test_integration`도 마찬가지입니다. 일부 D 도구는 D가 서버 측 확인이 아닌 해당 효과를 표시하므로 한 번의 요청으로 실행됩니다. `update_agent`는 초안에 있던 내용을 대체하고(`discard_agent_draft`는 이를 되돌림), `deploy_agent`는 라이브 구성을 대체하며, `update_phone_number`는 라이브 통화를 재연결하고, `sync_mcp_server_tools`는 원격 서버의 도구 카탈로그를 대체하며, `import_voip_numbers`는 번호를 통신사로 다시 연결하고, `run_agent_tests`는 크레딧을 사용할 수 있으며, `send_sms` 및 `place_call`은 실제 사람에게 연결되고(`place_call`은 자체 동의 확인을 유지함), `provision_phone_number`는 번호를 구매합니다. MCP 클라이언트는 여전히 이러한 작업의 승인을 요청할 수 있습니다.

## 시작 프롬프트

`prompts/list`는 재사용 가능한 다섯 가지 워크플로를 제공합니다:

- `create_inbound_receptionist`
- `run_agent_tests`
- `buy_and_attach_number`
- `review_low_grade_calls`
- `add_url_to_agent_knowledge`

나열된 프롬프트 이름과 선언된 인수를 사용하여 `prompts/get`을 호출하면 즉시 실행 가능한 사용자 메시지를 받을 수 있습니다.

## 리소스

`resources/list`는 공개 캐시 참조를 제공합니다.

| URI | 콘텐츠 |
| --- | --- |
| `thunderphone://docs/llms.txt` | 공개 문서 색인입니다. |
| `thunderphone://docs/quickstart` | 빠른 시작 Markdown입니다. |
| `thunderphone://pricing` | 현재 공개 가격 Markdown입니다. |

`resources/read`로 하나를 읽습니다. 공개 가져오기는 짧은 시간 제한, 2 MiB 제한 및 프로세스 내 10분 캐시를 사용합니다.

## 프로토콜 및 오류

서버는 `2025-06-18` 및 `2025-03-26` 프로토콜 버전을 지원합니다. 지원되는 클라이언트 버전을 에코하고, 그 외의 경우 `2025-06-18`을 선택합니다. `initialize`, `ping`, 도구, 프롬프트, 리소스 및 알림을 구현합니다. 알림은 `202 Accepted`를 반환합니다. 이 상태 비저장 서버는 SSE 리스너 또는 세션 삭제를 제공하지 않으므로 `GET` 및 `DELETE`는 `Allow: POST`와 함께 `405 Method Not Allowed`를 반환합니다.

도구 실패는 `isError: true`를 포함하는 성공적인 JSON-RPC 응답으로 유지됩니다. 해당 텍스트에는 짧은 문장 뒤에 JSON 블록이 포함됩니다.

```json
{
  "code": "insufficient_balance",
  "detail": "There is not enough prepaid balance.",
  "next_step": "Call get_billing_summary, add funds in Organization > Billing, then retry."
}
```

`place_call`에는 고유한 `outbound_tcpa_confirmation_required:` 접두사가 유지됩니다. 알 수 없는 JSON-RPC 메서드는 HTTP `200` 응답에서 `-32601`을 반환합니다. JSON-RPC 배치는 MCP `2025-06-18`에서 지원되지 않으며 명확한 `-32600` 잘못된 요청 오류를 반환합니다.