TrueDialog MCP

MCP(Model Context Protocol)는 AI 클라이언트가 실제 작업에 필요한 도구와 데이터에 접근하는 방식입니다. tdmcp는 MCP를 사용하는 모든 클라이언트와 TrueDialog SMS API 사이를 연결하는 기반입니다. 30년간 쌓아 온 통신사 인프라, 수신 거부 처리, 양방향 대화, RCS, MMS, 단축 번호 트래픽을 잘 정의된 소수의 도구로 제공합니다.

인증에는 자격 증명을 붙여 넣는 방식이 아니라 OAuth 2.1을 사용합니다. 브라우저에서 한 번만 auth.tdmcp.com을 통해 권한을 부여하면 됩니다. 포털에서 사용하는 것과 동일한 TrueDialog 계정으로 로그인하세요. AI 클라이언트에는 수명이 짧은 bearer 토큰만 저장되며 비밀번호는 저장되지 않습니다. 클라이언트는 각 호출에 토큰을 함께 보냅니다. 커넥터는 토큰을 검증하고 비공개 백채널을 통해 서버 측에서 TrueDialog 액세스 권한을 확인합니다. 클라이언트 설정에는 장기간 유효한 정보가 저장되지 않습니다.

런타임은 의도적으로 단순합니다. 관리형 프런트 도어 뒤의 Azure Container Apps, AMD64 컨테이너, Streamable HTTP를 제공하는 FastMCP, 고정 세션 없음. 전체 인프라는 Terraform으로 관리합니다. 예상 밖의 요소도, 직접 추가하지 않은 핫 패스의 요소도 없습니다.

---

엔드포인트: https://connect.tdmcp.com. 상태 비저장 Streamable HTTP입니다. 동일한 전송 방식은 https://connect.tdmcp.com/mcp에서도 응답합니다. /mcp 경로 규칙을 가정하는 클라이언트를 위한 호환 별칭이며, 두 URL 모두 사용할 수 있습니다. 인증에는 OAuth 2.1을 사용합니다. 클라이언트가 자동으로 검색하고 브라우저 로그인 과정을 안내합니다. 붙여 넣을 키나 헤더는 없습니다.

권한 부여 방식

아래의 모든 클라이언트는 동일한 네 단계를 따르며, 대부분은 자동으로 진행됩니다.

1. 클라이언트에 connect.tdmcp.com을 추가합니다.
2. 클라이언트가 auth.tdmcp.com에서 OAuth 서버를 찾아 자동으로 등록합니다(동적 클라이언트 등록, PKCE).
3. 브라우저 창이 열립니다. TrueDialog 자격 증명으로 로그인합니다.
4. 클라이언트가 토큰을 받으면 연결이 완료됩니다. 토큰은 자동으로 갱신되므로 세션이 만료될 때까지 다시 로그인할 필요가 없습니다.

Claude(Desktop 앱 또는 claude.ai)에서 Customize → Connectors를 열고 + → Add custom connector를 클릭합니다. 이름과 엔드포인트 URL을 입력합니다.

커스텀 커넥터 추가

Name:   TrueDialog
URL:    https://connect.tdmcp.com/

Add를 클릭한 다음 Connect를 클릭합니다. TrueDialog 로그인용 브라우저 창이 열립니다. 승인을 마치면 9개의 도구가 표시됩니다. Claude가 OAuth 서버에 자동으로 등록되므로 붙여 넣을 내용은 없습니다. Team/Enterprise에서는 먼저 Owner가 조직에 커넥터를 활성화해야 합니다(Organization settings → Connectors → Add → Custom → Web). 그러면 각 구성원이 Customize → Connectors에서 커넥터를 추가할 수 있습니다.

---

각 MCP 도구는 특정 TrueDialog API 영역에 대응합니다. 도구는 의도적으로 작고 명확하게 구성했습니다. 에이전트의 추론은 도구 목록이 아니라 프롬프트에서 이루어집니다. 도구는 총 9개이며, 읽기 전용 6개와 쓰기 작업 3개입니다.

1. whoami
   인증된 세션의 사용자와 계정을 반환합니다. 한 번 호출해 인증 상태를 확인할 때 유용합니다. 읽기 전용입니다.
2. list_accounts
   로그인 계정에서 볼 수 있는 모든 계정을 나열합니다. 여러 테넌트를 운영하는 사용자에게 유용하며, 단일 계정 사용자에게는 해당하지 않습니다. 읽기 전용입니다.
