API und MCP-Server

b2breachout stellt deine Prospecting-Daten auf zwei Wegen für eigene Tools und KI-Assistenten bereit: eine REST-API v1 und einen Remote-MCP-Server (Model Context Protocol). Beide nutzen denselben API-Schlüssel, dieselbe Mandantentrennung und dieselben Fachregeln wie die App. Neben dem Lesen von Leads, Kontakten, Signalen und Entwürfen kannst du auch die Agenten-Aktionen auslösen: Discovery-Lauf, Anreicherung, Entscheider-Recherche, Signalprüfung und Entwürfe. Nichts wird automatisch an Prospects versendet — Entwürfe bleiben zur menschlichen Prüfung oder zur Übergabe an dein eigenes Versand-Tool.

• Verfügbar im Professional- und Agency-Plan.
• Schlüssel erstellst du unter Einstellungen → API-Schlüssel (lesend oder lesend + schreibend).
• Maschinenlesbarer Vertrag: openapi.json (OpenAPI 3.1, Version 1.1.0).

Authentifizierung

Jede Anfrage trägt den Schlüssel als Bearer-Token. Der Schlüssel wird nur einmal angezeigt und bei uns ausschliesslich als Hash gespeichert. Ein widerrufener Schlüssel verliert sofort den Zugriff.

curl https://b2breachout.operal.tech/api/v1/me \
  -H "Authorization: Bearer b2br_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

REST-API v1

Basis-URL: https://b2breachout.operal.tech/api/v1. Antworten sind JSON; Listen werden mit Cursor paginiert.

Beispiele

# Leads mit Fit-Score ≥ 70 in der Schweiz, 20 pro Seite
curl "https://b2breachout.operal.tech/api/v1/prospects?country=CH&minScore=70&limit=20" \
  -H "Authorization: Bearer $B2BR_KEY"

# Nächste Seite: nextCursor aus der Antwort als cursor mitgeben
curl "https://b2breachout.operal.tech/api/v1/prospects?country=CH&minScore=70&limit=20&cursor=<nextCursor>" \
  -H "Authorization: Bearer $B2BR_KEY"

# Kaufsignale der letzten 7 Tage
curl "https://b2breachout.operal.tech/api/v1/signals?since=$(date -u -v-7d +%Y-%m-%dT%H:%M:%SZ)" \
  -H "Authorization: Bearer $B2BR_KEY"

# Anruf loggen und Follow-up setzen (Scope write)
curl -X POST "https://b2breachout.operal.tech/api/v1/prospects/<id>/activities" \
  -H "Authorization: Bearer $B2BR_KEY" -H "Content-Type: application/json" \
  -d '{"kind":"call","note":"Kurz telefoniert, Interesse an Q4","nextActionAt":"2026-10-01"}'

# Status setzen (Scope write)
curl -X PATCH "https://b2breachout.operal.tech/api/v1/prospects/<id>" \
  -H "Authorization: Bearer $B2BR_KEY" -H "Content-Type: application/json" \
  -d '{"status":"replied"}'

Funnel-Rezept

So fährt ein Agent den ganzen Arbeitsfluss ohne Klick in der App — vom neuen Lead bis zum Entwurf, den dein eigenes Tool versendet. Alle Schritte brauchen einen Schlüssel mit Scope write.

# 1. Discovery-Lauf starten → 202 mit dem Run (status "running").
#    409 precondition_failed, wenn schon ein Lauf läuft oder ICP/Prioritäten nicht bestätigt sind;
#    402 quota_exceeded, wenn Agenten-Läufe oder Leads des Plans aufgebraucht sind.
curl -s -X POST "https://b2breachout.operal.tech/api/v1/discovery/runs" -H "Authorization: Bearer $B2BR_KEY"
# → {"data":{"id":"<runId>","agent":"discovery","status":"running","startedAt":"…","finishedAt":null,"summary":{…}}}

