Verbindung mit einem MCP-Server über den MCP Client Connector in Jitterbit Studio

Einführung

Das Model Context Protocol (MCP) ist ein offener Standard zum Verbinden von LLMs mit externen Tools und Datenquellen. Ein MCP-Server stellt eine Sammlung benannter Tools zur Verfügung, jeweils mit einem definierten Input-Schema. Ein MCP-Client erkennt diese Tools, übergibt ihre Schemas einem LLM als verfügbare Funktionen und führt die Tool-Aufrufe aus, die das LLM auswählt.

Der MCP Client Connector bietet zwei Aktivitäten, die den Tool-Aufruf-Zyklus abdecken:

• Tools auflisten: Ruft das Tool-Manifest vom MCP-Server ab. Damit wird das Verzeichnis der verfügbaren Tools des LLMs vor jeder Konversation gefüllt.
• Tools aufrufen: Führt ein bestimmtes Tool auf dem MCP-Server mit den Argumenten aus, die das LLM ausgewählt hat. Wird nach einer tool_calls-Antwort des LLMs verwendet.

Diese Anleitung behandelt die Verbindungseinrichtung, das Abrufen des Tool-Manifests und den Tool-Aufruf auf Connector-Ebene. Für die vollständige Schleife mit mehreren Runden, die diese Schritte mit einem LLM verbindet, siehe Implementiere eine LLM-Tool-Aufruf-Schleife. Für eine vollständige Agent-Anleitung, die diese Komponenten in einem funktionierenden KI-Agent zusammenführt, siehe So erstellst du einen KI-Agent mit MCP. Wenn der MCP-Server, mit dem du dich verbindest, in Jitterbit MCP erstellt wurde, siehe Verbindung mit einem Jitterbit MCP-Server über den MCP Client Connector, um die Server-URL und das Authentifizierungstoken zu finden.

Design-Muster

Der MCP-Tool-Ausführungs-Zyklus nutzt zwei Operationen. Eine Tool-Erkennungs-Operation ruft das Tool-Manifest einmalig ab (oder zu Beginn jeder Sitzung) und registriert die verfügbaren Tools mit dem LLM. Eine Tool-Aufruf-Operation wird jedes Mal ausgeführt, wenn das LLM ein Tool auswählt und das Ergebnis an das LLM zurückgibt.

Teil 1: Konfiguriere die MCP Client Verbindung

1. Öffne im Projektdesigner die Registerkarte Projektendpunkte und Connectoren der Design-Komponentenpalette.

2. Klicke unter Verfügbare Endpunkte auf MCP Client, um es zu erweitern und die verfügbaren Aktivitätstypen anzuzeigen.

3. Klicke auf Neuen Endpunkt hinzufügen, um eine neue Verbindung zu erstellen. Der Verbindungskonfigurationsbildschirm wird angezeigt.

4. Gib einen Verbindungsnamen ein. Der Name muss innerhalb des Projekts eindeutig sein und darf / oder : nicht enthalten.

5. Gib in MCP-Server-URL die vollständige Endpunkt-URL des MCP-Servers ein, einschließlich Protokoll und Pfad. Beispiel: https://api.example.com/mcp.

6. Wähle unter Authentifizierungsmechanismus die Option, die dem MCP-Server entspricht:

   • Keine Authentifizierung: Es sind keine Anmeldedaten erforderlich.
   • Zugriffstoken: Gib ein Bearer-Token ein, das vom MCP-Server oder dessen Dienstanbieter ausgegeben wurde.
   • Authorization Code Grant: Wähle eine in App-Registrierungen konfigurierte OAuth-Anwendung aus und klicke auf Mit OAuth anmelden. Siehe 3LO-Voraussetzungen für Einrichtungsanforderungen. Agent-Version 10.83 / 11.21 oder höher erforderlich.

7. (Optional) Klicke auf Optionale Einstellungen, um zusätzliche Einstellungen zu konfigurieren:

   • Protokollversion: Wähle die MCP-Protokollversion. Die Standardeinstellung (2025-06-18) wird empfohlen, sofern der MCP-Server keine bestimmte Version benötigt.
   • Timeout (in Millisekunden): Erhöhe diesen Wert, wenn der MCP-Server langsam antwortet. Die Standardeinstellung ist 30000 (30 Sekunden).
   • Benutzerdefinierte Request-Header: Füge alle Header hinzu, die der Server bei jeder Anfrage benötigt.

