MCP-Server

@spicyapi/mcp lässt den KI-Assistenten, den Sie ohnehin nutzen – Claude, Cursor, VS Code, Codex, Windsurf, Gemini CLI und andere –, für Sie mit SpicyAPI arbeiten. Ist alles eingerichtet, schreiben Sie zum Beispiel „Mach mir aus diesem Foto ein fünf Sekunden langes Video“, und der Assistent sucht ein passendes Modell, nennt Ihnen den Preis, wartet auf Ihr Okay, startet den Auftrag und gibt Ihnen den Link zum Ergebnis.

Code müssen Sie dafür nicht schreiben. Sie brauchen Node.js, einen API-Schlüssel und etwa zehn Minuten.

Was MCP ist, einfach erklärt

MCP (Model Context Protocol) ist ein offener Standard, über den KI-Assistenten zusätzliche Fähigkeiten erhalten. Stellen Sie es sich wie eine Steckdose vor: Ein Assistent, der MCP unterstützt, kann „Server“ laden, und jeder Server bringt eine Reihe von Tools mit, die der Assistent verwenden darf, während er mit Ihnen spricht.

@spicyapi/mcp ist einer dieser Server. Er fügt 15 SpicyAPI-Tools hinzu. Das passiert, wenn Sie um etwas bitten:

1. Sie schreiben eine ganz normale Nachricht, zum Beispiel „Generiere ein Bild von einem Leuchtturm im Morgengrauen.“
2. Ihr Assistent entscheidet, welche SpicyAPI-Tools er braucht, und ruft sie auf.
3. Der Server – ein kleines Programm, das auf Ihrem eigenen Computer läuft und von Ihrer Assistenten-App automatisch gestartet wird – sendet diese Anfragen mit Ihrem API-Schlüssel an SpicyAPI.
4. Alles, was Geld kostet, hält vorher an: Ihre App zeigt Ihnen den Preis und bittet Sie um Bestätigung. Der Assistent kann diese Frage nicht an Ihrer Stelle beantworten.
5. Die Ergebnisse kommen zurück ins Gespräch, und der Assistent erklärt sie Ihnen.

Sie müssen nichts hosten und nichts dauerhaft laufen lassen. Die Assistenten-App startet den Server, wenn sie ihn braucht, und beendet ihn, wenn Sie die App schließen.

Er passt zu Ihnen, wenn Sie bereits einen KI-Assistenten nutzen und Modelle ausprobieren, Preise vergleichen oder Bilder und Videos erstellen möchten, ohne ein Programm zu schreiben. Auch Entwickler nutzen ihn, um den Katalog direkt aus ihrem Editor heraus zu erkunden, bevor sie eine Integration bauen.

Er ist nicht das richtige Werkzeug für eine produktive App oder ein Backend (nehmen Sie das SDK oder die HTTP-API), für große Stapel, die unbeaufsichtigt laufen (nehmen Sie die CLI), oder für Chat-Antworten, die Token für Token gestreamt werden – der MCP-Server reicht Tasks ein und verfolgt sie; für Chat siehe Text und Streaming.

MCP, CLI, SDK oder Skill?

SpicyAPI veröffentlicht vier getrennte Pakete. Die meisten brauchen nur eins oder zwei davon.

Ist Ihre Anwendung nicht in TypeScript geschrieben, hat die SDK-Zeile vier weitere Möglichkeiten: Python, Go, PHP und Java.

Was Ihr Assistent tun kann

Das sind alle 15 Tools, die der Server hinzufügt. Beim Namen rufen Sie sie nie auf – Sie bitten in Ihren eigenen Worten, und der Assistent wählt aus. Nützlich sind die Namen, wenn Sie nachlesen, was der Assistent getan hat, oder wenn Ihre App Sie bittet, einen Tool-Aufruf zu genehmigen.

„Fragt vorher nach“ bedeutet, dass der SpicyAPI-Server selbst anhält und um Bestätigung bittet – der Assistent kann das nicht überspringen. Viele Apps fragen Sie zusätzlich, bevor sie irgendein Tool ausführen; das ist eine eigene Einstellung der App und davon unabhängig.

Bevor Sie beginnen

node --version

Ihren Client einrichten

Jede App unten führt denselben Befehl aus: npx --yes --package=@spicyapi/mcp spicyapi-mcp. Beim ersten Start wird das Paket heruntergeladen, was ein paar Sekunden dauern kann.

Diesen Befehl müssen Sie nie selbst ausführen – die App startet ihn. Führen Sie ihn doch von Hand aus, wartet er stumm darauf, dass eine App mit ihm spricht. Das sieht aus, als hinge er, ist aber normal. Mit Ctrl+C beenden Sie ihn.

