MCP Server

BillionVerify의 OAuth 보호 MCP 서버를 ChatGPT 및 다른 MCP 호환 AI 클라이언트에 연결하세요.

Model Context Protocol(MCP)은 AI 클라이언트가 공통 인터페이스를 통해 외부 도구를 호출할 수 있게 해주는 개방형 표준입니다. BillionVerify는 이메일 검증, 계정 리포트, 결과 다운로드, 웹훅 관리를 위한 호스팅형 MCP 서버를 Streamable HTTP 로 제공합니다.


MCP 서버 버전	`2.1.0`
엔드포인트	`https://mcp.billionverify.com/mcp`
인증 방식	OAuth 2.1 + Bearer 액세스 토큰
Protected Resource Metadata	`https://mcp.billionverify.com/.well-known/oauth-protected-resource`
사용 가능한 도구	11
사용 가능한 리소스	3

중요

BillionVerify MCP 서버는 ?api_key=... 쿼리 파라미터, API 키가 포함된 리소스 URI, api_key 도구 인자를 지원하지 않습니다.

예전에 curl --stdio "https://mcp.billionverify.com/mcp?api_key=..." 를 사용했다면, 그 방식은 더 이상 지원되지 않습니다. OAuth 를 지원하는 원격 MCP 클라이언트를 사용하세요. 클라이언트가 로컬 stdio + API 키만 지원한다면 MCP 대신 BillionVerify REST API 를 사용해야 합니다.

할 수 있는 일

단일 이메일 주소 검증
한 번의 배치 호출로 최대 50개 이메일 검증
계정 크레딧 잔액 확인
비동기 검증 작업 상태 추적
완료된 작업의 필터링된 다운로드 링크 생성
검증 이력과 집계 통계 조회
라이프사이클 알림용 웹훅 생성, 조회, 삭제

인증 방식

BillionVerify MCP 는 표준 원격 OAuth 흐름을 사용합니다.

MCP 클라이언트가 https://mcp.billionverify.com/.well-known/oauth-protected-resource 에서 protected resource metadata 를 찾습니다.
클라이언트가 공개된 authorization server metadata 를 자동으로 따릅니다.
BillionVerify 계정으로 로그인하고 요청된 스코프를 승인합니다.
이후 클라이언트가 Authorization: Bearer <access_token> 헤더와 함께 https://mcp.billionverify.com/mcp 를 호출합니다.

사용 가능한 스코프

Scope	용도
`billionverify.read`	잔액, 작업 상태, 이력, 통계, 다운로드 링크 조회
`billionverify.verify`	이메일 검증 도구 실행
`billionverify.webhooks`	웹훅 생성, 조회, 삭제

ChatGPT 에서 연결하기

ChatGPT 에서 BillionVerify 를 연결하려면 다음 원격 MCP 서버 URL 을 사용하세요.

https://mcp.billionverify.com/mcp

ChatGPT 는 protected resource metadata 를 자동으로 확인하고 BillionVerify 로그인 및 동의 화면으로 리디렉션한 뒤, 액세스 토큰으로 MCP 서버를 호출합니다.

연결 후에는 다음과 같이 요청할 수 있습니다.

Verify jane@company.com
Check my current BillionVerify credit balance
Show my recent verification history
Get a download link for only valid emails from job 36f68e67-ddcb-441a-a407-22f826e72443

다른 MCP 클라이언트에서 연결하기

다음 기능을 지원하는 모든 MCP 클라이언트는

Streamable HTTP 기반 원격 MCP
OAuth-protected resources
표준 Bearer 토큰 인증

동일한 엔드포인트에 연결할 수 있습니다.

https://mcp.billionverify.com/mcp

클라이언트의 원격 MCP 설정 흐름에서 위 URL 을 사용하세요. curl --stdio 로 감싸거나 URL 에 API 키를 붙이지 마세요.

REST API 를 써야 하는 경우

다음 경우에는 MCP 대신 BillionVerify REST API 를 사용하세요.

클라이언트가 로컬 stdio MCP 서버만 지원하는 경우
통합이 OAuth 대신 API 키에 의존하는 경우
MCP 클라이언트 없이 백엔드 간 자동화를 구축하는 경우

API 키는 BillionVerify REST API 에서는 계속 사용할 수 있습니다. 다만 더 이상 MCP 인증 모델의 일부는 아닙니다.

사용 가능한 도구

도구	Scope	설명
`health_check`	none	MCP 서버가 정상 동작 중인지 확인
`verify_single_email`	`billionverify.verify`	이메일 주소 1개 검증
`verify_batch_emails`	`billionverify.verify`	최대 50개의 이메일 주소 검증
`get_account_balance`	`billionverify.read`	현재 크레딧 잔액과 사용 요약 조회
`get_task_status`	`billionverify.read`	비동기 검증 작업 상태 조회
`get_download_url`	`billionverify.read`	완료된 작업의 필터된 결과 다운로드 URL 생성
`get_verification_history`	`billionverify.read`	인증된 계정의 검증 이력 목록 조회
`get_verification_stats`	`billionverify.read`	집계된 검증 통계 조회
`create_webhook`	`billionverify.webhooks`	검증 웹훅 생성
`list_webhooks`	`billionverify.webhooks`	설정된 웹훅 목록 조회
`delete_webhook`	`billionverify.webhooks`	ID 로 웹훅 삭제

사용 가능한 리소스

리소스 URI	Scope	설명
`billionverify://account/info`	`billionverify.read`	계정 수준의 크레딧 및 사용량 요약
`billionverify://history/summary`	`billionverify.read`	최근 검증 이력 요약
`billionverify://stats/verification`	`billionverify.read`	집계된 검증 통계

예시 프롬프트

단일 이메일 검증

Verify john@google.com

배치 검증

Verify these emails in one request: john@google.com, test@mailinator.com, support@microsoft.com

계정 잔액

How many BillionVerify credits do I have left?

검증 이력

Show my 20 most recent verification jobs

필터링된 결과 다운로드

Get a download link for only valid emails from job job-123

웹훅 관리

Create a webhook for file.completed and file.failed events at https://example.com/webhooks/billionverify

MCP 응답 예시

`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
}

`get_task_status`

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

`get_account_balance`

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

문제 해결

`401`, OAuth 프롬프트 또는 `mcp/www_authenticate` 가 표시됩니다

대개 클라이언트가 아직 OAuth 승인을 완료하지 않았거나, 액세스 토큰이 만료되었거나, 필요한 스코프가 빠졌다는 의미입니다. MCP 서버를 다시 연결하고 요청된 스코프를 승인하세요.

클라이언트가 `curl --stdio` 또는 API 키가 들어간 로컬 JSON 설정만 지원합니다

그 클라이언트는 BillionVerify 의 현재 원격 MCP 인증 모델과 호환되지 않습니다. 대신 BillionVerify REST API 를 사용하세요.

예전에는 `?api_key=...` 로 연결했는데 지금은 동작하지 않습니다

그 레거시 흐름은 MCP 표면에서 제거되었습니다. OAuth 를 지원하는 MCP 클라이언트로 전환하고 원격 엔드포인트에 직접 연결하세요.

크레딧은 어떻게 계산되나요?

유효한 이메일: 1 크레딧
유효하지 않은 이메일: 0 크레딧
알 수 없는 이메일: 0 크레딧

남은 잔액은 get_account_balance 로 확인하세요.