# 2. Pollen (alle 20–30 s), bis status nicht mehr "running" ist — ein Lauf dauert einige Minuten.
curl -s "https://b2breachout.operal.tech/api/v1/runs/$RUN_ID" -H "Authorization: Bearer $B2BR_KEY"

# 3. Ergebnisse des Laufs: beste Passung zuerst, isNew = in diesem Lauf neu gefunden.
curl -s "https://b2breachout.operal.tech/api/v1/runs/$RUN_ID/results" -H "Authorization: Bearer $B2BR_KEY"

# 4. Lead anreichern (Website, E-Mails, Telefone, Recherche, Socials, Tech-Stack).
curl -s -X POST "https://b2breachout.operal.tech/api/v1/prospects/$ID/enrich" -H "Authorization: Bearer $B2BR_KEY"

# 5. Entscheider recherchieren → data.contacts[] mit id, name, role, email.
curl -s -X POST "https://b2breachout.operal.tech/api/v1/prospects/$ID/decision-makers" -H "Authorization: Bearer $B2BR_KEY"

# 6. Entwurf generieren (201) — contactId aus Schritt 5, step 1 = Erstkontakt, 2–3 = Follow-ups.
#    422 suppressed, wenn die Adresse auf deiner Sperrliste steht.
curl -s -X POST "https://b2breachout.operal.tech/api/v1/drafts" \
  -H "Authorization: Bearer $B2BR_KEY" -H "Content-Type: application/json" \
  -d "{\"prospectId\":\"$ID\",\"channel\":\"email\",\"contactId\":\"$CONTACT_ID\",\"step\":1}"
# → {"data":{"id":"<draftId>","subject":"…","body":"…","status":"draft",…},"suggestedContacts":{…}}

# 7. Freigeben …
curl -s -X PATCH "https://b2breachout.operal.tech/api/v1/drafts/$DRAFT_ID" \
  -H "Authorization: Bearer $B2BR_KEY" -H "Content-Type: application/json" \
  -d '{"status":"approved"}'

# 8. … und nachdem DEIN Tool die Mail verschickt hat, als gesendet markieren:
#    setzt das Follow-up auf +4 Tage und den Lead auf "contacted".
curl -s -X PATCH "https://b2breachout.operal.tech/api/v1/drafts/$DRAFT_ID" \
  -H "Authorization: Bearer $B2BR_KEY" -H "Content-Type: application/json" \
  -d '{"status":"sent"}'

• Ein laufender Lauf lässt sich mit DELETE /runs/{id} stoppen; bis dahin gefundene Leads bleiben erhalten.
• Synchrone Aktionen (Anreicherung, Entscheider, Signalprüfung, Entwurf) akzeptieren optional den Header x-operation-id (UUID), damit du einen laufenden Aufruf über denselben Stopp-Mechanismus wie in der App abbrechen kannst.
• Nach einem Bounce: PATCH /prospects/{id}/contacts/{contactId} mit {"hidden":true} — der Kontakt verschwindet aus App und API, ohne gelöscht zu werden.

Pagination, Fehler, Limits

• Listen liefern { data: [...], nextCursor }. Solange nextCursor nicht null ist, gibt es eine weitere Seite. limit 1–100, Standard 50.
• Fehler haben immer die Form { error: { code, message } }. Codes: unauthorized (401), plan_required, insufficient_scope, forbidden (403), not_found (404), invalid_request (400), quota_exceeded (402: Plan-Kontingent, Monatslimite oder Plattform-Budget erreicht), precondition_failed (409: ICP oder Prioritäten nicht bestätigt, Lauf läuft bereits, Lauf läuft nicht mehr), suppressed (422: Adresse auf der Sperrliste, kein Entwurf), rate_limited (429), unavailable (503).
• Unbekannte oder fremde IDs antworten mit 404 — nie mit 403.
• 20'000 Anfragen pro Schlüssel und Kalendermonat, maximal 10 aktive Schlüssel pro Konto.
• Agenten-Aktionen (Discovery-Lauf, Anreicherung, Entscheider-Recherche, Signalprüfung, Entwurf generieren) sind über API und MCP auslösbar und verbrauchen genau dieselben Kontingente und Monatslimiten wie in der App: Discovery zählt gegen Agenten-Läufe pro Monat, Leads gesamt und Ergebnisse pro Lauf (max_agent_runs_per_month, max_prospects, max_discovery_results); Anreicherung, Entscheider-Recherche und Signalprüfung je 100 pro Monat; Entwürfe gegen max_drafts_per_month. Pro Konto läuft immer nur ein Discovery-Lauf gleichzeitig. Versendet wird nie etwas — auch status: sent protokolliert nur, was dein eigenes Tool verschickt hat.

