MCP
AI 에이전트에 전화번호 연결
MCP 서버를 연결하면 에이전트가 번호를 받고, 전화를 걸고 받고, 문자를 보내고 받습니다. API 키 하나면 됩니다. MCP 도구와 REST API 가 같은 키, 같은 권한으로 움직입니다.
01
연결 정보
| 항목 | 값 |
|---|---|
| 주소 | https://studio-gateway.zerocall.kr/mcp |
| 전송 방식 | Streamable HTTP (세션 없음, JSON 응답) |
| 인증 | x-api-key 헤더에 API 키 |
| 메서드 | POST. GET · DELETE /mcp 는 405 를 돌려줍니다. |
API 키는 콘솔에서 발급합니다. 발급 방법은 빠른 시작 1단계를 보세요.
02
에이전트가 할 수 있는 일
번호 · 전화 · 문자를 모두 다룹니다. 같은 API 키로 MCP 도구와 REST API 를 함께 씁니다.
| 할 일 | 방법 |
|---|---|
| 번호 받기 | 가입 때 070 번호가 하나 생기고, 유료 요금제에서는 MCP 도구 issue_number 로 하나씩 더 받습니다. 번호 추가 |
| 전화 걸기 | MCP 도구 create_ai_outbound_call 로 AI 발신을 접수합니다. 도구 목록 |
| 전화 받기 | AI 상담원을 번호에 연결하면 그 번호로 오는 전화를 받습니다. 결과는 CALL_COMPLETED 웹훅으로 옵니다. 번호 연결 |
| 문자 보내기 | 채팅 API 로 SMS · LMS · MMS 를 보냅니다. 통화 중에는 상담원 문자 도구로 링크를 보낼 수 있습니다. 메시지 발송 |
| 문자 받기 | 고객이 보낸 문자는 MESSAGE_RECEIVED 웹훅으로 옵니다. 이벤트 목록 |
| 결과 받기 | 발신 결과는 get_ai_outbound_call 이나 AI_OUTBOUND 웹훅으로 받습니다. |
03
Claude Code
터미널에서 한 줄로 추가합니다. 추가한 뒤 Claude Code 안에서 /mcp 로 연결 상태를 확인합니다.
터미널
claude mcp add --transport http kat https://studio-gateway.zerocall.kr/mcp --header "x-api-key: <API 키>"04
Cursor
프로젝트의 .cursor/mcp.json 이나 사용자 설정의 mcp.json 에 넣습니다.
mcp.json
{
"mcpServers": {
"kat": {
"url": "https://studio-gateway.zerocall.kr/mcp",
"headers": {
"x-api-key": "<API 키>"
}
}
}
}05
ChatGPT · Gemini · GitHub Copilot · Windsurf
원격 MCP 서버를 추가하는 화면이나 설정 파일에 아래 네 가지를 넣습니다. 설정 파일의 키 이름은 클라이언트마다 다릅니다.
공통
이름 kat
전송 방식 Streamable HTTP
주소 https://studio-gateway.zerocall.kr/mcp
헤더 x-api-key: <API 키>| 클라이언트 | 넣는 곳 |
|---|---|
| GitHub Copilot (VS Code) | .vscode/mcp.json 의 servers. 아래 예시처럼 type 을 http 로 둡니다. |
| Windsurf | mcp_config.json 의 mcpServers. 주소 키는 serverUrl 입니다. |
| Gemini CLI | settings.json 의 mcpServers. 주소 키는 httpUrl 입니다. |
| ChatGPT | 원격 MCP 서버(커넥터) 추가 화면. x-api-key 헤더를 넣을 수 있는지 먼저 확인하세요. |
.vscode/mcp.json
{
"servers": {
"kat": {
"type": "http",
"url": "https://studio-gateway.zerocall.kr/mcp",
"headers": { "x-api-key": "<API 키>" }
}
}
}클라이언트 설정 형식은 각 제품이 바꿀 수 있습니다. 연결이 안 되면 그 제품의 원격 MCP 문서를 함께 확인하세요.
06
MCP 도구
지금 MCP 서버가 내놓는 도구는 다섯 개입니다. 각 도구는 같은 일을 하는 REST API 와 짝입니다.
| 도구 | 하는 일 | 같은 REST |
|---|---|---|
| list_outbound_agents | 발신 상담원(방향 OUTBOUND)과 등록 입력 스키마를 봅니다. | GET /group/{groupId}/agent?direction=OUTBOUND |
| create_ai_outbound_call | AI 발신을 접수합니다. idempotencyKey 가 필수입니다. 재시도할 때는 같은 값을 씁니다. | POST /group/{groupId}/ai-outbound/calls (Idempotency-Key) |
| get_ai_outbound_call | 통화 · 분석 · 정산 상태를 봅니다. | GET /group/{groupId}/ai-outbound/calls/{requestId} |
| list_ai_outbound_calls | 발신 목록을 봅니다. cursor · limit 으로 넘깁니다. | GET /group/{groupId}/ai-outbound/calls |
| terminate_ai_outbound_call | 아직 걸지 않은 발신은 취소하고, 진행 중인 통화는 종료를 요청합니다. | POST /group/{groupId}/ai-outbound/calls/{requestId}/termination |
- 도구마다
groupId를 받습니다. API 키에 그룹이 하나뿐이면 생략할 수 있습니다. - 권한 · 한도 · 멱등성 · 오류 코드는 REST 와 같습니다.
- 실패하면
isError결과에코드: 메시지형태로 옵니다. - 발신은 바로
requestId와 접수 상태를 돌려줍니다. 통화가 끝난 뒤 결과는get_ai_outbound_call이나 웹훅AI_OUTBOUND로 받습니다.
07
쓰기 전에
create_ai_outbound_call은 실제로 전화를 겁니다. 요금이 생길 수 있습니다. 클라이언트의 도구 승인 설정을 켜 두세요.- 재시도할 때는 같은
idempotencyKey를 씁니다. 새 값을 쓰면 새 전화로 접수됩니다. - API 키는 설정 파일에 그대로 들어갑니다. 설정 파일을 저장소에 올리지 마세요.
- 문자 발신 외 API 는 비즈니스 요금제 그룹이나 별도 허용된 그룹에서 씁니다. 사용 범위와 권한
- 01계정 만들기
- 02전화번호 발급
- 03에이전트 연결하고 첫 통화
