MCP Server

Model Context Protocol (MCP)은 AI 모델이 외부 도구 및 데이터 소스와 안전하게 상호작용할 수 있게 하는 Anthropic의 오픈 프로토콜입니다. BillionVerify는 HTTP Streamable Transport를 통해 AI 에이전트에 엔터프라이즈급 이메일 검증 기능을 제공하여 통합을 매우 간단하게 만듭니다.

AI 에이전트에 이메일 검증이 필요한 이유

현대 AI 에이전트의 사용 사례:

• Claude Code는 사용자 데이터를 처리할 때 이메일 주소를 검증해야 합니다
• OpenCode는 자동화된 워크플로우에서 이메일 유효성 검사가 필요합니다
• Gemini CLI 에이전트는 등록 데이터를 처리할 때 품질 보증이 필요합니다
• Codex 생성 코드에는 내장 이메일 검증 로직이 필요합니다
• 커스텀 AI 에이전트는 인간과 상호작용할 때 연락처 진위를 확인해야 합니다

BillionVerify MCP를 사용하면 모든 AI 에이전트가 HTTP Streamable Transport 표준을 통해 엔터프라이즈급 이메일 검증 서비스를 직접 호출할 수 있습니다 - 복잡한 설정이 필요 없습니다.

핵심 기능

1. 단일 이메일 실시간 검증

• 이메일 형식, 도메인, MX 레코드 검증
• 선택적 SMTP 연결 확인
• 일회용 이메일 감지
• 기업 vs 무료 이메일 식별
• 역할 기반 이메일 감지 (support@, noreply@ 등)
• 평균 응답 시간 < 2초

2. 대량 이메일 검증

• 한 번에 최대 50개 이메일 검증
• 효율성을 위한 병렬 처리
• 상세한 결과 및 통계

3. 스마트 캐싱 시스템

• 유효한 이메일 7일간 캐시
• 유효하지 않은 이메일 7일간 캐시
• 알 수 없는 상태 10분간 캐시
• 불필요한 반복 검증 감소

4. 정확한 크레딧 과금

• 유효한 이메일: 1 크레딧
• 유효하지 않은 이메일: 0 크레딧 (낭비 방지)
• 알 수 없는 상태: 0 크레딧 (자동 재시도)
• 실시간 잔액 조회

지원되는 AI 클라이언트

빠른 설정 (HTTP Transport - 권장)

가장 간단한 통합 방법 - npm 패키지 설치가 필요 없습니다!

1단계: API 키 받기

BillionVerify 대시보드를 방문하여 API 키를 생성하세요.

2단계: Claude Desktop 설정

설정 파일을 편집하세요:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "billionverify": {
      "command": "curl",
      "args": ["--stdio", "https://mcp.billionverify.com/mcp?api_key=YOUR_API_KEY"]
    }
  }
}

YOUR_API_KEY를 실제 API 키로 교체한 후 Claude Desktop을 재시작하세요.

그게 전부입니다! npm 설치도, 의존성도 필요 없습니다. curl은 모든 시스템에 기본 설치되어 있습니다. 이제 Claude가 이메일 검증 기능을 갖추었습니다.

3단계: 검증 시작

대화에서 간단히 물어보세요:

이 이메일을 검증해주세요: user@example.com

Claude가 자동으로 BillionVerify를 호출하고 상세한 결과를 반환합니다.

Claude Code 설정

Claude Code CLI의 경우 MCP 서버를 추가하세요:

claude mcp add billionverify -- curl --stdio "https://mcp.billionverify.com/mcp?api_key=YOUR_API_KEY"

또는 ~/.claude.json에 추가하세요:

{
  "mcpServers": {
    "billionverify": {
      "command": "curl",
      "args": ["--stdio", "https://mcp.billionverify.com/mcp?api_key=YOUR_API_KEY"]
    }
  }
}

OpenCode 설정

OpenCode의 경우 ~/.opencode/config.json에 설정하세요:

{
  "mcpServers": {
    "billionverify": {
      "command": "curl",
      "args": ["--stdio", "https://mcp.billionverify.com/mcp?api_key=YOUR_API_KEY"]
    }
  }
}

Gemini CLI 설정

Gemini CLI의 경우 설정에 추가하세요:

{
  "mcpServers": {
    "billionverify": {
      "command": "curl",
      "args": ["--stdio", "https://mcp.billionverify.com/mcp?api_key=YOUR_API_KEY"]
    }
  }
}