8. Klicken Sie auf Test, um die Verbindung zu überprüfen. Ein erfolgreicher Test lädt auch die neueste Connector-Version in die Agentgruppe herunter, die der aktuellen Umgebung zugewiesen ist.

9. Klicken Sie auf Save Changes.

Part 2: Tool-Manifest abrufen

Die Aktivität List Tools ruft alle Tools ab, die derzeit auf dem MCP-Server registriert sind. Jeder Tool-Eintrag enthält seinen Namen, eine Beschreibung und ein Input-Schema. Führen Sie diese Operation vor dem ersten LLM-Aufruf in einem Workflow oder am Anfang jeder Sitzung aus, wenn sich die Tool-Liste des Servers dynamisch ändert.

1. Ziehen Sie den Aktivitätstyp List Tools aus der Designkomponentenpalette in eine Drop-Zone auf der Designoberfläche. Eine neue Operation wird erstellt.

2. Doppelklicken Sie auf die Aktivität, um ihre Konfiguration zu öffnen.

3. Geben Sie im Feld Name einen Namen für die Aktivität ein (z. B. MCP - List Tools).

4. Klicken Sie auf Next, um zu Schritt 2 zu wechseln, wo das vom MCP-Server zurückgegebene Response-Schema angezeigt wird. Klicken Sie auf Refresh, wenn das Schema nicht angezeigt wird.

5. Klicken Sie auf Finished.

6. Fügen Sie eine Transformation rechts neben der Aktivität List Tools in derselben Operation ein. Die Transformation ordnet die MCP-Tool-Definitionen dem Format zu, das der LLM erwartet. Details zur Zuordnung finden Sie unter Part 3.

Part 3: Tool-Manifest in das LLM-Format übertragen

Die Antwort von List Tools enthält ein tools-Array. Jeder Eintrag enthält die folgenden Felder:

Die meisten LLM-APIs, einschließlich OpenAI Chat Completions und Azure OpenAI, erwarten Tools, die als Funktionsschemas weitergegeben werden:

{
  "type": "function",
  "function": {
    "name": "<tool name>",
    "description": "<tool description>",
    "parameters": { "<inputSchema contents>" }
  }
}

Ordnen Sie in der Transformation nach List Tools die Felder name, description und inputSchema den entsprechenden Feldern im Request-Schema des LLM zu. Falls Sie einen LLM-Connector verwenden (z. B. OpenAI, Amazon Bedrock oder Ollama), der eine Aktivität Register Tools bereitstellt, platzieren Sie diese Aktivität rechts neben der Transformation als Ziel der Operation.

Wenn die Operation ausgeführt wird, speichert Jitterbit die registrierten Tool-Schemas im Speicher des privaten Agenten. Jede Operation, die danach ausgeführt wird, hat automatisch Zugriff auf diese Schemas, wenn sie den LLM aufruft. Sie müssen die Antwort von Register Tools nicht erfassen oder die Tool-Definitionen explizit an die nachfolgende Prompt-Operation übergeben. Dieser In-Memory-Speicher ist eine Funktion des privaten Agenten, weshalb ein privater Agent erforderlich ist, um die Aktivität Register Tools zu verwenden.

Wenn du das LLM über den HTTP v2 Connector aufrufen möchtest, füge das serialisierte Tool-Array im Feld tools des LLM-Request-Body ein. Speichere das Ergebnis als Projektvariable (z. B. mcp_tools_json), um es in jeder LLM-Anfrage wiederzuverwenden, ohne List Tools erneut aufzurufen. Informationen zur LLM-Request-Body-Konstruktion und zum HTTP v2-Setup findest du unter REST-API mit dem HTTP v2 Connector aufrufen.

Teil 4: Ein Tool auf dem MCP-Server aufrufen

Wenn das LLM eine tool_calls-Antwort zurückgibt, extrahiere den Tool-Namen und die Argumente und führe das Tool dann mit der Aktivität Invoke Tools aus.

Den Tool-Aufruf aus der LLM-Antwort extrahieren

Füge nach dem LLM-Aufruf einen Skript-Schritt hinzu, um die Antwort zu lesen und die Tool-Call-Variablen zu setzen:

$tool_call_id  = TrimChars(GetJSONString($jitterbit.response,
                     "/choices/0/message/tool_calls/0/id"), "\"");
$function_name = TrimChars(GetJSONString($jitterbit.response,
                     "/choices/0/message/tool_calls/0/function/name"), "\"");
$function_args = GetJSONString($jitterbit.response,
                     "/choices/0/message/tool_calls/0/function/arguments");

