AI Agents
MCP-Tool-Referenz
Die Tools, die der SimpliGen MCP-Server AI-Agenten zur Verfügung stellt, und die dahinter liegende lokale Control API.
SimpliGen wird mit einem MCP-Server (@simpligen/mcp) ausgeliefert, der einen AI-Agenten über eine lokale, token-authentifizierte Verbindung mit der laufenden SimpliGen-App verbindet. Der Agent ruft MCP-Tools auf; der Server leitet sie an die lokale Control API der App weiter. Siehe Verbinde einen Agent um dies einzurichten.
Tools
| Tool | Was es tut |
|---|---|
list_capabilities | Listet alle Presets auf, mit denen der Agent generieren kann (Bild oder Video), deren Eingaben und Optionen, ob sie lokal bereit sind, und Cloud-Verfügbarkeit sowie Kreditkosten. |
get_status | Meldet Engine-Status, ob Cloud verbunden ist, den Kreditstand, das aktive Projekt und den characters-Capability-Block (aktiviertes Flag, installierte Preset-Anzahl für Base/Edit/i2v und enhancePresets, die Anzahl der installierten Upscale-Presets). |
start_engine | Startet die lokale Engine, falls noch nicht vorhanden. Gibt den Engine-Status zurück; wenn ein Kaltstart länger dauert, ist engineStarting true und get_status meldet, wenn sie erreichbar ist. Macht nichts, wenn die Engine bereits läuft, und installiert niemals eine fehlende (Connector 0.3.0 oder neuer). |
stop_engine | Stoppt die lokale Engine und gibt deren VRAM frei. Cloud-Generierung ist nicht betroffen (Connector 0.3.0 oder neuer). |
restart_engine | Startet die lokale Engine neu, nach Installation oder Entfernung eines Custom Node oder wenn sie hängengeblieben ist (Connector 0.3.0 oder neuer). |
list_projects | Listet Projekte auf (die Container, die Generierungen halten). |
create_project | Erstellt ein neues Projekt. |
upload_file | Lädt ein lokales Bild oder Video hoch und erhält einen Handle zum Übergeben an generate. |
list_loras | Listet die installierten User-LoRAs auf (Name, Basis-Modell, Trigger-Wörter), damit du sie an generate übergeben kannst. |
generate | Startet eine Bild- oder Video-Generierung. Wähle local, cloud oder auto. Optional kannst du loras: [{ name, weight }] (lokales Backend, Presets wo inputs.supportsLoras true ist; verwende list_loras für Namen) und einen negativePrompt übergeben. options nimmt die benannten Felder (steps, cfg, seed, resolution, aspectRatio, durationSeconds) und alle Advanced Controls, die das Preset unter list_capabilities → options.controls deklariert, wie unlock, shift oder high_steps, als Top-Level-Schlüssel (Connector 0.2.0 oder neuer). Gibt eine Job-ID zurück. |
get_job | Erhält Status und Ergebnis eines Jobs, einschließlich des Ausgabepfads nach Abschluss. |
wait_for_result | Wartet bis ein Job abgeschlossen ist, fehlschlägt oder timeout. |
list_jobs | Listet kürzliche Generierungs-Jobs auf. |
cancel_job | Bricht einen warteschlangen- oder laufenden Job ab. |
prepare_preset | Startet das Herunterladen der Modelle eines lokalen Presets, damit es einsatzbereit wird. |
get_result_image | Gibt das Bild eines abgeschlossenen Jobs inline zur Anzeige zurück. Video-Ergebnisse geben einen Dateipfad zurück. |
list_recipe_blocks | Listet die Bausteine zum Erstellen eines Rezepts auf: Einstiegspunkte (Bild oder Video erstellen, Bild bearbeiten, hochskalieren) und jedes als Schritt nutzbare Preset, jeweils mit seinem Port-Vertrag (Eingaben, die es benötigt, was es erzeugt, zu welchen Einstiegspunkten es passt). |
compose_recipe | Erstellt ein neues Rezept aus einer High-Level-Spezifikation (geordnete Schritte an Presets gepinnt, plus eventuell Eingaben) und speichert es als Entwurf. SimpliGen verbindet die Ports automatisch, die Schritt-für-Schritt-Medienverkettung und eine Prompt-Eingabe pro Schritt, dann validiert. Gibt die Rezept-ID und Validierung zurück. |
validate_recipe | Trockenlauf einer Rezept-Spezifikation (oder Raw-Config) ohne zu speichern, und erhält präzise Fehler zum Beheben vor dem Komposieren. |
list_recipes | Listet die auf diesem Gerät gespeicherten Rezepte-Entwürfe auf. |
get_recipe | Erhält ein gespeichertes Rezept und seine vollständige Konfiguration nach ID. |
publish_recipe | Übermittelt ein gespeichertes Rezept zum Creator Marketplace (eingereiht zur menschlichen Überprüfung). Erfordert ein verbundenes Konto; wird kostenlos veröffentlicht, es sei denn, ein einmaliger Token-Preis ist festgelegt. |
run_recipe | Führt ein installiertes Rezept aus (die in UGC Studio und Product Studio oder ein Entwurf) mit seinen gefüllten Eingaben. Eine Subject-Eingabe nimmt eine Character- oder Produkt-ID, Media-Eingaben nehmen Upload-Handles, Text- und Auswahl-Eingaben nehmen einfache Werte. Gleiche Pipeline wie Klick auf Generate im Studio. Gibt eine Run-ID zurück. |
get_recipe_run | Status einer Rezept-Ausführung: Gesamtstatus, jeden Schritt mit seinem Status und Ergebnis, und den finalen Ergebnis-Pfad nach Abschluss. |
wait_for_recipe_run | Blockiert bis eine Rezept-Ausführung abgeschlossen ist (oder ein Timeout verstreicht) und gibt den finalen Run zurück. |
list_recipe_runs | Kürzliche Ausführungen eines Rezepts mit ihrem Status und Ergebnissen. |
cancel_recipe_run | Stoppt eine laufende Rezept-Ausführung. Keine weiteren Schritte starten; ein lokal laufender Schritt wird unterbrochen. |
list_subjects | Jedes Subject, das eine Rezept-Subject-Eingabe annehmen kann: Characters und Produkte, mit ihren IDs. |
list_products | Die auf diesem Gerät gespeicherten Produkte. |
create_product | Speichert ein Produkt aus einem hochgeladenen Foto (Name, Beschreibung, Kategorie), damit Product Studio und UGC-Rezepte es verwenden können. Gibt die Produkt-ID zurück. |
remove_product | Löscht ein Produkt und sein Foto. |
list_characters | Listet alle aktiven Characters in Character Studio auf. |
get_character | Erhält die Details und Bilder für einen einzelnen Character nach ID. |
list_character_features | Listet alle Identity-Features (Hautton, Haare usw.) und deren Optionen auf, zur Verwendung beim Erstellen eines Characters per Beschreibung. |
list_character_presets | Listet installierte Presets für jede Character-Rolle auf: Base-Portrait-Generierung, Identity-Bearbeitung, Image-to-Video-Animation und Verbesserung (Hochskalieren). Jedes Verbesserungs-Preset enthält ein supportedScales-Array. |
create_character | Erstellt einen neuen Character. Unterstützt drei Pfade: Beschreiben (Base-Portrait aus Feature-Auswahl generieren), Hochladen (dein eigenes Bild als Base verwenden) und Vision-Nachschaffung (Agent-beschriebene Features aus Benutzer-Foto). Im Generate-Modus fragt das Tool intern ab bis das Base-Portrait fertig ist und gibt das fertige Character-Objekt zurück. Im Upload-Modus ist der Character sofort fertig. |
generate_character_image | Generiert ein Szenenbild für einen existierenden Character per Prompt. Nimmt optional eine presetId um auszuwählen welches Identity-Edit-Preset für diesen Aufruf verwendet wird. Gibt eine oder mehrere Job-IDs zum Abfragen via wait_for_result zurück. |
generate_character_video | Generiert einen animierten Video-Clip für einen existierenden Character. Nimmt optional framePresetId (Identity-Edit-Preset für den Frame-Schritt) und videoPresetId (i2v-Preset für den Animationsschritt). Gibt Job-IDs für sowohl den Frame- als auch den Animationsschritt zurück. |
generate_character_frame | Generiert einen einzelnen Still-Frame für einen Character ohne ihn zu animieren. Nützlich wenn du den Frame überprüfen oder verbessern möchtest, bevor du ihn animierst. Nimmt optional eine presetId. Gibt { jobIds: [...] } zurück; verwende jobIds[0] als Frame-Job-ID. |
animate_character | Animiert einen Character aus einem abgeschlossenen Frame oder jedem abgeschlossenen Image-Job. Übergebe jobId (eine Job-ID aus einer beliebigen abgeschlossenen Generierung) oder filePath (absoluter lokaler Bild-Pfad). Nimmt optional eine videoPresetId. Gibt eine Video-Job-ID zurück. |
set_character_preset | Setzt ein haftendes Pro-Character-Standard-Preset für Bildgenerierung (imagePresetId) und/oder Videogenerierung (videoPresetId). Übergebe null um einen Standard zu löschen. Nachfolgende Aufrufe zu generate_character_image und generate_character_video verwenden diese Standards, es sei denn Pro-Aufruf überschrieben. |
enhance_character_media | Hochskalieren oder Verbessern eines Character-Bildes oder Videos. Quelle kann ein abgeschlossener Job (jobId), eine hochgeladene Datei (filePath-Handle) oder das Character-Base-Portrait (target: 'base') sein. Nimmt scale (Hochskalier-Faktor), keepResolution (hochskalieren dann auf Quell-Dimensionen zurückgröße für ein schärferes Ergebnis bei gleicher Größe) und applyAsBase (ersetze das Character-Base-Portrait mit dem hochskalierten Ergebnis). Gibt eine Job-ID zurück. |
regenerate_character_base | Re-generiert das Base-Portrait für einen existierenden Character an Ort und Stelle, optional wechselnd zu einem anderen Base-Preset oder aktualisierend die Identity. Kein neuer Character wird erstellt. Fragt intern ab, akzeptiert das neue Base automatisch und gibt das fertige Character-Objekt zurück. Der Agent muss danach keine Job-ID abfragen. |
remove_character | Löscht einen Character und seine zugehörigen Daten dauerhaft. |
Wie es sich verbindet
Der Agent führt den MCP-Server mit npx -y @simpligen/mcp über stdio aus. Der Server authentifiziert sich bei der App mit einem Pairing-Token (SIMPLIGEN_TOKEN) und findet den lokalen Port der App automatisch. Die SimpliGen-App muss laufen. Präge einen Token unter Settings im Abschnitt "Connect an agent".
Baust du eine benutzerdefinierte Integration?
Die MCP-Tools leiten zu einer lokalen HTTP Control API weiter, die du direkt aus jeder Sprache aufrufen kannst. Siehe die Control API-Referenz.
Ausgabenlimits
Jeder Token kann mit einer Ausgabenbegrenzung behaftet sein. Ein leeres Limit bedeutet unbegrenzte Cloud-Nutzung, 0 bedeutet nur lokale Generierung und eine positive Zahl begrenzt Cloud-Ausgaben auf diese Anzahl von Krediten. Lokale Generierung ist immer erlaubt und wird niemals gegen die Begrenzung angerechnet.