{
  "mcpServers": {
    "spicyapi": {
      "command": "npx",
      "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"],
      "env": { "SPICY_API_KEY": "YOUR_SPICY_API_KEY" }
    }
  }
}

Jede App legt selbst fest, wo ihre Konfiguration liegt und wie sie aufgebaut ist, und beides ändert sich zwischen Versionen. Passt ein Schritt oben nicht mehr zu Ihrer App, ist deren eigene MCP-Dokumentation maßgeblich. Eine andere MCP-fähige App kann dieselben Werte für command, args und env wie oben verwenden.

Ihren Schlüssel schützen

Wer Ihren Schlüssel besitzt, kann Ihr Guthaben ausgeben. Ein paar Gewohnheiten halten das Risiko klein:

• Legen Sie den Schlüssel nur in Dateien auf Benutzerebene ab – den oben genannten in Ihrem Benutzerordner –, nie in eine Datei innerhalb eines Projekts oder Repositorys. Sichern Sie Ihre Einstellungsdateien in einem öffentlichen „Dotfiles“-Repository, lassen Sie diese Dateien dabei weg.
• Fügen Sie den Schlüssel nie in den Chat ein. Der Assistent braucht ihn nicht; der Server liest ihn aus der Konfiguration.
• Legen Sie ein Tageslimit für den Schlüssel fest, damit ein Fehler eine Obergrenze hat.
• Ist ein Schlüssel geleakt, sperren Sie ihn auf der Seite API-Schlüssel und legen Sie einen neuen an. Das Sperren wirkt sofort; bereits angenommene Tasks laufen trotzdem zu Ende und werden berechnet. Was nach einem Leak zu tun ist, steht unter Authentifizierung.

Prüfen, ob es funktioniert

Fragen Sie in einem neuen Gespräch nacheinander diese drei Dinge:

1. „Prüf den Status des SpicyAPI-Dienstes.“ – verwendet spicyapi_service_status. Dafür ist kein Schlüssel nötig; funktioniert das, ist der Server richtig installiert.
2. „Wie hoch ist mein SpicyAPI-Guthaben?“ – verwendet spicyapi_balance_get. Funktioniert das, kommt Ihr Schlüssel beim Server an.
3. „Welche SpicyAPI-Tools hast du?“ – der Assistent sollte 15 Tools auflisten, deren Namen mit spicyapi_ beginnen.

Nichts davon kostet etwas. Schlägt eines fehl, siehe Fehlerbehebung.

Ausprobieren: Beispielgespräche

Kopieren Sie eines davon in Ihren Assistenten. Die Beschreibungen zeigen, welche Tools er typischerweise verwendet – Assistenten verhalten sich unterschiedlich, die genaue Reihenfolge kann also abweichen – und an welcher Stelle genau er anhält, um Sie zu fragen.

Guthaben und Ausgaben prüfen

Wie viel SpicyAPI-Guthaben habe ich, und wie viel habe ich diese Woche ausgegeben?

Der Assistent ruft spicyapi_balance_get und spicyapi_usage_get auf. Beide sind kostenlos und nur lesend, deshalb wird nirgends eine Bestätigung verlangt. held im Guthaben ist Geld, das noch laufende Tasks reserviert haben.

Modelle finden und vergleichen

Finde SpicyAPI-Modelle, die aus einem Standbild ein Video machen können, und vergleiche, was ein 5-Sekunden-Clip bei jedem davon kosten würde.

Der Assistent ruft spicyapi_models_list auf (gefiltert auf Videomodelle, die ein Bild annehmen), eventuell spicyapi_model_get für Details und eventuell spicyapi_task_quote einmal pro Kandidat, um einen exakten Preis für Ihre Einstellungen zu erhalten. Kostenschätzungen sind kostenlos und legen nichts an, deshalb gibt es keine Bestätigung. Als Antwort erhalten Sie einen Vergleich, aus dem Sie auswählen können.

Ein Bild generieren

Generiere mit SpicyAPI ein quadratisches Bild von einem neonbeleuchteten Ramen-Laden in einer regnerischen Nacht. Nimm ein günstiges Bildmodell und gib mir den Link, wenn es fertig ist.

1. spicyapi_models_list, um ein Modell zu wählen, und spicyapi_model_get, falls der Assistent die Felder braucht, die dieses Modell annimmt.
2. spicyapi_task_create. Hier hält er an. Ihre App zeigt eine Bestätigung mit dem Modell, der geschätzten Belastung, der Höchstbelastung und dem Ablaufzeitpunkt der Kostenschätzung. Bis Sie bestätigen, wird nichts berechnet.
3. Nach Ihrer Bestätigung startet der Task, und spicyapi_task_wait wartet, bis er fertig ist.
4. Der Assistent gibt Ihnen den Ergebnislink aus dem fertigen Task.

