# MCP 서버 (/docs/mcp)

## MCP 서버

한국AI통신은 [Model Context Protocol(MCP)](https://modelcontextprotocol.io) 호환 AI 에이전트가 바로 연결할 수 있는 **호스팅 MCP 서버**를 제공합니다.
연결하면 AI 에이전트가 자연어 요청만으로 070 번호를 발급하고, 전화를 걸고, 문자를 보내고, 통화 녹음·전사·요약을 확인합니다.

| 항목 | 값 |
| --- | --- |
| 서버 이름 | `kat` (KAT / 한국AI통신) |
| 서버 주소 | `https://api.koreaaitel.com/mcp` |
| 전송 방식 | Streamable HTTP |
| 인증 | OAuth 2.1 (브라우저에서 한국AI통신 계정으로 로그인 후 동의) |

로컬에 서버를 설치하거나 설정 파일에 API 키를 적을 필요가 없습니다.

## 연결하기

### Claude Code

터미널에서 서버를 추가합니다.

```bash
claude mcp add --transport http kat https://api.koreaaitel.com/mcp
```

Claude Code 에서 `/mcp` 를 입력하고 `kat` 을 고른 뒤 **Authenticate** 를 누르면 브라우저에서 로그인과 동의가 진행됩니다.
동의를 마치면 바로 자연어로 요청할 수 있습니다.

```text
내 전화번호 목록을 보여줘.
사용할 수 있는 070 번호를 하나 발급해줘.
마지막 통화를 전사하고 핵심 내용을 요약해줘.
```

### 다른 MCP 클라이언트

원격 MCP 서버(Streamable HTTP)와 OAuth 를 지원하는 클라이언트라면 같은 주소로 연결합니다.
서버가 `401` 응답의 `WWW-Authenticate` 헤더로 인증 서버 위치(`resource_metadata`)를 알려 주므로, 클라이언트가 로그인 화면을 자동으로 엽니다.

## 인증과 권한

처음 연결하면 동의 화면에 AI 에이전트가 쓸 권한 목록이 나옵니다. 권한은 조회(`read:`)와 변경(`write:`)으로 나뉘고,
**동의한 권한에 해당하는 도구만** AI 에이전트에게 보입니다.

`write:` 권한은 실제로 비용이 나가거나 되돌릴 수 없는 작업을 포함합니다 — 전화 발신, 문자 발송, 번호 발급·반납, 녹음 삭제, API 키 생성·폐기 등.
AI 에이전트가 이런 작업을 하기 전에 사용자에게 확인하도록 클라이언트의 도구 승인 설정을 켜 두기를 권합니다.

연결한 앱과 부여한 권한은 콘솔에서 확인하고 연결을 끊을 수 있습니다.

| 권한 | 내용 |
| --- | --- |
| `read:phone_numbers` · `write:phone_numbers` | 전화번호 조회 · 발급/해지 |
| `read:calls` · `write:calls` | 통화 내역 조회 · 발신/제어 |
| `read:messages` · `write:messages` | 메시지 내역 조회 · 발송 |
| `read:recordings` · `write:recordings` | 통화 녹음 조회 · 삭제 |
| `read:transcripts` · `write:transcripts` | 통화 전사 조회 · 전사 요청 |
| `read:agents` · `write:agents` | AI 에이전트 조회 · 생성/수정 |
| `read:call_flows` · `write:call_flows` | 콜 플로우(ARS) 조회 · 생성/수정/삭제 |
| `read:webhooks` · `write:webhooks` | 웹훅 구독 조회 · 생성/삭제 |
| `read:dictionaries` · `write:dictionaries` | 받아쓰기 사전 조회 · 생성/수정/삭제 |
| `read:blocked_recipients` · `write:blocked_recipients` | 수신거부 명단 조회 · 등록/해제 |
| `read:blocked_callers` · `write:blocked_callers` | 수신 통화 차단 목록 조회 · 등록/해제 |
| `read:sip_credentials` · `read:sip_endpoints` · `read:sip_tokens` · `write:sip_tokens` | SIP 단말·엔드포인트 조회, SIP 임시 토큰 발급/취소 |
| `read:assignment_links` · `write:assignment_links` | 관리번호 발급 링크 조회 · 생성/취소 |
| `read:api_keys` · `write:api_keys` | API 키 조회 · 생성/삭제 |
| `read:usage` | 사용량 집계 조회 |
| `read:ice_servers` | WebRTC ICE/TURN 서버 정보 조회 |

이 밖에 카카오 채널(`read/write:kakao_channels`), 알림톡 템플릿(`read/write:kakao_templates`), 이메일 발신 도메인(`read/write:email_domains`), 이메일 발송(`read/write:emails`),
증명서(`read/write:certificates`) 권한이 있습니다. 전체 목록은 서버의
[OAuth 보호 리소스 메타데이터](https://api.koreaaitel.com/.well-known/oauth-protected-resource/mcp)에서 확인할 수 있습니다.

## 도구 목록

AI 에이전트에게 보이는 도구는 동의한 권한과 계정 설정(예: 대표번호 부가서비스)에 따라 달라집니다.

### 전화 비서와 AI 에이전트

| 도구 | 하는 일 |
| --- | --- |
| `ensure_phone_assistant` | 대신 전화를 걸어 줄 전화 비서를 준비합니다(계정당 하나를 다시 씁니다) |
| `update_phone_assistant` | 전화 비서의 목소리를 바꿉니다 |
| `list_agent_voices` | 쓸 수 있는 한국어 음성과 계정의 복제 음성을 조회합니다 |
| `list_agents` · `get_agent` | AI 에이전트 목록 · 상세(프롬프트·모델·음성·실행 설정) |
| `create_agent` · `update_agent` · `delete_agent` | AI 에이전트 생성 · 수정 · 삭제 |

### 전화번호

| 도구 | 하는 일 |
| --- | --- |
| `list_phone_numbers` | 발급된 번호와 웹훅·라우팅 설정 조회 |
| `create_phone_number` | 070 번호 발급 |
| `create_representative_number` | 대표번호 발급(대표번호 부가서비스를 켠 계정) |
| `update_phone_number` | 번호의 받는 방식(웹훅·SIP·소프트폰·착신전환·콜 플로우·AI 에이전트) 변경 |
| `delete_phone_number` | 번호 반납 |
| `list_assignment_links` · `create_assignment_link` · `delete_assignment_link` | 관리번호 발급 링크 조회 · 생성 · 취소 |

### 전화

| 도구 | 하는 일 |
| --- | --- |
| `create_call` | 전화 발신 |
| `control_call` | 통화 제어(종료) |
| `list_calls` · `get_call` | 통화 목록 · 상세(상태·시간·종료 사유) |
| `list_call_events` | 통화 이벤트 타임라인 |
| `render_call_panel` | 통화 화면을 지원하는 클라이언트에 통화 상태 화면 표시 |
| `list_call_flows` · `get_call_flow` | 콜 플로우(ARS) 목록 · 상세 |
| `create_call_flow` · `update_call_flow` · `delete_call_flow` | 콜 플로우 생성 · 수정 · 삭제 |

### 통화 기록

| 도구 | 하는 일 |
| --- | --- |
| `get_recording` · `delete_recording` | 녹음 내려받기 링크(15분 유효) · 녹음 삭제(되돌릴 수 없음) |
| `trigger_transcript` · `get_transcript` | 전사 요청 · 전사 원문 조회 |
| `get_call_summary` | AI 통화 요약 조회 |
| `list_dictionaries` · `get_dictionary` | 받아쓰기 사전 목록 · 상세 |
| `create_dictionary` · `update_dictionary` · `delete_dictionary` | 사전 생성 · 수정 · 삭제 |
| `add_dictionary_term` · `update_dictionary_term` · `delete_dictionary_term` | 업무 용어 추가 · 수정 · 삭제 |

### 메시지

| 도구 | 하는 일 |
| --- | --- |
| `send_message` | SMS·LMS·MMS 또는 카카오 알림톡·브랜드 메시지 발송 |
| `list_messages` · `get_message` | 메시지 목록 · 상세 |
| `list_sender_numbers` · `register_sender_number` · `delete_sender_number` | 문자 발신번호 조회 · 등록 · 삭제 |

### 수신거부와 차단

| 도구 | 하는 일 |
| --- | --- |
| `list_blocked_recipients` · `get_blocked_recipient` | 수신거부(발신 금지) 명단 조회 |
| `create_blocked_recipient` · `update_blocked_recipient` · `release_blocked_recipient` | 수신거부 등록 · 메모 수정 · 해제 |
| `list_blocked_callers` · `get_blocked_caller` | 수신 통화 차단 목록 조회 |
| `create_blocked_caller` · `update_blocked_caller` · `release_blocked_caller` | 수신 통화 차단 등록 · 메모 수정 · 해제 |

### 연동과 계정

| 도구 | 하는 일 |
| --- | --- |
| `list_webhooks` · `create_webhook` · `delete_webhook` | 계정 웹훅 조회 · 등록 · 삭제 |
| `list_sip_credentials` · `get_sip_credential` | SIP 단말 조회 |
| `list_sip_endpoints` · `get_sip_endpoint` | SIP 엔드포인트(외부 PBX) 조회 |
| `create_sip_token` · `revoke_sip_token` | WebRTC 용 SIP 임시 토큰 발급 · 회수 |
| `get_ice_servers` | WebRTC STUN/TURN 정보 조회 |
| `list_api_keys` · `create_api_key` · `delete_api_key` | API 키 조회 · 생성 · 폐기 |
| `get_usage` | 통화·문자·전사·요약 사용량 집계 |

## 다음 단계

- [Voice Agent](/docs/voice-agent) — SDK 로 직접 만드는 음성 에이전트와, 에이전트에서 다른 MCP 서버를 쓰는 방법
- [웹훅](/docs/webhooks) — 통화·메시지 이벤트를 내 서버로 받기
- [API 레퍼런스](/docs/api-reference) — MCP 도구가 부르는 REST API 전체