MCP-Server

Ein MCP-Server (Model Context Protocol) ist ein Endpoint, der ein oder mehrere Tools bereitstellt, die die KI zur Laufzeit entdecken und verwenden kann. So können Sie das Tool-Set weiterentwickeln, ohne die Agentenkonfiguration anzufassen: ein Tool auf Ihrem Server hinzufügen, die KI sieht es bei der nächsten Discovery.

Was ein MCP-Server ist

MCP ist ein offenes Protokoll, basierend auf JSON-RPC 2.0 über HTTP (Streamable HTTP). Der Server stellt Primitive wie tools/list und tools/call bereit. yourang.ai fragt Ihren Server zu Beginn jedes Anrufs ab, um die Tools zu entdecken, und legt sie dem KI-Modell als aufrufbare Funktionen vor. Jede Invocation läuft über Ihren Server, der die Logik ausführt und antwortet.

Wie die KI mit dem MCP-Server kommuniziert

1. 1

   Initiale Discovery

   Beim Start des Anrufs sendet yourang.ai eine tools/list-Anfrage an Ihren MCP-Server. Der Server antwortet mit der Liste der Tools (Name, Beschreibung, Parameterschema). Die Discovery überträgt keine Kundendaten: sie baut nur den Tool-Katalog auf.

2. 2

   MCP-Sitzung

   Die erste Antwort des Servers liefert einen Mcp-Session-Id-Header. Wir verwenden ihn bei jeder nachfolgenden Anfrage (tools/list und tools/call) innerhalb desselben Sprachanrufs, damit Ihr Server bei Bedarf Status halten kann.

3. 3

   Bereitstellung für den Agenten

   Entdeckte Tools werden dem KI-Modell als aufrufbare Funktionen übergeben, neben vordefinierten Tools und External Tools.

4. 4

   Invocation (tools/call)

   Wenn das Modell entscheidet, ein MCP-Tool zu nutzen, ruft yourang.ai tools/call mit Tool-Name + Argumenten auf. Neben den Argumenten hängen wir automatisch einen _meta.caller-Block mit den bekannten Kundendaten an (siehe Abschnitt unten).

5. 5

   Antwort an die KI

   Der Textinhalt der MCP-Antwort wird aus den content[].text-Blöcken extrahiert, verkettet und als Function Output an das Modell zurückgegeben. Das Gespräch geht weiter.

JSON-RPC-Payload

Die zwei Anfragen, die Ihr Server erhalten wird, sind einfach und standardisiert. Discovery überträgt keine Metadaten; Invocation schon.

{
 "jsonrpc": "2.0",
 "method": "tools/list",
 "params": {},
 "id": "<uuid>"
}

Automatisch übergebene Kunden-Metadaten

Wenn die KI ein Tool aufruft, reichert yourang.ai die Anfrage mit einem _meta.caller-Block an, der den aktuellen Anrufkontext enthält. Das sind Standardfelder, gefüllt mit dem, was wir zum Anrufzeitpunkt bereits über den Kunden wissen.

call_sid

Eindeutige UUID des laufenden Anrufs. Nützlich, um Ihre Logs auf MCP-Seite mit dem Anrufverlauf in yourang.ai zu korrelieren.

agent_id

UUID des KI-Agenten, der das Tool aufgerufen hat. Verwenden Sie sie, wenn mehrere Agenten denselben MCP-Server teilen und Sie die Logik differenzieren müssen.

organization_id

UUID der Organisation (Tenant). Üblicherweise der erste Filter, den Sie auf Ihrem Server anwenden: jeder Anruf gehört zu genau einem Tenant.

phone

Telefonnummer des Anrufers im E.164-Format (z. B. +49 30 12345678), sofern verfügbar.

name

Name des Kontakts, sofern bereits im Adressbuch für diese Nummer vorhanden. Fehlt, wenn der Anrufer unbekannt ist.

email

E-Mail des Kontakts, sofern in der Kontaktkarte in yourang.ai vorhanden.

contact_id

UUID des Kontakts in yourang.ai, wenn die Nummer im Adressbuch übereinstimmte. Damit holen Sie weitere Daten, ohne erst per Telefonnummer suchen zu müssen.

So konfigurieren Sie einen

1. 1

   Agentenkonfiguration öffnen

   /ai-agents → Agent auswählen → Tab MCP.

2. 2

   URL und Authentifizierung eingeben

   HTTPS-URL des MCP-Servers, Authentifizierungsmethode (keine, Bearer, API-Key, benutzerdefinierte Header).

3. 3

   Speichern und Discovery prüfen

   Das Panel zeigt die Anzahl der zuletzt entdeckten Tools und den Zeitstempel. Mit einem Klick können Sie eine neue Discovery erzwingen.

4. 4

   Einzelne Tools aktivieren oder deaktivieren

   Auch wenn der Server 30 Tools bereitstellt, können Sie nur die 5 für diesen Agenten aktivieren.

Authentifizierung und Header

Jede MCP-Anfrage enthält immer die Standard-Header Content-Type und Accept, dazu den von Ihnen konfigurierten Auth-Header und eine Mcp-Session-Id, die wir bei allen Anfragen derselben Sprachsitzung wiederverwenden.

# Sempre presenti
Content-Type: application/json
Accept: application/json, text/event-stream
Mcp-Session-Id: <restituito dal server alla prima risposta>

# Auth (in base alla configurazione)
Authorization: Bearer <token>
# oppure
X-API-Key: <chiave>

Keine

Öffentlicher Server. Nur für Tests oder Tools ohne sensible Daten.

Bearer

Header Authorization: Bearer <Token> bei jeder Anfrage.

API-Key

Beliebiger HTTP-Header (z. B. X-API-Key).

Benutzerdefinierte Header

Mehrere Kombinationen (z. B. X-Tenant + X-Signature).

Wann MCP einem External Tool vorzuziehen ist

• Sie haben viele verwandte Tools. Ein MCP-Server, der 10 CRM-Tools bereitstellt (lookup, create, update, list, ...), ist handlicher als 10 einzelne External Tools.
• Sie wollen den Tool-Katalog weiterentwickeln. Tools auf Ihrem Server ergänzen, ohne die yourang.ai-Konfiguration anzufassen: Die nächste Discovery erkennt sie.
• Sie müssen nur mit einem Endpoint sprechen. Ein External Tool ist leichter: weniger Overhead, direkte Konfiguration.