Ein Foto von Ihrem Computer in ein Video verwandeln

Mach aus dem Foto unter /Users/me/Desktop/portrait.jpg ein 5-Sekunden-Video, in dem die Kamera langsam heranfährt.

Unter Windows geben Sie den Pfad als C:\Users\me\Desktop\portrait.jpg an.

1. spicyapi_upload_file lädt das Foto hoch und gibt eine spicy://-Adresse dafür zurück. Das Hochladen ist kostenlos und fragt nicht nach einer Bestätigung, sendet diese Datei aber an SpicyAPI – geben Sie also den exakten Pfad genau der Datei an, die Sie meinen.
2. spicyapi_models_list / spicyapi_model_get, um ein Bild-zu-Video-Modell auszuwählen und seine Optionen anzusehen.
3. spicyapi_task_create – hier hält er für Ihre Bestätigung an und zeigt den Preis.
4. spicyapi_task_wait. Videos dauern oft mehrere Minuten; jedes Warten dauert höchstens fünf, deshalb wartet der Assistent eventuell mehrmals, oder Sie fragen später nach dem Task.

Einen früheren Task finden

Zeig mir meine SpicyAPI-Tasks der letzten drei Tage, die fehlgeschlagen sind, und sag mir, warum.

Der Assistent ruft spicyapi_tasks_list mit einem Filter auf fehlgeschlagene Tasks auf und dann spicyapi_task_get für die Tasks, die Sie interessieren, um den Fehler zu lesen. Bei fehlgeschlagenen oder abgelaufenen Tasks wird die Reservierung normalerweise vollständig freigegeben. Einige Inhaltsablehnungen werden zum angenommenen Angebotspreis berechnet, sofern die Modellseite diese Ausnahme ausdrücklich nennt. Prüfen Sie den endgültigen Betrag anhand von settled und cost. Sagen Sie danach „Wiederhol den da“, ruft er spicyapi_task_retry auf, das für Ihre Bestätigung anhält, denn eine Wiederholung ist ein neuer kostenpflichtiger Task.

Die Ergebnisdatei holen

Gib mir den Download-Link für mein letztes SpicyAPI-Video.

Der Assistent findet den Task mit spicyapi_tasks_list und liest ihn dann mit spicyapi_task_get, das sofort nutzbare Ergebnislinks enthält. Öffnen Sie den Link im Browser, um die Datei herunterzuladen. Links sind kurzlebig: Ist einer abgelaufen, fragen Sie erneut, und der Assistent holt einen frischen.

Der MCP-Server speichert selbst keine Dateien auf Ihrem Computer. Assistenten, die auch Befehle ausführen können – etwa Claude Code oder Codex –, können den Link auf Wunsch in einen Ordner herunterladen.

Tool-Referenz

Jedes Tool, was es entgegennimmt und was es zurückgibt. Geldbeträge sind immer US-Dollar, geschrieben als exakter Dezimaltext ohne $-Zeichen, zum Beispiel "0.08". Datumsangaben sind in UTC.

Dienst und Dokumentation prüfen

spicyapi_service_status

Prüft, ob die öffentliche API von SpicyAPI erreichbar ist und fehlerfrei läuft. Das Tool braucht keinen API-Schlüssel, kostet nichts und fragt nichts. Es dient der Diagnose: Der Assistent muss es nicht ausführen, bevor er einen Task erstellt.

Parameter: keine.

Rückgabe: operational (true oder false), die einzelnen Prüfungen health und readiness mit ihrem HTTP-Status sowie checkedAt.

spicyapi_docs_search

Durchsucht einen Index der SpicyAPI-Dokumentationsseiten, der im Server mitgeliefert wird, und gibt passende Titel, Zusammenfassungen und Links zurück. Braucht keinen Schlüssel und sendet keine Netzwerkanfrage.

Rückgabe: eine Liste von Einträgen, jeweils mit slug, title, summary, keywords und url. Die Links zeigen auf diese Dokumentationswebsite, in der Form https://docs.spicyapi.ai/docs/retention. Passt nichts, ist die Liste leer.

Modelle durchsuchen

spicyapi_models_list

Listet die Modelle, die Ihr API-Schlüssel aufrufen kann, mit Preisen, in die ein Rabatt Ihres Kontos bereits eingerechnet ist. Kostenlos und nur lesend.

Rückgabe: total und items. Jeder Eintrag enthält model (die exakte ID, die Sie verwenden), displayName, provider, modality, tasks, enabled und available, availability, eine Liste pricing (jeder Eintrag hat eine Bezeichnung der Preisstufe, eine unit aus per_image, per_second, per_request oder per_1k_tokens und einen price in USD), startingPrice, taskTimeoutSeconds sowie auf Anfrage inputSchema / examples.

