MCP Server

Model Context Protocol (MCP) — это открытый стандарт, который позволяет AI-клиентам вызывать внешние инструменты через общий интерфейс. BillionVerify предоставляет размещенный MCP-сервер для проверки email, отчетности по аккаунту, загрузки результатов и управления вебхуками через Streamable HTTP.

Важно

MCP-сервер BillionVerify не поддерживает query-параметры ?api_key=..., resource URI со встроенным API key и аргументы инструментов api_key.

Если вы раньше использовали curl --stdio "https://mcp.billionverify.com/mcp?api_key=...", этот путь больше не поддерживается. Используйте remote MCP-клиент с поддержкой OAuth. Если ваш клиент работает только с локальным stdio + API key, используйте REST API BillionVerify вместо MCP.

Что можно делать

• Проверять один email-адрес
• Проверять до 50 email-адресов одним batch-запросом
• Получать текущий баланс кредитов аккаунта
• Отслеживать статус асинхронных задач проверки
• Генерировать отфильтрованные ссылки на скачивание результатов
• Смотреть историю проверок и агрегированную статистику
• Создавать, просматривать и удалять вебхуки для уведомлений

Как работает аутентификация

BillionVerify MCP использует стандартный remote OAuth flow:

1. Ваш MCP-клиент обнаруживает protected resource metadata по адресу https://mcp.billionverify.com/.well-known/oauth-protected-resource.
2. Клиент автоматически следует опубликованным metadata authorization server.
3. Вы входите в свой аккаунт BillionVerify и подтверждаете запрошенные scopes.
4. Затем клиент вызывает https://mcp.billionverify.com/mcp с заголовком Authorization: Bearer <access_token>.

Доступные scopes

Подключение из ChatGPT

Если вы подключаете BillionVerify из ChatGPT, используйте этот URL remote MCP server:

https://mcp.billionverify.com/mcp

ChatGPT автоматически обнаружит protected resource metadata, перенаправит вас на вход и consent BillionVerify, а затем начнет вызывать MCP-сервер с access token.

После подключения вы можете просить, например:

• 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-клиент, который поддерживает:

• remote MCP поверх Streamable HTTP
• OAuth-protected resources
• стандартную Bearer token authentication

может подключиться к тому же endpoint:

https://mcp.billionverify.com/mcp

Используйте remote MCP flow вашего клиента и укажите URL выше. Не оборачивайте сервер через curl --stdio и не добавляйте API key в URL.

Когда вместо этого использовать REST API

Используйте BillionVerify REST API вместо MCP, если:

• ваш клиент поддерживает только локальные stdio MCP-серверы
• ваша интеграция зависит от API keys, а не от OAuth
• вы строите backend-to-backend автоматизацию без MCP-клиента

API keys по-прежнему существуют для BillionVerify REST API. Они просто больше не являются частью модели аутентификации MCP.

Доступные инструменты

Доступные ресурсы

Примеры промптов

Проверка одного email

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 prompt или mcp/www_authenticate

Обычно это означает, что клиент еще не завершил OAuth authorization, срок действия access token истек или отсутствует нужный scope. Подключите MCP-сервер заново и подтвердите требуемые scopes.

Мой клиент поддерживает только curl --stdio или локальный JSON с API keys

Такой клиент несовместим с текущей моделью remote MCP authentication BillionVerify. Используйте BillionVerify REST API.

Раньше я подключался через ?api_key=..., а теперь это не работает

Этот legacy flow был удален из MCP surface. Перейдите на OAuth-совместимый MCP-клиент и подключайтесь напрямую к remote endpoint.

Как работают кредиты?

• Валидный email: 1 кредит
• Невалидный email: 0 кредитов
• Неизвестный email: 0 кредитов

Используйте get_account_balance, чтобы проверить оставшийся баланс.

FAQ

MCP-сервер поддерживает API keys?

Нет. Remote MCP-server требует OAuth access tokens. API keys разработчика предназначены для REST API, а не для инициализации MCP-подключения.

Какие клиенты поддерживаются?

Подключиться может любой клиент, который поддерживает remote MCP через Streamable HTTP и OAuth-protected resources. ChatGPT — один из примеров. Для клиентов без remote OAuth MCP support используйте REST API.

Нужно ли устанавливать npm-пакет?

Нет. Это размещенный remote MCP-server. Вы подключаетесь напрямую к https://mcp.billionverify.com/mcp.

Можно ли получать историю и статистику через MCP?

Да. Используйте get_verification_history, get_verification_stats или соответствующие read-only resources.

Что дальше