Open in

ThunderPhone을 MCP 서버로 사용하기

Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code 또는 다른 Streamable HTTP MCP 클라이언트에서 ThunderPhone 음성 에이전트를 구축, 테스트, 검증 및 운영합니다.

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

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

이는 원격 MCP 서버를 음성 에이전트에 연결하는 것과 반대 방향입니다.

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

인증

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

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

CLI 및 stdio 대안

ThunderPhone CLI는 관련 없는 서버를 유지하면서 클라이언트 구성을 작성할 수 있습니다.

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로 로그인하며 API 키는 사용하지 않습니다. 아직 ThunderPhone 계정이 없다면 로그인 페이지에서 계정 만들기를 선택하세요. 이메일 인증 후 승인 화면으로 돌아갑니다.

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

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

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

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

ChatGPT

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

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

Claude Code

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

Codex

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

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

Cursor

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

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

Claude Desktop

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

{
  "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의 입력 프롬프트를 통해 키를 입력합니다.

{
  "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단계 작업입니다. 파괴적 작업 확인을 참조하세요.
`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로 표시된 도구는 항목을 변경하거나 삭제하거나 실제 사람에게 전화를 걸기 시작합니다. 되돌릴 수 없는 작업에는 두 번의 요청이 필요합니다. 첫 번째 요청은 아무것도 변경하지 않으며 다음을 반환합니다:

{
  "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 블록이 포함됩니다.

{
  "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 잘못된 요청 오류를 반환합니다.