3. get_account_info
   단일 계정 레코드를 가져옵니다. 기본값은 인증된 계정입니다. 읽기 전용입니다.
4. list_channels
   계정의 채널(롱 코드, 단축 코드, RCS, 이메일, 음성)을 나열합니다. send_sms를 호출하기 전에 채널 ID를 확인할 때 사용합니다. 읽기 전용입니다.
5. get_contact
   ID로 연락처를 조회합니다. 읽기 전용입니다.
6. search_contacts
   전화번호와 이메일 주소에서 부분 문자열을 검색합니다. 읽기 전용입니다.
7. create_contact
   전화번호 또는 이메일로 연락처를 생성합니다(둘 중 하나 이상 필요). 해당 번호나 이메일이 이미 연락처에 있으면 TrueDialog가 생성을 거부하고 update_contact를 안내합니다. 중복 연락처를 조용히 만들지 않습니다.
8. update_contact
   연락처의 전화번호, 이메일 또는 이름을 업데이트합니다. 먼저 레코드를 읽고 전달된 필드만 다시 기록하므로, TrueDialog의 전체 덮어쓰기 방식 업데이트로 나머지 정보가 지워지지 않습니다. 읽기-수정-쓰기 방식이므로 manage 권한 외에 contact-read 권한도 필요하며, 동시에 발생하는 편집에 대해 원자적으로 처리되지는 않습니다. 쓰기 작업입니다.
9. send_sms
   하나 이상의 번호로 SMS를 발송합니다. 실제 발송이며, 기본적으로 실제 휴대전화에 메시지가 전달됩니다(테스트 실행에는 execute=false을 전달하세요). 발신 채널을 지정하지 않으면 자동으로 확인합니다. 단방향이며 답장을 읽지는 않습니다.

대화해 보세요.

도구 이름을 직접 호출할 필요는 없습니다. 요청만 하면 에이전트가 적절한 도구를 선택합니다. 연결한 뒤 다음과 같이 시도해 보세요.

• “어떤 계정으로 연결되어 있나요?” 인증을 확인합니다.
• “내 계정에는 어떤 채널이 설정되어 있나요?” 채널을 조회합니다.
• “+1 512 555 0142로 문자 보내 줘: 오후 7시에 4인 테이블 예약이 확인되었습니다.” 한 명에게 메시지 한 건을 보냅니다.
• “512 555 0142의 연락처를 찾아 주문이 발송되었다고 알려 줘.” 연락처를 조회하고 메시지를 보냅니다.

---

파일은 이메일 도구를 통해 전송됩니다. inbox_send_message와 inbox_reply_to_message는 각각 attachments 목록을 받습니다. inbox_forward_message는 원본 파일을 그대로 포함합니다(include_attachments, 기본값은 켜짐). attachments 목록의 각 항목은 정확히 하나의 바이트 소스를 지정합니다. 어떤 소스를 선택하느냐에 따라 파일이 도착할 수도, 도착하지 않을 수도 있습니다.

이 도구들은 배포별로 활성화되는 Inbox 팩에 속합니다. 현재 connect.tdmcp.com의 커넥터는 위의 TrueDialog 도구 9개를 제공합니다. Inbox 팩이 활성화된 곳에서는 이메일 도구와 함께 첨부 파일 기능도 제공됩니다.

1. attachment_id
   이 받은 편지함의 메시지에 플랫폼이 이미 보관 중인 첨부 파일을 지정합니다. ID는 inbox_get_thread에서 가져옵니다. 서버가 저장된 바이트를 직접 다시 첨부하므로 모델을 통해 base64를 전달할 필요가 없습니다. 아주 작은 파일이 아닌 경우에 적합하며, 답장할 스레드에 이미 바이트가 있는 경우 자연스러운 경로입니다. filename과 content_type은 저장된 바이트에서 상속되며 재정의할 수 있습니다. 전사 한도는 없애지만 크기 제한은 그대로 적용됩니다. (전달에는 이 항목조차 필요하지 않습니다. inbox_forward_message는 기본적으로 원본 첨부 파일을 포함합니다.)
2. upload_id
   스토리지에 이미 준비된 바이트를 지정합니다. 새 대용량 파일을 보낼 때 사용하는 경로입니다. 파일 이름, MIME 유형, 정확한 바이트 길이를 지정해 /v1/inboxes/{inbox_id}/attachments/uploads에 POST합니다. 반환된 사전 서명 upload_url에 원시 바이트를 PUT한 다음, 전송 요청에 upload_id를 지정합니다. Inbox 팩이 활성화된 곳에서는 inbox_create_attachment_upload가 첫 단계를 수행하고 upload_id와 upload_url을 반환합니다. PUT을 수행하는 도구는 없으므로, 이 커넥터만 사용할 수 있는 에이전트는 새 바이트를 준비할 수 없습니다. 업로드는 클라이언트나 앱에서 별도로 PUT해야 합니다.
