임시 이메일을 위한 MCP 서버 구축 — AI 에이전트가 이메일 인증을 처리하는 방법

문제점
AI 에이전트 (AI agent)를 사용하여 가입 프로세스 (signup flow)를 자동화하려고 시도해 본 적이 있다면, 다음과 같은 벽에 부딪혔을 것입니다: 서비스가 인증 이메일을 보내지만, 에이전트는 이를 읽을 방법이 없습니다. 에이전트는 양식을 채우고, 버튼을 클릭하고, 페이지를 탐색할 수 있습니다. 하지만 프로세스에서 "인증 코드를 확인하기 위해 이메일을 확인하세요"라고 말하는 순간, 에이전트는 멈춰버립니다. 수동으로 처리하거나, 테스트 이메일을 하드코딩하거나, 테스트 환경에서 이메일 인증을 완전히 건너뛰어야 합니다. 에이전트가 자율적으로 작동하기를 원할 때 이 중 어떤 옵션도 제대로 작동하지 않습니다.

MCP가 제공하는 것
모델 컨텍스트 프로토콜 (Model Context Protocol, MCP)은 AI 에이전트가 외부 도구 (external tools)를 호출할 수 있게 해주는 개방형 표준입니다. 에이전트가 추측하거나 환각 (hallucination)을 일으키는 대신, 구조화된 인터페이스를 통해 실제 API를 호출할 수 있습니다. 저는 무료 임시 이메일 서비스인 GoneBox를 위한 MCP 서버를 구축하여, AI 에이전트가 다음과 같은 작업을 수행할 수 있도록 했습니다:

• 즉석에서 일회용 편지함 (disposable inbox) 생성
• 이메일 도착 대기
• 인증 코드 또는 확인 링크 추출
• 작업 후 자체 정리

이 모든 과정은 별도의 커스텀 통합 코드 없이 표준 MCP 도구 호출을 통해 이루어집니다.

설정
claude_desktop_config.json 파일에 서버를 추가하세요:

{ "mcpServers" : { "gonebox" : { "command" : "npx" , "args" : [ "@gonebox/mcp-server" ], "env" : { "GONEBOX_API_URL" : "https://api.gonebox.email" , "GONEBOX_API_KEY" : "your-api-key-here" } } } }

동일한 설정이 Cursor (.cursor/mcp.json) 및 Windsurf에서도 작동합니다. 그게 전부입니다. 클라이언트를 재시작하면 에이전트가 사용할 수 있는 7개의 새로운 도구가 생깁니다.

도구

도구	기능
create_inbox	임시 이메일 주소 생성 (랜덤 또는 사용자 지정 사용자 이름)
list_messages	편지함의 모든 메시지 목록 표시
read_message	특정 이메일의 전체 내용 읽기
wait_for_email	새로운 이메일이 도착할 때까지 폴링 (선택적 제목 필터 포함)
delete_inbox	편지함 및 모든 메시지를 영구적으로 삭제
extract_verification_code	최신 이메일에서 4~8자리의 OTP 코드 찾기
extract_link	최신 이메일에서 인증/확인 URL 찾기

3가지 도메인 선택권을 제공합니다: gonebox.email, sumiu.email, nemexiste.email.

모두 동일한 방식으로 작동합니다. 실제 워크플로우: 이메일 인증

서비스에 가입할 때 실제 에이전트 상호작용은 다음과 같이 이루어집니다:

에이전트: 가입을 위해 임시 이메일을 생성하겠습니다.
→ create_inbox(domain: "gonebox.email" )
← { "email" : "kx7m2p@gonebox.email" , "expires_at" : "2026-05-20T15:30:00Z" }

에이전트: 이제 kx7m2p@gonebox.email로 가입 양식을 채우겠습니다...
[ 에이전트가 양식을 채움 ]

에이전트: 인증 이메일을 기다리는 중...
→ wait_for_email(address: "kx7m2p@gonebox.email" , subject_contains: "verify" , timeout_seconds: 60 )
← { "found" : true , "waited_seconds" : 8 , "message" : { "subject" : "Verify your account" , ... } }

에이전트: 확인했습니다. 코드를 추출하겠습니다.
→ extract_verification_code(address: "kx7m2p@gonebox.email" )
← { "found" : true , "code" : "482916" }

에이전트: 코드 482916을 입력합니다...
[ 에이전트가 코드를 입력함 ]

에이전트: 임시 편지함을 정리합니다.
→ delete_inbox(address: "kx7m2p@gonebox.email" )
← { "deleted" : true }

wait_for_email 도구는 3초마다 폴링(polling)하며, 설정 가능한 타임아웃(5~300초)을 지원합니다. 관련 없는 이메일과 매칭되는 것을 방지하기 위해 제목(subject)으로 필터링할 수 있습니다.

extract_verification_code 작동 방식

코드 추출은 단순히 문자열에 정규 표현식(regex)을 적용하는 것이 아닙니다. 다음과 같은 다중 전략(multi-strategy) 접근 방식을 사용합니다:

• 키워드 근접성 (Keyword proximity) — "code", "verify", "OTP", "PIN"과 같은 단어 근처의 숫자를 찾습니다.
• 역패턴 (Reverse pattern) — "482916 is your code"와 같은 형식을 포착합니다.
• 컨텍스트 윈도우 (Context window) — 독립적인 숫자 시퀀스의 경우, 80자 이내에 인증 키워드가 나타나는지 확인합니다.
• 폴백 (Fallback) — 이메일 내에서 처음 발견되는 독립적인 4~8자리 숫자를 선택합니다.

먼저 일반 텍스트(plain text) 본문을 검색한 다음, HTML로 폴백합니다. 영어 및 포르투갈어 이메일 템플릿에서 작동합니다.

extract_link 작동 방식

마찬가지로, extract_link는 인증 관련 경로 세그먼트를 포함하는 URL을 스캔합니다: verify, confirm, activate, reset, token, auth, magic-link, invitation 등이 포함됩니다.

특정 URL 패턴을 필터링하기 위해 link_contains를 전달할 수도 있습니다:

→ extract_link(address: "kx7m2p@gonebox.email" , link_contains: "reset-password" ) ←
{ "found" : true , "url" : "https://example.com/reset-password?token=abc123" }

REST API 직접 사용하기

MCP 서버는 GoneBox REST API를 얇게 감싼 래퍼 (wrapper)입니다. MCP를 사용하지 않는 무언가를 구축하고 있다면, API를 직접 호출할 수 있습니다:

# 편지함(inbox) 생성
curl -X POST https://api.gonebox.email/api/v1/inboxes \
 -H "Content-Type: application/json" \
 -d '{"domain": "gonebox.email"}'

# 메시지 목록 조회
curl https://api.gonebox.email/api/v1/inboxes/kx7m2p@gonebox.email/messages

# 메시지 읽기
curl https://api.gonebox.email/api/v1/messages/msg_abc123

# 편지함 삭제
curl -X DELETE https://api.gonebox.email/api/v1/inboxes/kx7m2p@gonebox.email

이 API는 Cloudflare Workers에서 실행되며, 전 세계적으로 100ms 미만의 응답 시간을 보장합니다.

아키텍처 (Architecture)

스택은 운영 비용을 저렴하게 유지하도록 설계되었습니다:

• 이메일 수집 (Email ingestion): Cloudflare Email Routing (3개 도메인에 대한 catch-all 설정)이 이메일을 Worker로 전달하며, Worker는 이메일을 파싱(parse), 정화(sanitize, DOMPurify 사용) 및 저장합니다.
• 저장소 (Storage): 5분마다 자동 TTL (Time To Live) 삭제 기능이 있는 Cloudflare D1 (에지(edge)에서의 SQLite)을 사용합니다.
• API: Cloudflare Workers 상의 Hono를 사용하며 KV 캐싱을 적용합니다.
• MCP 서버: TypeScript, @modelcontextprotocol/sdk, stdio 전송(transport) 방식을 사용하며, npm을 통해 배포됩니다.

편지함은 1시간 후에 자동 삭제됩니다. 회원가입도, 로그인도 필요 없으며, 개인 데이터는 저장되지 않습니다.

제한 사항 (What It Doesn't Do)

한계점에 대해 투명하게 공개합니다:

• 발신 이메일 불가 — GoneBox는 이메일을 받기만 합니다. 보낼 수는 없습니다.
• 첨부 파일 미지원 (현재 기준) — 저장 용량을 관리 가능한 수준으로 유지하기 위해 v1에서는 첨부 파일을 제거합니다.
• 무료 티어의 1시간 TTL — 편지함은 자동으로 만료됩니다.
• 속도 제한 (Rate limited) — API 키가 없으면 분당 60회 요청, IP당 분당 10개의 편지함 생성이 제한됩니다.

이것을 만든 이유

두 가지 이유가 있습니다. 첫째, AI 에이전트 워크플로우를 구축하던 중 이메일 인증이라는 벽에 계속 부딪혔습니다. 모든 임시 이메일 서비스에는 웹 UI가 있지만, MCP 서버를 제공하는 곳은 없었습니다. 둘째, MCP 생태계는 아직 초기 단계이기 때문입니다.

데이터베이스, 파일 시스템, 웹 검색을 위한 MCP 서버는 존재하지만, 이메일과 같은 기본 인프라는 빠져 있었습니다. 임시 이메일은 작업이 단순하고, 상태가 저장되지 않으며 (stateless), 설계상 데이터가 휘발성 (ephemeral)이기 때문에 MCP에 매우 적합합니다.

웹사이트 체험하기: gonebox.email
API 문서: gonebox.email/api-docs
MCP 서버: npx @gonebox/mcp-server
소스 코드: 이 MCP 서버는 MIT 라이선스를 따릅니다.

이메일이 포함된 AI 에이전트 워크플로 (AI agent workflows)를 구축하고 있다면, 한 번 시도해 보세요. MCP 서버를 설정하는 데는 약 30초 정도가 소요됩니다.