Cursor 설정

Cursor에서 Settings > MCP로 이동하여 추가하세요:

{
  "billionverify": {
    "command": "curl",
    "args": ["--stdio", "https://mcp.billionverify.com/mcp?api_key=YOUR_API_KEY"]
  }
}

NPX 방식 (대안)

npm 패키지 방식을 선호하는 경우:

{
  "mcpServers": {
    "billionverify": {
      "command": "npx",
      "args": ["-y", "@billionverify/mcp-server"],
      "env": {
        "BV_API_KEY": "your-api-key-here"
      }
    }
  }
}

사용 가능한 도구

verify_single_email

단일 이메일 주소를 종합적으로 검증합니다.

매개변수:

반환값:

{
  "email": "user@example.com",
  "status": "valid",
  "score": 1,
  "is_deliverable": true,
  "is_disposable": false,
  "is_catchall": false,
  "is_role": false,
  "is_free": true,
  "domain": "example.com",
  "mx_records": ["has_mx_records"],
  "smtp_check": true,
  "response_time": 2,
  "credits_used": 1
}

Claude에서의 사용 예:

"test@example.com이 유효한 이메일인지 확인해줘"

verify_batch_emails

여러 이메일 주소를 한 번에 검증합니다 (최대 50개).

매개변수:

반환값:

{
  "total_emails": 2,
  "valid_emails": 2,
  "invalid_emails": 0,
  "results": [...],
  "credits_used": 2,
  "process_time": 4
}

Claude에서의 사용 예:

"이 이메일들을 검증해줘: user1@example.com, user2@test.com, info@company.com"

get_account_balance

계정 크레딧 및 사용 통계를 확인합니다.

매개변수: 없음

반환값:

{
  "account_id": "acc_xxx",
  "credits_balance": 842740,
  "credits_consumed": 157260,
  "credits_added": 1000000,
  "last_updated": "2026-02-05T04:51:35Z"
}

Claude에서의 사용 예:

"검증 크레딧이 얼마나 남았나요?"

health_check

MCP 서버 상태를 확인합니다.

매개변수: 없음

반환값:

{
  "status": "healthy",
  "version": "2.1.0",
  "service": "billionverify-mcp",
  "mode": "api-proxy"
}

get_task_status

파일 검증 작업 진행 상황을 조회합니다.

매개변수:

반환값:

{
  "job_id": "job-uuid-xxxxx",
  "status": "completed",
  "progress": 100,
  "total_emails": 1000,
  "processed_emails": 1000,
  "valid_count": 850,
  "invalid_count": 100
}

Claude에서의 사용 예:

"파일 검증 작업 job-123의 상태가 어떻게 되나요?"

get_download_url

선택적 상태 필터를 사용하여 검증 결과 다운로드 링크를 가져옵니다.

매개변수:

Claude에서의 사용 예:

"job-123에서 유효한 이메일만 다운로드 링크를 줘"

create_webhook

검증 완료 알림을 받을 웹훅을 생성합니다.

매개변수:

반환값:

{
  "id": "webhook-uuid",
  "url": "https://your-server.com/webhook",
  "events": ["file.completed"],
  "secret": "hmac-secret-for-signature",
  "is_active": true
}

참고: secret은 생성 시에만 반환됩니다. 서명 검증을 위해 저장하세요.

Claude에서의 사용 예:

"파일 검증이 완료되면 알림을 받을 웹훅을 만들어줘"

list_webhooks

현재 계정의 모든 웹훅을 나열합니다.

매개변수: 없음

반환값:

{
  "total": 1,
  "webhooks": [
    {
      "id": "webhook-uuid",
      "url": "https://your-server.com/webhook",
      "events": ["file.completed"],
      "is_active": true
    }
  ]
}

Claude에서의 사용 예:

"내 설정된 웹훅들을 보여줘"

delete_webhook

특정 웹훅을 삭제합니다.

매개변수:

Claude에서의 사용 예:

"webhook-123 ID를 가진 웹훅을 삭제해줘"

사용 예제

기본 검증

사용자:

john@google.com을 검증해줘

Claude:

그 이메일 주소를 검증해드리겠습니다.

이메일 검증 결과

필드	값
이메일	john@google.com
상태	유효
전달 가능	예
일회용	아니요
점수	0.95

이 이메일은 유효하고 전달 가능합니다.