function_name muss genau dem name-Wert entsprechen, der von List Tools zurückgegeben und auf dem MCP-Server definiert wird. function_args ist ein JSON-String mit den Parameterwerten, die das LLM ausgewählt hat. Analysiere ihn mit JSONParser, um einzelne Werte zu extrahieren, bevor du sie an die Transformation im nächsten Schritt übergibst.

Die Aktivität „Invoke Tools" konfigurieren

1. Ziehe den Aktivitätstyp Invoke Tools aus der Design-Komponenten-Palette auf eine Drop-Zone auf der Design-Canvas.

2. Doppelklicke auf die Aktivität, um ihre Konfiguration zu öffnen.

3. Gebe im Feld Name einen Namen für die Aktivität ein (z. B. MCP - Invoke Tool).

4. Wähle unter Tool auswählen die Methode zur Angabe des Tools:

   • Tool-Namen manuell eingeben: Gebe [function_name] im Feld Tool-Name ein. Dies übergibt zur Laufzeit die Variable mit dem vom LLM ausgewählten Tool-Namen und ermöglicht es einer einzelnen Aktivitätsinstanz, jedes Tool auf dem MCP-Server aufzurufen.
   • Tool aus Liste auswählen: Wähle zur Designzeit ein bestimmtes Tool aus der Liste aus. Verwende diesen Ansatz, wenn die Operation einem bekannten Tool zugeordnet ist.

5. Klicke auf Next, um das Datenschema für das ausgewählte Tool zu überprüfen, und klicke dann auf Finished.

6. Füge eine Transformation links von der Aktivität Invoke Tools hinzu. Die Transformation ordnet die aus function_args extrahierten Argument-Werte den Eingabefeldern zu, die im Tool-inputSchema definiert sind. Das Schema ist spezifisch für das ausgewählte Tool und ist in Step 2 der Aktivität verfügbar.

Das Tool-Ergebnis erfassen

Nachdem die Aktivität Invoke Tools ausgeführt wird, ist die Antwort des MCP-Servers über das Datenschema der Aktivität verfügbar. Füge einen Skript-Schritt oder eine Transformation nach der Aktivität hinzu, um das Tool-Ergebnis function_resp zuzuweisen. Übergebe function_resp an den Nachricht-Aufbau-Schritt in Ein LLM-Tool-Aufruf-Loop implementieren, um das Ergebnis zur Unterhaltung hinzuzufügen und den nächsten LLM-Aufruf auszulösen.

Integration überprüfen

1. Stellen Sie den Tool Discovery-Betrieb bereit und führen Sie ihn aus. Bestätigen Sie in den Betriebslogs, dass die List Tools-Aktivität ein nicht-leeres Manifest zurückgegeben hat. Verwenden Sie WriteToOperationLog, um Toolnamen zu protokollieren und zu überprüfen, dass die erwarteten Tools aufgelistet sind.

2. Führen Sie einen Test-LLM-Aufruf mit dem registrierten Tool-Manifest aus. Senden Sie eine Benutzernachricht, die eindeutig einem der registrierten Tools entspricht. Bestätigen Sie in den Logs, dass die LLM-Antwort einen tool_calls-Eintrag enthält und dass function_name einem Toolnamen aus dem Manifest entspricht.

3. Stellen Sie den Tool Invocation-Betrieb bereit und führen Sie ihn aus mit function_name und function_args, die auf einen gültigen Tool-Aufruf gesetzt sind. Überprüfen Sie in den Logs, dass die Invoke Tools-Aktivität abgeschlossen wurde und dass function_resp die erwartete Ausgabe vom MCP-Server enthält.

4. Wenn die Invoke Tools-Aktivität mit einem Schemafehler fehlschlägt, klicken Sie in Schritt 2 der Aktivität auf Aktualisieren, um das Schema vom MCP-Server zu regenerieren, und überprüfen Sie dann die Transformationszuordnung.

5. Wenn das LLM ein Tool auswählt, das auf dem MCP-Server nicht verfügbar ist (z. B. aufgrund eines Namenskonflikts), gibt die Invoke Tools-Aktivität einen Fehler zurück. Aktivieren Sie Bei Fehler fortfahren in der Aktivitätskonfiguration, um den Fehler zu protokollieren, ohne den Betrieb zu beenden, und geben Sie dann eine aussagekräftige Fehlermeldung an das LLM als Tool-Ergebnis zurück, damit das Modell angemessen reagieren kann.