MCP Server

Das Model Context Protocol (MCP) ist ein offener Standard, mit dem KI-Clients externe Tools über eine gemeinsame Schnittstelle aufrufen können. BillionVerify stellt einen gehosteten MCP-Server für E-Mail-Verifizierung, Kontoberichte, Ergebnisdownloads und Webhook-Verwaltung über Streamable HTTP bereit.

Wichtig

Der BillionVerify MCP-Server unterstützt keine ?api_key=...-Query-Parameter, keine Ressourcen-URIs mit eingebettetem API-Schlüssel und keine api_key-Tool-Argumente.

Falls Sie früher curl --stdio "https://mcp.billionverify.com/mcp?api_key=..." verwendet haben, ist dieser Weg nicht mehr verfügbar. Nutzen Sie stattdessen einen OAuth-fähigen Remote-MCP-Client. Wenn Ihr Client nur lokales stdio + API-Schlüssel unterstützt, verwenden Sie bitte die BillionVerify-REST-API statt MCP.

Was Sie damit tun können

• Eine einzelne E-Mail-Adresse verifizieren
• Bis zu 50 E-Mail-Adressen in einem Batch prüfen
• Guthaben und Credits des Kontos abfragen
• Den Status asynchroner Verifizierungsjobs verfolgen
• Gefilterte Download-Links für abgeschlossene Jobs erzeugen
• Verifizierungshistorie und aggregierte Statistiken abrufen
• Webhooks für Lifecycle-Benachrichtigungen erstellen, auflisten und löschen

So funktioniert die Authentifizierung

BillionVerify MCP verwendet einen standardmäßigen Remote-OAuth-Flow:

1. Ihr MCP-Client entdeckt die Protected-Resource-Metadaten unter https://mcp.billionverify.com/.well-known/oauth-protected-resource.
2. Der Client folgt automatisch den angegebenen Metadaten des Authorization Servers.
3. Sie melden sich mit Ihrem BillionVerify-Konto an und bestätigen die angeforderten Scopes.
4. Anschließend ruft der Client https://mcp.billionverify.com/mcp mit Authorization: Bearer <access_token> auf.

Verfügbare Scopes

Verbindung über ChatGPT

Wenn Sie BillionVerify in ChatGPT verbinden, verwenden Sie diese Remote-MCP-URL:

https://mcp.billionverify.com/mcp

ChatGPT entdeckt die OAuth-geschützten Ressourcen automatisch, leitet Sie zur BillionVerify-Anmeldung und Einwilligung weiter und ruft danach den MCP-Server mit einem Access Token auf.

Nach erfolgreicher Verbindung können Sie zum Beispiel Folgendes fragen:

• 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

Verbindung aus anderen MCP-Clients

Jeder MCP-Client, der Folgendes unterstützt,

• Remote-MCP über Streamable HTTP
• OAuth-protected resources
• standardisierte Bearer-Token-Authentifizierung

kann sich mit demselben Endpunkt verbinden:

https://mcp.billionverify.com/mcp

Nutzen Sie die Remote-MCP-Konfiguration Ihres Clients und hinterlegen Sie die URL oben. Verwenden Sie weder curl --stdio als Wrapper noch einen API-Schlüssel im Query-String.

Wann Sie stattdessen die REST-API nutzen sollten

Verwenden Sie die BillionVerify-REST-API anstelle von MCP, wenn:

• Ihr Client nur lokale stdio-MCP-Server unterstützt
• Ihre Integration auf API-Schlüsseln statt OAuth basiert
• Sie eine Backend-zu-Backend-Automatisierung ohne MCP-Client bauen

API-Schlüssel existieren weiterhin für die BillionVerify-REST-API. Sie gehören nur nicht mehr zum MCP-Authentifizierungsmodell.

Verfügbare Tools

Verfügbare Ressourcen

Beispiel-Prompts

Einzelne E-Mail verifizieren

Verify john@google.com

Batch-Verifizierung

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

Kontostand

How many BillionVerify credits do I have left?

Verifizierungshistorie

Show my 20 most recent verification jobs

Gefilterte Ergebnisse herunterladen

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

Webhook-Verwaltung

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

Beispielantworten des MCP-Servers

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

Fehlerbehebung

Ich erhalte 401, einen OAuth-Prompt oder mcp/www_authenticate

Das bedeutet meist, dass der Client die OAuth-Autorisierung noch nicht abgeschlossen hat, das Access Token abgelaufen ist oder der erforderliche Scope fehlt. Verbinden Sie den MCP-Server erneut und bestätigen Sie die angeforderten Scopes.

Mein Client unterstützt nur curl --stdio oder lokale JSON-Konfigurationen mit API-Schlüsseln

Dieser Client ist mit dem aktuellen Remote-MCP-Authentifizierungsmodell von BillionVerify nicht kompatibel. Verwenden Sie stattdessen die BillionVerify-REST-API.

Ich habe früher ?api_key=... verwendet und jetzt funktioniert es nicht mehr

Dieser Legacy-Flow wurde aus der MCP-Oberfläche entfernt. Wechseln Sie zu einem OAuth-fähigen MCP-Client und verbinden Sie den Remote-Endpunkt direkt.

Wie funktionieren Credits?

• Gültige E-Mail: 1 Credit
• Ungültige E-Mail: 0 Credits
• Unbekannte E-Mail: 0 Credits

Verwenden Sie get_account_balance, um Ihr verbleibendes Guthaben zu prüfen.

FAQ

Unterstützt der MCP-Server API-Schlüssel?

Nein. Der Remote-MCP-Server erfordert OAuth-Access-Tokens. Entwickler-API-Schlüssel sind für die REST-API gedacht, nicht für den Verbindungsaufbau mit MCP.

Welche Clients werden unterstützt?

Jeder Client, der Remote-MCP über Streamable HTTP und OAuth-protected resources unterstützt, kann sich verbinden. ChatGPT ist ein Beispiel. Für Clients ohne Remote-OAuth-MCP-Support verwenden Sie bitte die REST-API.

Muss ich ein npm-Paket installieren?

Nein. Dies ist ein gehosteter Remote-MCP-Server. Sie verbinden sich direkt mit https://mcp.billionverify.com/mcp.

Kann ich Historie und Statistiken über MCP abrufen?

Ja. Verwenden Sie get_verification_history, get_verification_stats oder die entsprechenden schreibgeschützten Ressourcen.

Nächste Schritte