smartchat

MCP-Server

MCP (Model Context Protocol) ist ein Standard, mit dem ein AI-Assistent Werkzeuge nutzt. Der SmartChat MCP-Server gibt einem Assistenten die meisten Fähigkeiten der REST-API: Kontakte lesen, einen Newsletter vorbereiten, eine Automation bauen, die Landingpage bearbeiten. Du entscheidest, was der Assistent darf. Nicht jeder REST-Aufruf ist ein MCP-Werkzeug; die Tabelle REST zu MCP zeigt, welche es sind.

#Adresse

Der Server liegt unter https://api.smartchat.marketing/mcp (Streamable HTTP). Es gibt einen Server für alle Assistenten.

#Anmeldung

Du kannst dich auf zwei Wegen verbinden:

  • OAuth. Der Assistent öffnet eine Zustimmungsseite. Du siehst, welche Rechte er anfragt, und stimmst zu. Der Assistent bekommt dann ein Zugriffstoken (sc_at_...). Die Zustimmungsseite schlägt kleine Rechte vor: Die Stufe Read ist vorgewählt.
  • API-Schlüssel. Füge einen API-Schlüssel (sc_...) als Bearer-Token ein. Siehe Anmeldung.

Verbindungen des früheren SmartChat Servers gelten nicht mehr. Verbinde dich neu.

#Was der Assistent sehen kann

Der Assistent sieht nur die Werkzeuge, die seine Rechte erlauben. Mit der Stufe Read sieht er kein Werkzeug, das deine Daten ändert, mit einer Ausnahme: Er kann einen Kontakt-Export anfordern, der eine Datei mit den Daten deiner Kontakte erzeugt. Mit mehr Rechten erscheinen mehr Werkzeuge. Siehe die Werkzeugliste.

#Für Assistenten gebaut

  • Jedes Werkzeug hat eine klare Aufgabe. Lesen und Schreiben sind nie im selben Werkzeug. Namen haben die Form verb_noun, zum Beispiel search_contacts.
  • Jedes Werkzeug sagt dem Assistenten, was es tut: Es liest nur, es ändert Daten, es sendet Nachrichten, es veröffentlicht. Siehe die Hinweise auf jeder Werkzeugseite.
  • Listen haben höchstens 50 Einträge pro Seite (Standard 20) und nutzen einen Cursor.
  • Text von Kontakten ist mit der Endung _untrusted markiert (warum).
  • Fehler kommen als Werkzeug-Ergebnis mit isError: true zurück. Der Fehler-Body hat eine request_id. Bewahre sie auf und gib sie dem Support, wenn du Hilfe brauchst.
  • Aufrufe, die Nachrichten senden, werden auf dem Server wie REST-Aufrufe geprüft: Opt-in, abgemeldete Kontakte, das 24-Stunden-Fenster und genehmigte Vorlagen. Siehe Sicher senden.

#Besondere Argumente

Manche Werkzeuge nehmen Argumente, die die REST-API als Header sendet. Ein MCP-Werkzeugaufruf hat keine Header, deshalb sind es normale Argumente:

ArgumentWannWas es tut
idempotency_keyPflicht bei Werkzeugen, die Nachrichten senden. Freiwillig bei Werkzeugen, die etwas anlegen.Ein eindeutiger Wert, den du dir ausdenkst, zum Beispiel eine UUID. Derselbe Key mit denselben Argumenten innerhalb von 24 Stunden gibt das erste Ergebnis zurück und tut nichts noch einmal.
confirmed_by_userPflicht, wo die Werkzeugseite es aufführt (zum Beispiel unsubscribe_contact). Muss true sein.Deine Aussage, dass die Nutzerin oder der Nutzer im Gespräch Ja gesagt hat. Frage zuerst nach. Der Server kann es nicht prüfen, deshalb muss der Assistent die Frage dem Nutzer zeigen.
detailFreiwillig bei manchen Listen-Werkzeugen.concise (Standard) gibt wenige wichtige Felder je Eintrag zurück, full gibt alle Felder zurück.

Beispielaufruf:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "send_text_message",
    "arguments": {
      "contact_id": "con_0123456789abcdef0123456789abcdef",
      "text": "Hello, your table is ready.",
      "idempotency_key": "6f1c1f6e-3b7a-4c52-9a43-0f6d2a1c9b11"
    }
  }
}

Ohne idempotency_key antwortet ein sendendes Werkzeug mit idempotency_key_required; ohne confirmed_by_user: true antwortet ein Werkzeug mit Bestätigung mit validation_failed.

#Was der Assistent nie kann

Es gibt keine Werkzeuge zum Löschen von Daten, für den Tarif oder die Zahlung, für die Verwaltung des Kontos oder des Teams, für API-Schlüssel, zum Verbinden der WhatsApp-Nummer oder für Rechtstexte. Einen Freitext-Auftrag an eine andere AI gibt es auch nicht. Wissen mit einem Modell hochladen und Bilder erzeugen bleiben in der App.

#Einrichten