Manche Einstellungen, etwa Auflösung oder Dauer, verändern den Preis. Die Preisliste dient zum Vergleichen; die genaue Belastung für eine bestimmte Anfrage liefert eine Kostenschätzung.

spicyapi_model_get

Gibt ein Modell vollständig zurück: die akzeptierten Eingaben (inputSchema, eine maschinenlesbare Beschreibung jedes Feldes mit Typ, erlaubten Werten und Standardwerten), Preise, Verfügbarkeit und Beispiele. Kostenlos und nur lesend.

Rückgabe: dieselben Felder wie ein Eintrag von spicyapi_models_list, immer einschließlich inputSchema.

Ihr Konto

spicyapi_balance_get

Zeigt Ihr Guthaben. Kostenlos und nur lesend. Vor dem Erstellen eines Tasks nicht nötig – das Erstellen prüft das Guthaben selbst.

Parameter: keine.

Rückgabe: available, held (von noch laufenden Tasks reserviert) und total, in USD. Möglicherweise ist außerdem eine Aufschlüsselung funding enthalten: vorausbezahlte Mittel, Bonusguthaben aus Aktionen und eine eventuell bewilligte Kreditlinie; siehe Abrechnung.

spicyapi_usage_get

Berichtet, was dieser API-Schlüssel getan hat: wie viele Tasks, wie viele davon erfolgreich waren oder fehlgeschlagen sind und die abgerechneten Ausgaben, gruppiert nach Tag und nach Modell. Kostenlos und nur lesend. Es erfasst nur den Schlüssel in Ihrer Konfiguration, nicht Ihr ganzes Konto, und es ist nicht Ihr Guthaben.

Rückgabe: from, to, currency, totalCalls, totalSpend sowie die Listen days und models mit calls, succeeded, failed und spend. Gezählt werden nur abgerechnete Belastungen; Geld, das laufende Tasks noch reserviert haben, zählt nicht mit, und eine späte Abrechnung kann einen früheren Tag nachträglich ändern.

Tasks

spicyapi_tasks_list

Listet die mit diesem API-Schlüssel erstellten Tasks, die neuesten zuerst – nützlich, um einen Task wiederzufinden, nachdem Sie den Chat geschlossen haben. Es zeigt nur Metadaten: keine Prompts, Eingaben oder Ergebnislinks. Kostenlos und nur lesend.

Rückgabe: items (jeweils mit taskId, model, state, cost, settled, createdAt, deadlineAt und, sobald fertig, completedAt), hasMore und nextCursor. cost ist erst endgültig, wenn settled gleich true ist.

spicyapi_task_get

Öffnet einen mit diesem API-Schlüssel erstellten Task. Kostenlos und nur lesend.

Rückgabe: taskId, model, state, cost, settled, createdAt, completedAt und je nach Task:

• output.assets – die Ergebnisse. Jedes fertige Asset hat eine url, die Sie direkt öffnen können, dazu expiresAt, den Typ mime und Größe oder Dauer. Ein Asset mit der Markierung pending wird noch gespeichert – fragen Sie in ein paar Sekunden erneut. Eines mit der Markierung unavailable ist endgültig weg.
• errorCode und errorMessage, wenn der Task fehlgeschlagen ist; die Codes stehen unter Fehler.
• input – was gesendet wurde, bis die Aufbewahrungsfrist für Prompts endet.
• contentState (present, expired oder purged) und retention, das angibt, wann Ergebnisse und Prompts entfernt werden.
• sourceTaskId, wenn dieser Task eine Wiederholung ist.

Eine Task-ID, die es nicht gibt, und eine, die jemand anderem gehört, liefern beide „not found“.

spicyapi_task_wait

Fragt einen Task wiederholt ab, bis er fertig ist oder die Wartezeit abläuft, und gibt ihn dann zurück. Kostenlos und nur lesend. Läuft die Wartezeit ab, wird der Task weder abgebrochen noch als fehlgeschlagen gewertet – er läuft weiter, und Sie können erneut warten oder später nachsehen.

Rückgabe: der fertige Task, in derselben Form wie bei spicyapi_task_get. Läuft die Zeit vorher ab, meldet das Tool, dass der Task innerhalb dieser Zeit nicht fertig geworden ist.

Dateien

spicyapi_upload_file

Liest eine Datei von Ihrem Computer, lädt sie zu SpicyAPI hoch, schließt den Upload ab und gibt eine spicy://-Adresse zurück, die in die Eingabe eines Modells gehört – alles in einem Aufruf, ohne zweiten Schritt. Kostenlos, und es fragt nicht nach einer Bestätigung – es sendet aber die Datei und ist daher nicht nur lesend.