여러 이메일 검증

사용자:

이 이메일들을 확인해줘: john@google.com, test@mailinator.com, support@microsoft.com

Claude:

세 개의 이메일 주소를 모두 검증하겠습니다.

이메일	상태	참고
john@google.com	유효	전달 가능, 기업 이메일
test@mailinator.com	유효하지 않음	일회용 이메일, 거부 권장
support@microsoft.com	유효	역할 기반 주소, 공유될 수 있음

권장사항:

• john@google.com - 사용해도 안전
• test@mailinator.com - 임시 이메일, 권장하지 않음
• support@microsoft.com - 유효하지만 팀 수신함일 가능성 있음

개발자 워크플로우

사용자 (Claude Code에서):

.env.example 파일의 테스트 이메일들을 검증해줘

Claude:

파일을 읽고 발견된 이메일 주소들을 검증하겠습니다.

.env.example에서 3개의 이메일 주소를 찾았습니다:

• TEST_EMAIL=user@example.com
• ADMIN_EMAIL=admin@company.com
• SUPPORT_EMAIL=help@temp-mail.org

검증 결과:

이메일	상태
user@example.com	알 수 없음 (예제 도메인)
admin@company.com	유효
help@temp-mail.org	유효하지 않음 (일회용)

테스트용으로 실제 이메일 주소 사용을 권장합니다.

출력 형식

MCP 서버는 잘 포맷된 결과를 반환합니다:

## 이메일 검증 결과

**이메일:** test@example.com
**상태:** 유효
**신뢰도 점수:** 95.0%

### 세부 정보
| 확인 항목 | 결과 |
|-----------|------|
| 전달 가능 | 예 |
| 유효한 형식 | 예 |
| 유효한 도메인 | 예 |
| 유효한 MX | 예 |
| 일회용 | 아니요 |
| 역할 주소 | 아니요 |
| Catch-all | 아니요 |
| 무료 제공자 | 아니요 |

**사용된 크레딧:** 1

모범 사례

1. API 키 안전하게 저장

API 키를 하드코딩하지 마세요. 환경 변수를 사용하세요:

{
  "env": {
    "BV_API_KEY": "${BV_API_KEY}"
  }
}

2. 자연어 사용

MCP 서버는 다양한 표현을 이해합니다:

• "user@example.com 검증해줘"
• "test@company.com이 유효한 이메일인가요?"
• "이 이메일이 전달 가능한지 확인해줘: john@test.com"
• "이 이메일 주소들을 검증해줄 수 있나요?"

3. 가능하면 일괄 처리

여러 이메일의 경우 Claude에 함께 검증하도록 요청하면 효율적입니다:

"이 이메일들을 한 번에 검증해줘: email1@test.com, email2@test.com, email3@test.com"

문제 해결

MCP 서버를 찾을 수 없음

Claude가 BillionVerify 도구를 찾을 수 없다고 하면:

1. 설정 파일 경로 확인
2. JSON이 유효한지 확인
3. Claude Desktop을 완전히 재시작
4. API 키가 올바른지 확인

속도 제한 오류

속도 제한 오류가 표시되면:

1. "크레딧이 얼마나 남았나요?"로 남은 크레딧 확인
2. 잠시 기다렸다가 다시 시도
3. 더 높은 한도를 위해 플랜 업그레이드 고려

연결 문제

검증이 실패하면:

1. 인터넷 연결 확인
2. API 키가 유효한지 확인
3. 먼저 간단한 검증 시도

FAQ

API 키가 안전한가요?

예. API 키는 로컬 설정 파일에 저장되며 여러분의 기기에서 실행되는 MCP 서버에서만 사용됩니다. 제3자에게 전송되지 않습니다.

어떤 AI 클라이언트가 MCP를 지원하나요?

Claude Desktop, Claude Code, Cursor, Zed, Cline, Continue를 포함한 모든 MCP 호환 클라이언트가 작동합니다.

오프라인일 때 어떻게 되나요?

BillionVerify API에 연결할 수 없으면 도구는 오류 메시지를 반환합니다. 이는 Claude의 다른 기능에 영향을 주지 않습니다.

크레딧은 어떻게 작동하나요?

각 이메일 검증은 1개의 크레딧을 사용합니다. 대량 검증은 이메일당 1개의 크레딧을 사용합니다. check_credits 도구로 잔액을 확인하세요.

다음 단계