MCP-Server

Der MCP-Server unter https://b2breachout.operal.tech/api/mcp (Streamable HTTP) stellt dieselben Operationen als Tools bereit, damit Claude, Cursor oder eigene Agenten direkt mit deinen Leads arbeiten können — zum Beispiel «Welche meiner Leads haben diese Woche Kaufsignale?», «Starte einen Discovery-Lauf und reichere die zehn besten neuen Leads an» oder «Logge den Anruf mit Muster AG und setze das Follow-up auf nächsten Montag».

Lesen (Scope read):

• get_account, get_icp_profile
• list_prospects, get_prospect
• list_signals, list_drafts
• list_runs, get_run, get_run_results

Schreiben und Aktionen (Scope write, verbrauchen Kontingente wie in der App):

• update_prospect_status, add_prospect_activity
• start_discovery_run, cancel_run
• enrich_prospect, research_decision_makers, check_prospect_signals
• generate_draft, update_draft, delete_draft
• add_contact, update_contact, delete_contact
• ICP und Prioritäten: get_icp_latest, get_priorities (read); save_icp_draft, confirm_icp, update_icp_personas, save_priorities_draft, confirm_priorities (write)

Claude Code

claude mcp add --transport http b2breachout https://b2breachout.operal.tech/api/mcp \
  --header "Authorization: Bearer $B2BR_KEY"

Claude Desktop, Cursor und andere stdio-Clients

Clients ohne native HTTP-Unterstützung verbinden sich über mcp-remote:

{
  "mcpServers": {
    "b2breachout": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://b2breachout.operal.tech/api/mcp",
        "--header", "Authorization: Bearer ${B2BR_KEY}"
      ],
      "env": { "B2BR_KEY": "b2br_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

Eigene Agenten

Jeder MCP-Client, der Streamable HTTP spricht (Protokoll 2026-07-28 oder 2025-Streamable-HTTP), kann sich mit dem Header Authorization: Bearer <Schlüssel> verbinden. Der Server ist zustandslos; Sitzungen oder SSE-Endpunkte sind nicht nötig. Aktions-Tools laufen synchron (bis zu einigen Minuten); ein Discovery-Lauf wird gestartet und danach mit get_run abgefragt.

Datenschutz und Sicherheit

• Ein Schlüssel sieht ausschliesslich die Daten des Kontos, das ihn erstellt hat.
• Erstellung, Widerruf und schreibende Zugriffe werden im Aktivitätsprotokoll des Kontos festgehalten.
• Datenhaltung in der EU (Frankfurt), revDSG-konform — Details in der Datenschutzerklärung.
• Verlust eines Schlüssels: sofort widerrufen und einen neuen erstellen.
• Vertragliche Regeln für API und MCP: AGB Ziff. 16.

Roadmap

• OAuth 2.1 für den MCP-Server, damit auch claude.ai-Connectors und ChatGPT ohne Schlüssel-Kopieren verbinden können.
• Webhooks für neue Kaufsignale und Entwürfe (z. B. direkt ins CRM).

Fragen oder Wünsche: info@operal.ch.