3. content
   filename과 content_type을 지정해 base64를 인라인으로 전달합니다. 아주 작은 파일에서만 안정적으로 작동합니다. 대략 2 KB, base64 문자 약 2,700자 정도입니다. 도구 호출에서 전체 문자열을 문자 단위로 정확히 출력해야 하며, 문자 하나만 잘못되어도 불투명한 base64 패딩 오류와 함께 전송이 실패하기 때문입니다. 이는 신뢰성 한계이지 검증된 제한은 아닙니다. 2 KB에서 요청이 거부되지는 않습니다. 전송은 접수되지만 디코딩 중 나중에 실패합니다.

서버에서 적용하는 제한

서버 측에서 확인하는 제한은 세 가지입니다.

1. 메시지당 10 MB. 형식과 관계없이 모든 항목의 크기를 합산합니다. 참조된 바이트도 인라인 바이트와 동일하게 전체 크기가 계산됩니다. 참조를 사용하면 파일을 직접 전사하지 않아도 되지만 파일 크기가 줄어드는 것은 아닙니다.
2. 파일당 10 MB. 업로드 슬롯을 생성할 때 선언된 size_bytes에 적용되므로, 크기 초과 객체를 저장할 수 있는 URL은 발급되지 않습니다.
3. attachments 목록당 항목 100개.

총 크기는 바이트를 가져오기 전에 저장된 메타데이터를 기준으로 확인하고, 모든 항목을 확인한 뒤 다시 검사합니다. 따라서 제한을 초과하는 전송은 일부만 전달되는 대신 422과 함께 거부됩니다. 어느 한 제한이라도 초과하는 파일 묶음은 여러 번의 전송으로 나누세요.

세 가지 형식은 하나의 목록에서 자유롭게 섞어 사용할 수 있습니다. 사전 서명 업로드 URL은 기본적으로 15분 동안 유효합니다. PUT은 서명에 포함된 Content-Type과 Content-Length를 전달받은 값 그대로 보내야 합니다. 업로드는 한 번만 사용할 수 있습니다. 해당 업로드를 참조하는 첫 번째 전송에서 소모됩니다. GET …/attachments/uploads/{upload_id}를 사용하면 슬롯이 아직 대기 중인지, 언제 만료되는지, 어떤 메시지에서 사용되었는지 확인할 수 있습니다. 하지만 PUT이 도착했는지는 확인하지 않습니다. 바이트가 준비되기 전에 전송하면 422과 함께 거부되며 업로드는 소모되지 않습니다. 따라서 PUT이 완료된 뒤 다시 시도할 수 있습니다. 반대 방향으로는 inbox_get_attachment가 첨부 파일의 바이트를 base64로 인코딩해 반환합니다.

---

MCP 서버는 진입점입니다. 흥미로운 제품 작업은 그 위에서 이루어집니다. SMS 대화를 성과로 이어 주는 에이전트 런타임입니다.

SMS 답장이 도착하면 전체 대화 맥락과 함께 적절한 에이전트를 실행합니다. 답장을 유발한 발신 메시지, 고객 이력, 대화의 목표를 모두 포함합니다. 에이전트를 위한 웹훅입니다.

분 단위가 아니라 목표를 판매하세요. 여러 차례에 걸친 예약 확인 및 일정 변경, 낮은 점수에 대한 NPS 후속 대화, B2B 리드 자격 확인, 지원 요청 분류. 에이전트가 대화를 처음부터 끝까지 처리합니다.

TrueDialog의 규정 준수 전문성을 답장 계층에 적용합니다. “밤에는 문자 보내지 마세요”라는 요청을 완전한 수신 거부가 아니라 조용한 시간대 설정으로 처리합니다. TCPA를 준수하는 감사 추적도 기본으로 제공됩니다.

고객 지원 담당자를 대체하지 말고 지원하세요. 담당자가 이미 사용하는 에이전트 콘솔에서 답장 초안, 대화 요약, 다음 최선의 조치를 제안합니다.

---

기술 스택

FastMCP / httpx / Python 3.14
Azure Container Apps / ACR / Static Web Apps / Azure DNS
Terraform / Docker

라이선스

MIT.

서체

Lato, JetBrains Mono.