Dateien, die bereits unter einer öffentlichen https://-Adresse online liegen, müssen nicht hochgeladen werden: Der Assistent kann diese Adresse direkt an das Modell übergeben, sofern das Modell eine URL annimmt.

Akzeptierte Dateien: Bilder im Format JPEG, PNG, WebP und GIF bis 10 MiB; Video im Format MP4 und WebM sowie Audio im Format MP3 und WAV bis 90 MiB und 600 Sekunden. Ein Modell kann eigene, strengere Grenzen setzen.

Welche Ordner: Standardmäßig lassen sich nur Dateien innerhalb Ihres Benutzerordners lesen. Siehe Lokale Dateien.

Rückgabe: uri (die spicy://-Adresse), fileId, bytes, contentType, sha256, width / height / durationSeconds, sofern bekannt, und expiresAt. Die Adresse ist standardmäßig einen Tag lang verwendbar.

Der Upload ist bereits abgeschlossen, wenn dieses Tool zurückkehrt; einen separaten „Commit“-Schritt gibt es also nicht. Der Server hat kein Tool, um einen Upload abzuschließen, den ein anderes Programm begonnen hat; Code, der in getrennten Schritten hochlädt, schließt den Upload mit commitUploadedFile aus dem SDK ab.

spicyapi_download_url_create

Stellt einen neuen signierten Download-Link für ein Ergebnis eines Ihrer Tasks aus. Kostenlos. Meist unnötig: spicyapi_task_get und spicyapi_task_wait enthalten bereits fertige Links, und eine erneute Abfrage des Tasks erneuert sie.

Rückgabe: key, url und expiresAt. Der Link funktioniert 20 Minuten und lässt sich nach dem Ausstellen nicht widerrufen; geben Sie ihn also nicht weiter und speichern Sie ihn nicht. Siehe Medien.

Preise, Erstellen und Löschen

spicyapi_task_quote

Ermittelt den exakten Preis einer bestimmten Anfrage, ohne etwas zu starten oder Geld zu reservieren. Kostenlos und nur lesend. Der Assistent nutzt es, um Optionen zu vergleichen; vor dem Erstellen eines Tasks braucht er es nicht, denn das Erstellen holt eine eigene Kostenschätzung ein.

Rückgabe: quoteId, model, estimatedCost, maxCharge, currency, quantity, unit und expiresAt. Eine Kostenschätzung gilt fünf Minuten und nur für genau diese Anfrage.

spicyapi_task_create

Startet eine Generierung. Kostet Geld und fragt immer vorher nach.

Was nacheinander passiert:

1. Der Server holt eine exakte Kostenschätzung für die Anfrage ein. Eine Kostenschätzung ist kostenlos: Sie legt nichts an und reserviert kein Geld.
2. Ihre App zeigt Ihnen eine Bestätigung mit dem Modell, der geschätzten Belastung, der Höchstbelastung, dem Ablaufzeitpunkt der Kostenschätzung und einem Idempotenzschlüssel (einer Kennung, die verhindert, dass dieselbe Anfrage zweimal berechnet wird).
3. Lehnen Sie ab, wird kein Task erstellt und kein Geld reserviert oder berechnet. Die einzige bis dahin gesendete Anfrage war die kostenlose Kostenschätzung aus Schritt 1.
4. Bestätigen Sie, prüft SpicyAPI die Eingaben, den Preis, die Berechtigungen Ihres Schlüssels und Ihr Guthaben, reserviert den geschätzten Betrag und startet den Task.

Das setzt eine App voraus, die Bestätigungsfragen anzeigen kann (MCP-Elicitation). In einer App, die das nicht kann, scheitert das Tool bei Schritt 2: Die kostenlose Kostenschätzung wurde abgerufen, sonst ist nichts passiert. Siehe Bevor Sie beginnen.

Rückgabe: taskId, state (normalerweise queued), estimatedCost und der verwendete idempotencyKey. Der Task läuft danach selbstständig; mit spicyapi_task_wait oder spicyapi_task_get holen Sie das Ergebnis ab.

Bricht die Verbindung ab, nachdem Sie bestätigt haben, enthält der Fehler den Idempotenzschlüssel. Bitten Sie den Assistenten, es mit genau diesem Idempotenzschlüssel und unverändertem Modell und unveränderten Einstellungen erneut zu versuchen, statt neu anzufangen: Möglicherweise werden Sie noch einmal um Bestätigung gebeten, aber SpicyAPI gibt den ursprünglichen Task zurück, statt einen zweiten zu berechnen. Ein neuer Idempotenzschlüssel würde einen zweiten kostenpflichtigen Task anlegen, und geänderte Einstellungen unter demselben Idempotenzschlüssel werden abgelehnt.

spicyapi_task_retry

Erstellt aus einem Task mit dem Status failed oder expired einen neuen, separat berechneten Task. Der ursprüngliche Task bleibt, wie er war. Kostet Geld und fragt immer vorher nach.

Rückgabe: die neue taskId, sourceTaskId (der ursprüngliche Task), state, estimatedCost und idempotencyKey.

Die Wiederholung verwendet den aktuellen Preis des Modells, und die aktuellen Prüfungen von Eingaben, Berechtigungen und Guthaben laufen erneut. Ihre Bestätigung zeigt keinen Preis; wenn Sie ihn vorher wissen möchten, bitten Sie den Assistenten, vor der Wiederholung mit spicyapi_task_quote eine Kostenschätzung für dasselbe Modell und dieselben Einstellungen einzuholen.

Eine Wiederholung verwendet die ursprüngliche Eingabe unverändert; lesen Sie deshalb zuerst den errorCode des fehlgeschlagenen Tasks:

• rate_limited, upstream_unavailable, timeout oder upstream_failed – nach kurzer Wartezeit eine Wiederholung wert.
• generation_failed – ändern Sie stattdessen den Prompt oder das Bild und starten Sie einen neuen Task; dieselbe Eingabe scheitert meist auf dieselbe Weise.
• invalid_asset – laden Sie die Datei erneut hoch und starten Sie einen neuen Task mit der neuen spicy://-Adresse; eine Wiederholung würde die alte Datei verwenden.
• content_rejected, invalid_request oder unsupported_combination – nicht unverändert wiederholen. Ändern Sie den Prompt, die Einstellungen oder das Modell und starten Sie einen neuen Task.

Die vollständige Liste steht unter Fehler.

spicyapi_task_purge

Löscht endgültig die gespeicherten Inhalte eines beendeten Tasks: die generierten Medien, die Ergebnisdaten (das gespeicherte Ergebnis), den Prompt und andere Eingabetexte. Das lässt sich nicht rückgängig machen, und das Tool fragt immer vorher nach. Es kostet nichts – und es erstattet nichts.

• Nur beendete Tasks (succeeded, failed, expired oder ein historisches canceled) lassen sich per Purge löschen. Ein angenommener Task lässt sich nicht abbrechen, und es gibt keine API zum Abbrechen; warten Sie bei einem Task mit queued oder running also, bis er fertig ist (spicyapi_task_wait), und löschen Sie ihn dann.
• Laden Sie vorher alles herunter, was Sie behalten möchten.
• Der Abrechnungsdatensatz bleibt: Ledger-Eintrag, berechneter Betrag, Modell, Status, Zeitstempel und Request-ID sind danach weiterhin sichtbar.
• Einen bereits gelöschten Task noch einmal per Purge zu löschen, schadet nicht.

Rückgabe: taskId, contentState (purged, sobald die Löschung eingeplant ist), purgedAt, contentRemovedBy und billingRetained: true. Links gibt das Tool bewusst nicht zurück. Das physische Entfernen der Dateien ist normalerweise innerhalb einer Minute abgeschlossen; siehe Datenaufbewahrung und Löschung.

Ressourcen und Prompt

Neben den Tools bietet der Server zwei nur lesbare Ressourcen und einen Prompt. Apps zeigen sie an unterschiedlichen Stellen, und viele Nutzer brauchen sie nie.

Kosten, Bestätigung und Sicherheit

So sieht die Bestätigung aus

Startet der Assistent einen Task, zeigt Ihre App eine Frage des SpicyAPI-Servers. Der Wortlaut sieht etwa so aus (die Beträge sind Beispiele):

Create a billable task using MODEL_ID_FROM_CATALOG? Estimated charge: USD 0.20;
maximum charge: USD 0.20. Quote expires: 2026-09-17T12:05:00Z. Before accepting
the request, SpicyAPI checks the model's current input requirements, price and
availability, your API key permissions, and available funds.
Idempotency-Key: 4f1c…

Geschätzte Belastung und Höchstbelastung zeigen derzeit dieselbe Zahl: Die Schätzung ist der Betrag, der beim Start des Tasks reserviert wird, und der Task wird nie höher berechnet als diese Reservierung.

Wie Sie antworten, hängt von der App ab – typischerweise über ein Kontrollkästchen oder einen Schalter confirm sowie Schaltflächen zum Annehmen und Ablehnen. Aktivieren Sie confirm und nehmen Sie an, um fortzufahren. Ablehnen oder Abbrechen beendet den Tool-Aufruf, und die Meldung sagt, was passiert ist und was nicht:

Antworten Sie innerhalb von fünf Minuten. Die Kostenschätzung gilt fünf Minuten. Ist sie abgelaufen, wenn Sie bestätigen, scheitert das Erstellen mit dem Fehler 40901, und es wird nichts berechnet; bitten Sie den Assistenten, es mit einer frischen Kostenschätzung erneut zu versuchen.

Beim Wiederholen erscheint eine ähnliche Frage ohne Preis. Beim Löschen per Purge weist die Frage darauf hin, dass sich das Löschen nicht rückgängig machen lässt und die Abrechnungsdatensätze erhalten bleiben.

Warum der Assistent sie nicht überspringen kann

• Die Frage geht an Sie, nicht an die KI. Der Server schickt sie über die Elicitation-Funktion von MCP an Ihre App, und die App zeigt sie Ihnen. Der Assistent hat keine Möglichkeit, sie zu beantworten.
• Ihre Antwort ist an genau diese Anfrage gebunden. Die Bestätigung gilt für das Modell und die Einstellungen, die Ihnen gezeigt wurden. Ändert der Assistent zwischen der Frage und Ihrer Antwort irgendetwas, lehnt der Server mit „confirmed request state does not match the current tool arguments“ ab, und es wird nichts erstellt.
• Lassen Sie es dabei. Bietet Ihre App eine Einstellung, die Fragen von MCP-Servern automatisch annimmt, lassen Sie sie für SpicyAPI ausgeschaltet. Ein Assistent oder eine Einstellung, die in Ihrem Namen bestätigt, entfernt die einzige Ausgabenkontrolle auf diesem Weg.
• Apps ohne Unterstützung für Bestätigungen können kein Geld ausgeben. Dort liefern Starten, Wiederholen und Purge einfach einen Fehler; beim Starten eines Tasks wurde bis dahin nur die kostenlose Kostenschätzung abgerufen. Siehe Bevor Sie beginnen.

Was Sie bezahlen

• Preise sind in US-Dollar angegeben. Schätzungen, Belastungen und Guthaben sind exakte Dollarbeträge.
• Ihnen wird nie mehr berechnet als das bestätigte Maximum. Startet ein Task, wird sein geschätzter Betrag reserviert (angezeigt als held). Ist er erfolgreich, zahlen Sie den tatsächlichen Verbrauch, begrenzt auf diese Reservierung, und nicht Verbrauchtes wird freigegeben.
• Bei fehlgeschlagenen oder abgelaufenen Tasks wird die Reservierung normalerweise vollständig freigegeben. Einige Inhaltsablehnungen werden zum angenommenen Angebotspreis berechnet, sofern die Modellseite diese Ausnahme ausdrücklich nennt. Prüfen Sie den endgültigen Betrag anhand von settled und cost.
• Nachsehen ist kostenlos: Modelle durchsuchen, Kostenschätzungen, Guthaben, Verbrauch, Task-Abfragen, Warten, Uploads und Download-Links.
• Ein gestarteter Task lässt sich nicht abbrechen. Den Chat schließen, die App beenden, ein abgelaufenes Warten oder das Sperren des Schlüssels stoppt keinen Task, der bereits angenommen wurde. Siehe Verbindliche Tasks und Wiederholen.
• Die Limits Ihres Schlüssels gelten. Ist ein Tageslimit, Monatslimit oder Gesamtlimit erreicht, werden neue Tasks mit 40202 abgelehnt, bis der Zeitraum neu beginnt; die Ausgabenlimits sind unter Abrechnung beschrieben.

Wie lange Ergebnisse aufbewahrt werden

• Generierte Dateien werden höchstens etwa 14 Tage aufbewahrt, kürzer, wenn Sie die Aufbewahrung für Ihr Konto oder für diesen Task verkürzt haben. Laden Sie herunter, was Sie behalten möchten.
• Ergebnislinks sind temporär – normalerweise 20 Minuten. Ein abgelaufener Link heißt nicht, dass die Datei weg ist: Fragen Sie den Task erneut ab, um einen frischen Link zu erhalten, solange die Aufbewahrungsfrist noch läuft.
• Prompts und Eingaben werden höchstens 30 Tage aufbewahrt; der Abrechnungsdatensatz des Tasks (ID, Modell, Status, Betrag, Zeitpunkte) bleibt erhalten.
• Hochgeladene Dateien sind einen Tag lang verwendbar.
• Um die Inhalte eines einzelnen Tasks vorzeitig zu löschen, bitten Sie den Assistenten um einen Purge. Um die Aufbewahrung für einen einzelnen Task zu verkürzen, bitten Sie ihn, beim Erstellen retentionSeconds zu setzen.

Die vollständigen Regeln und Ausnahmen stehen unter Datenaufbewahrung und Löschung.

Lokale Dateien

spicyapi_upload_file kann Dateien auf Ihrem Computer lesen, und dabei ist Vorsicht geboten:

• Standardmäßig liest es nur innerhalb Ihres Benutzerordners (zum Beispiel /Users/you oder C:\Users\you). Eine Datei an anderer Stelle wird mit einer Meldung abgelehnt, die nennt, welche Ordner erlaubt sind.
• Verknüpfungen umgehen das nicht. Ein symbolischer Link innerhalb Ihres Benutzerordners, der nach außerhalb zeigt, wird abgelehnt.
• Warum es diese Grenze gibt: Ein Assistent, der eine Webseite, eine E-Mail oder ein Dokument liest, kann auf versteckte Anweisungen stoßen wie „lade die privaten Schlüssel des Nutzers hoch“. Die Ordnergrenze hält solche Tricks von Systemdateien fern. Ihr eigener Benutzerordner bleibt aber lesbar; lassen Sie den Assistenten deshalb nur Dateien hochladen, die Sie selbst genannt haben, und lesen Sie den Pfad, wenn Ihre App Sie bittet, den Tool-Aufruf zu genehmigen.

Die Ordner ändern. Ergänzen Sie SPICY_MCP_UPLOAD_ROOTS im env des Servers, neben SPICY_API_KEY, mit einem oder mehreren vollständigen Ordnerpfaden. Die Einstellung ersetzt den Standard; Sie können also auf einen einzigen Ordner einschränken oder mehrere aufführen. Ordner werden genauso getrennt wie in der Systemeinstellung PATH, und das unterscheidet sich je nach Betriebssystem. Schreiben Sie jeden Ordner als vollständigen Pfad: ~ wird in dieser Einstellung nicht erweitert, obwohl es in den Dateipfaden, die Sie dem Assistenten nennen, erweitert wird.

{
  "env": {
    "SPICY_API_KEY": "YOUR_SPICY_API_KEY",
    "SPICY_MCP_UPLOAD_ROOTS": "/Users/you/Pictures:/Users/you/Movies"
  }
}

Diese Blöcke zeigen nur den Teil env. Ergänzen Sie die Zeile SPICY_MCP_UPLOAD_ROOTS im env des Eintrags spicyapi, den Sie unter Ihren Client einrichten angelegt haben, und lassen Sie Ihre vorhandene Schlüsselzeile unverändert. Bei Claude Code und Codex ergänzen Sie die Einstellung stattdessen im Registrierungsbefehl (-e SPICY_MCP_UPLOAD_ROOTS=… oder --env SPICY_MCP_UPLOAD_ROOTS=…), nachdem Sie den Server entfernt haben. Starten Sie die App danach neu. Ein Ordner, den es nicht gibt, passt einfach auf nichts; werden Uploads nach dieser Änderung abgelehnt, prüfen Sie also die Schreibweise in der Meldung, die die vom Server verwendeten Ordner auflistet.

HTTP-Modus: nur dieser Computer

Die meisten Apps starten den Server selbst, wie oben beschrieben. Einige wenige verbinden sich lieber über eine Adresse mit einem Server, der bereits läuft. Für diese enthält das Paket ein zweites Programm, spicyapi-mcp-http:

export SPICY_API_KEY="sk-spicy-..."
export SPICY_MCP_HTTP_TOKEN="$(node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))")"
npx --yes --package=@spicyapi/mcp spicyapi-mcp-http

Es gibt SpicyAPI MCP HTTP listening at http://127.0.0.1:8765/mcp aus. Richten Sie Ihre App auf diese Adresse aus und lassen Sie sie den Header Authorization: Bearer gefolgt von Ihrem SPICY_MCP_HTTP_TOKEN senden. http://127.0.0.1:8765/healthz antwortet mit {"ok":true}, solange der Server läuft.

„Nur Loopback“ heißt, dass sich nur Programme auf genau diesem Computer verbinden können. Andere Geräte in Ihrem WLAN und das Internet erreichen den Server nicht, und es gibt keine Einstellung, um ihn zu öffnen – jede andere Adresse wird schon beim Start abgelehnt. Anfragen von Webseiten anderer Websites werden ebenfalls zurückgewiesen. Brauchen Sie einen Server, der von anderen Rechnern aus erreichbar ist, ist dies nicht der richtige.

Fehlerbehebung

Quellcode

Das Paket steht unter MIT-Lizenz und wird offen unter github.com/spicyapi-ai/spicy-mcp entwickelt. Dort lesen Sie den Code hinter jedem Werkzeug dieser Seite, melden Verhalten, das von der Beschreibung abweicht, oder schlagen eine Änderung vor.

Nächste Schritte