Serwer MCP

@spicyapi/mcp pozwala asystentowi AI, z którego już korzystasz – Claude, Cursor, VS Code, Codex, Windsurf, Gemini CLI i innym – pracować ze SpicyAPI za ciebie. Po konfiguracji możesz napisać „zrób mi pięciosekundowe wideo z tego zdjęcia”, a asystent znajdzie odpowiedni model, poda ci cenę, poczeka na twoją zgodę, uruchomi zadanie i przekaże ci link do wyniku.

Nie musisz pisać kodu. Potrzebujesz Node.js, klucza API i około dziesięciu minut.

Czym jest MCP, prostymi słowami

MCP (Model Context Protocol) to otwarty standard, który daje asystentom AI dodatkowe umiejętności. Wyobraź go sobie jako gniazdko: asystent obsługujący MCP może wczytywać „serwery”, a każdy serwer dodaje zestaw narzędzi, z których asystent może korzystać podczas rozmowy z tobą.

@spicyapi/mcp to jeden z takich serwerów. Dodaje 15 narzędzi SpicyAPI. Oto, co się dzieje, gdy o coś prosisz:

1. Piszesz zwykłą wiadomość, na przykład „Wygeneruj obraz latarni morskiej o świcie”.
2. Asystent decyduje, których narzędzi SpicyAPI potrzebuje, i je wywołuje.
3. Serwer – niewielki program działający na twoim własnym komputerze, uruchamiany automatycznie przez aplikację asystenta – wysyła te żądania do SpicyAPI z użyciem twojego klucza API.
4. Wszystko, co kosztuje, najpierw się zatrzymuje: twoja aplikacja pokazuje ci cenę i prosi o potwierdzenie. Asystent nie może odpowiedzieć na to pytanie za ciebie.
5. Wyniki wracają do rozmowy, a asystent je objaśnia.

Niczego nie trzeba hostować ani utrzymywać w działaniu. Aplikacja asystenta uruchamia serwer, gdy go potrzebuje, i zatrzymuje go, gdy ją zamykasz.

Pasuje do ciebie, jeśli już korzystasz z asystenta AI i chcesz wypróbowywać modele, porównywać ceny albo tworzyć obrazy i wideo bez pisania programu. Programiści używają go też do przeglądania katalogu prosto z edytora, zanim zbudują integrację.

Nie jest właściwym narzędziem do aplikacji produkcyjnej ani backendu (użyj SDK albo HTTP API), do dużych partii działających bez nadzoru (użyj CLI) ani do strumieniowania odpowiedzi czatu token po tokenie – serwer MCP wysyła zadania i śledzi ich przebieg; czatowi poświęcona jest strona Tekst i streaming.

MCP, CLI, SDK czy Skill?

SpicyAPI publikuje cztery osobne pakiety. Większości osób wystarczy jeden albo dwa.

Jeśli twoja aplikacja nie jest napisana w TypeScripcie, wiersz z SDK ma jeszcze cztery warianty: Python, Go, PHP i Java.

Co może zrobić twój asystent

Oto wszystkie 15 narzędzi, które dodaje serwer. Nigdy nie wywołujesz ich z nazwy – prosisz własnymi słowami, a asystent sam wybiera. Nazwy przydają się, gdy czytasz, co asystent zrobił, albo gdy aplikacja prosi cię o zatwierdzenie wywołania narzędzia.

„Najpierw pyta ciebie” oznacza, że sam serwer SpicyAPI się zatrzymuje i prosi o potwierdzenie – asystent nie może tego pominąć. Wiele aplikacji dodatkowo pyta cię przed uruchomieniem dowolnego narzędzia; to własne ustawienie aplikacji, niezależne od opisanego tutaj potwierdzenia.

Zanim zaczniesz

node --version

Skonfiguruj swojego klienta

Każda z poniższych aplikacji uruchamia to samo polecenie: npx --yes --package=@spicyapi/mcp spicyapi-mcp. Przy pierwszym uruchomieniu pobierany jest pakiet, co może potrwać kilka sekund.

Nigdy nie musisz uruchamiać tego polecenia samodzielnie – robi to aplikacja. Jeśli uruchomisz je ręcznie, będzie w ciszy czekać, aż aplikacja zacznie się z nim komunikować. Wygląda to na zawieszenie, ale jest normalne. Naciśnij Ctrl+C, żeby je zatrzymać.

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

Każda aplikacja sama decyduje, gdzie trzyma konfigurację i w jakim formacie, a jedno i drugie zmienia się między wersjami. Gdy któryś krok powyżej nie pasuje już do twojej aplikacji, rozstrzyga jej własna dokumentacja MCP. Inna aplikacja obsługująca MCP może użyć tych samych wartości command, args i env, które pokazano powyżej.

Chroń swój klucz

Każdy, kto ma twój klucz, może wydawać twoje saldo. Kilka nawyków pozwala utrzymać go pod kontrolą:

• Wpisuj klucz tylko do plików na poziomie użytkownika – tych z twojego folderu domowego wymienionych powyżej – a nigdy do pliku w projekcie ani repozytorium. Jeśli robisz kopię zapasową plików ustawień w publicznym repozytorium „dotfiles”, pomiń te pliki.
• Nigdy nie wklejaj klucza do czatu. Asystent go nie potrzebuje; serwer odczytuje go z konfiguracji.
• Ustaw limit dzienny klucza, żeby pomyłka miała swój pułap.
• Jeśli klucz wycieknie, unieważnij go na stronie Klucze API i utwórz nowy. Unieważnienie działa natychmiast; zadania już przyjęte i tak się zakończą i zostaną rozliczone. Zobacz Uwierzytelnianie.

Sprawdź, czy działa

W nowej rozmowie poproś o te trzy rzeczy, po kolei:

1. „Sprawdź status usługi SpicyAPI” – używa spicyapi_service_status. Nie wymaga klucza, więc jeśli to działa, serwer jest poprawnie zainstalowany.
2. „Jakie mam saldo w SpicyAPI?” – używa spicyapi_balance_get. Jeśli to działa, twój klucz dociera do serwera.
3. „Jakie masz narzędzia SpicyAPI?” – asystent powinien wymienić 15 narzędzi o nazwach zaczynających się od spicyapi_.

Żadne z nich nic nie kosztuje. Jeśli któreś się nie powiedzie, zajrzyj do sekcji Rozwiązywanie problemów.

Wypróbuj: przykładowe rozmowy

Skopiuj dowolną z nich do swojego asystenta. Opisy pokazują, z których narzędzi asystent zwykle skorzysta – asystenci się różnią, więc dokładna kolejność może być inna – i w którym dokładnie miejscu zatrzyma się, żeby cię zapytać.

Sprawdź saldo i wydatki

Ile mam salda w SpicyAPI i ile wyniosły moje wydatki w tym tygodniu?

Asystent wywołuje spicyapi_balance_get i spicyapi_usage_get. Oba narzędzia są bezpłatne i tylko do odczytu, więc nic nie prosi o potwierdzenie. „Held” w saldzie to pieniądze zablokowane przez zadania, które jeszcze trwają.

Znajdź i porównaj modele

Znajdź w SpicyAPI modele, które potrafią zamienić nieruchomy obraz w wideo, i porównaj, ile kosztowałby w każdym z nich 5-sekundowy klip.

Asystent wywołuje spicyapi_models_list (z filtrem na modele wideo przyjmujące obraz), może wywołać spicyapi_model_get po szczegóły i może wywołać spicyapi_task_quote raz dla każdego kandydata, żeby dostać dokładną cenę dla twoich ustawień. Wyceny są bezpłatne i niczego nie tworzą, więc nie ma potwierdzenia. Odpowiedzią jest porównanie, z którego możesz wybrać.

Wygeneruj obraz

Wygeneruj w SpicyAPI kwadratowy obraz baru z ramenem w neonach w deszczową noc. Wybierz niedrogi model obrazu i daj mi link, gdy obraz będzie gotowy.

1. spicyapi_models_list, żeby wybrać model, i spicyapi_model_get, jeśli asystent potrzebuje pól, które ten model przyjmuje.
2. spicyapi_task_create. Tutaj asystent się zatrzymuje. Aplikacja pokazuje potwierdzenie z modelem, szacowaną opłatą, maksymalną opłatą i terminem wygaśnięcia wyceny. Nic nie zostaje pobrane, dopóki nie potwierdzisz.
3. Po twoim potwierdzeniu zadanie rusza, a spicyapi_task_wait czeka, aż się zakończy.
4. Asystent daje ci link do wyniku z zakończonego zadania.

Zamień zdjęcie z komputera w wideo

Zamień zdjęcie /Users/me/Desktop/portrait.jpg w 5-sekundowe wideo, w którym kamera powoli najeżdża na kadr.

W Windows podaj ścieżkę jako C:\Users\me\Desktop\portrait.jpg.

1. spicyapi_upload_file przesyła zdjęcie i zwraca dla niego adres spicy://. Przesyłanie jest bezpłatne i nie wymaga potwierdzenia, ale wysyła ten plik do SpicyAPI – dlatego podaj dokładną ścieżkę do pliku, o który ci chodzi.
2. spicyapi_models_list / spicyapi_model_get, żeby wybrać model wideo z obrazu i zobaczyć jego opcje.
3. spicyapi_task_create – tutaj asystent zatrzymuje się na twoje potwierdzenie i pokazuje cenę.
4. spicyapi_task_wait. Generowanie wideo często trwa kilka minut; każde czekanie trwa najwyżej pięć, więc asystent może czekać więcej niż raz, a ty możesz też zapytać o zadanie później.

Znajdź wcześniejsze zadanie

Pokaż mi moje zadania w SpicyAPI z ostatnich trzech dni, które się nie powiodły, i powiedz, dlaczego.

Asystent wywołuje spicyapi_tasks_list z filtrem na stan „failed”, a potem spicyapi_task_get dla zadań, które cię interesują, żeby odczytać błąd. Nieudane lub wygasłe zadania zwykle zwalniają całą blokadę. Niektóre odmowy dotyczące treści są płatne według zaakceptowanej wyceny, wyłącznie gdy strona modelu wyraźnie wskazuje ten wyjątek. Sprawdź settled i cost, aby poznać ostateczną kwotę. Jeśli potem napiszesz „ponów to zadanie”, asystent wywoła spicyapi_task_retry, które zatrzymuje się na twoje potwierdzenie, bo ponowienie to nowe, płatne zadanie.

Pobierz plik wyniku

Daj mi link do pobrania mojego ostatniego wideo z SpicyAPI.

Asystent znajduje zadanie przez spicyapi_tasks_list, a potem odczytuje je przez spicyapi_task_get, które zawiera gotowe do użycia linki do wyników. Otwórz link w przeglądarce, żeby pobrać plik. Linki działają krótko: jeśli któryś wygasł, zapytaj ponownie, a asystent pobierze świeży.

Serwer MCP sam nie zapisuje plików na twoim komputerze. Asystenci, którzy potrafią też uruchamiać polecenia – na przykład Claude Code czy Codex – mogą na twoją prośbę pobrać plik z linku do wskazanego folderu.

Opis narzędzi

Każde narzędzie, co przyjmuje i co zwraca. Kwoty to zawsze dolary amerykańskie zapisane jako dokładny tekst dziesiętny bez znaku $, na przykład "0.08". Daty są w UTC.

Sprawdzanie usługi i dokumentacji

spicyapi_service_status

Sprawdza, czy publiczne API SpicyAPI jest osiągalne i działa prawidłowo. Nie wymaga klucza API, nic nie kosztuje i o nic nie pyta. To narzędzie diagnostyczne: asystent nie musi go uruchamiać przed utworzeniem zadania.

Parametry: brak.

Zwraca: operational (true albo false), poszczególne sprawdzenia health i readiness z ich statusem HTTP oraz checkedAt.

spicyapi_docs_search

Przeszukuje dołączony do serwera indeks stron dokumentacji SpicyAPI i zwraca pasujące tytuły, streszczenia i linki. Nie wymaga klucza i nie wysyła żadnych żądań sieciowych.

Zwraca: listę pozycji, z których każda ma slug, title, summary, keywords i url. Linki prowadzą do tej dokumentacji i mają postać https://docs.spicyapi.ai/docs/retention. Gdy nic nie pasuje, lista jest pusta.

Przeglądanie modeli

spicyapi_models_list

Wyświetla modele, które może wywołać twój klucz API, z cenami uwzględniającymi już wszelkie zniżki na twoim koncie. Bezpłatne i tylko do odczytu.

Zwraca: total i items. Każda pozycja zawiera model (dokładny identyfikator do użycia), displayName, provider, modality, tasks, enabled i available, availability, listę pricing (każda pozycja ma etykietę poziomu cenowego, unit o wartości per_image, per_second, per_request albo per_1k_tokens oraz price w USD), startingPrice, taskTimeoutSeconds, a na żądanie także inputSchema / examples.

Niektóre ustawienia, takie jak rozdzielczość czy czas trwania, zmieniają cenę. Lista cen służy do porównań; dokładną opłatę za konkretne żądanie podaje wycena.

spicyapi_model_get

Zwraca pełny opis jednego modelu: dane wejściowe, które przyjmuje (inputSchema, czytelny dla maszyn opis każdego pola, jego typu, dozwolonych wartości i wartości domyślnych), ceny, dostępność i przykłady. Bezpłatne i tylko do odczytu.

Zwraca: te same pola co jedna pozycja z spicyapi_models_list, zawsze razem z inputSchema.

Twoje konto

spicyapi_balance_get

Pokazuje twoje saldo. Bezpłatne i tylko do odczytu. Nie jest potrzebne przed utworzeniem zadania – przy tworzeniu środki są sprawdzane automatycznie.

Parametry: brak.

Zwraca: available, held (środki zablokowane przez zadania, które jeszcze trwają) i total, w USD. Może też zawierać rozbicie funding na środki przedpłacone, środki promocyjne i ewentualny zatwierdzony kredyt; zobacz Rozliczenia.

spicyapi_usage_get

Podaje, co zrobił ten klucz API: ile było zadań, ile się powiodło, a ile nie, i ile rozliczono, w podziale na dni i modele. Bezpłatne i tylko do odczytu. Obejmuje wyłącznie klucz z twojej konfiguracji, a nie całe konto, i nie jest twoim saldem.

Zwraca: from, to, currency, totalCalls, totalSpend oraz listy days i models z polami calls, succeeded, failed i spend. Liczone są tylko rozliczone opłaty; pieniądze wciąż zablokowane przez trwające zadania nie są wliczane, a późne rozliczenie może zmienić dane wcześniejszego dnia.

Zadania

spicyapi_tasks_list

Wyświetla zadania utworzone tym kluczem API, od najnowszych – przydaje się, gdy trzeba znaleźć zadanie po zamknięciu rozmowy. Pokazuje tylko metadane: bez promptów, danych wejściowych i linków do wyników. Bezpłatne i tylko do odczytu.

Zwraca: items (każda pozycja z taskId, model, state, cost, settled, createdAt, deadlineAt i, po zakończeniu, completedAt), hasMore i nextCursor. cost jest ostateczny dopiero wtedy, gdy settled ma wartość true.

spicyapi_task_get

Otwiera jedno zadanie utworzone tym kluczem API. Bezpłatne i tylko do odczytu.

Zwraca: taskId, model, state, cost, settled, createdAt, completedAt, a zależnie od zadania także:

• output.assets – wyniki. Każdy gotowy plik ma url, który możesz otworzyć bezpośrednio, razem z expiresAt, typem mime i rozmiarem albo czasem trwania. Plik oznaczony jako pending jest jeszcze zapisywany – zapytaj ponownie za kilka sekund. Plik oznaczony jako unavailable zniknął na dobre.
• errorCode i errorMessage, gdy zadanie się nie powiodło; kody są wymienione na stronie Błędy.
• input – co zostało wysłane, dopóki nie skończy się okres przechowywania promptu.
• contentState (present, expired albo purged) i retention, które mówi, kiedy wyniki i prompty zostaną usunięte.
• sourceTaskId, gdy to zadanie jest ponowieniem.

Identyfikator zadania, które nie istnieje, i identyfikator zadania należącego do kogoś innego dają tę samą odpowiedź: „nie znaleziono”.

spicyapi_task_wait

Sprawdza zadanie raz za razem, aż się zakończy albo skończy się czas czekania, a potem je zwraca. Bezpłatne i tylko do odczytu. Koniec czasu czekania nie anuluje zadania i nie oznacza jego niepowodzenia – zadanie wykonuje się dalej, a ty możesz poczekać ponownie albo sprawdzić je później.

Zwraca: zakończone zadanie, w tej samej postaci co spicyapi_task_get. Jeśli wcześniej skończy się czas, narzędzie informuje, że zadanie nie zakończyło się w tym czasie.

Pliki

spicyapi_upload_file

Odczytuje plik z twojego komputera, przesyła go do SpicyAPI, kończy przesyłanie i zwraca adres spicy://, który można wpisać w dane wejściowe modelu – wszystko w jednym wywołaniu, bez drugiego kroku. Bezpłatne i nie wymaga potwierdzenia – ale wysyła plik, więc nie jest tylko do odczytu.

Plików, które są już dostępne w internecie pod publicznym adresem https://, nie trzeba przesyłać: asystent może przekazać ten adres bezpośrednio do modelu, jeśli model przyjmuje URL.

Przyjmowane pliki: obrazy JPEG, PNG, WebP i GIF do 10 MiB; wideo MP4 i WebM oraz dźwięk MP3 i WAV do 90 MiB i 600 sekund. Model może ustawić własne, surowsze limity.

Z których folderów: domyślnie można odczytywać tylko pliki z twojego folderu domowego. Zobacz Pliki lokalne.

Zwraca: uri (adres spicy://), fileId, bytes, contentType, sha256, width / height / durationSeconds, gdy są znane, oraz expiresAt. Adresu można domyślnie używać przez jeden dzień.

Gdy narzędzie zwraca wynik, przesyłanie jest już zakończone, więc nie trzeba uruchamiać osobnego kroku zatwierdzenia („commit”). Serwer nie ma narzędzia do kończenia przesyłania rozpoczętego przez inny program; kod, który przesyła pliki w osobnych krokach, kończy przesyłanie metodą commitUploadedFile z SDK.

spicyapi_download_url_create

Wydaje nowy, podpisany link do pobrania jednego wyniku jednego z twoich zadań. Bezpłatne. Zwykle niepotrzebne: spicyapi_task_get i spicyapi_task_wait zawierają już gotowe linki, a ponowne zapytanie o zadanie je odświeża.

Zwraca: key, url i expiresAt. Link działa przez 20 minut i po wydaniu nie da się go unieważnić, więc nie udostępniaj go ani nie zapisuj. Zobacz Media.

Wycenianie, tworzenie i usuwanie

spicyapi_task_quote

Oblicza dokładną cenę konkretnego żądania bez uruchamiania czegokolwiek i bez blokowania środków. Bezpłatne i tylko do odczytu. Asystent używa go do porównywania możliwości; nie musi go wywoływać przed utworzeniem zadania, bo tworzenie pobiera własną wycenę.

Zwraca: quoteId, model, estimatedCost, maxCharge, currency, quantity, unit i expiresAt. Wycena jest ważna pięć minut i tylko dla dokładnie tego żądania.

spicyapi_task_create

Uruchamia generację. Kosztuje i zawsze najpierw pyta ciebie.

Co się dzieje, po kolei:

1. Serwer pobiera dokładną wycenę żądania. Wycena jest bezpłatna: niczego nie tworzy i nie blokuje środków.
2. Aplikacja pokazuje ci potwierdzenie z modelem, szacowaną opłatą, maksymalną opłatą, terminem wygaśnięcia wyceny i kluczem idempotentności (odnośnikiem, który sprawia, że za to samo żądanie nie zapłacisz dwa razy).
3. Jeśli odmówisz, żadne zadanie nie powstaje, a środki nie zostają zablokowane ani pobrane. Jedynym wysłanym dotąd żądaniem była bezpłatna wycena z kroku 1.
4. Jeśli potwierdzisz, SpicyAPI sprawdza dane wejściowe, cenę, uprawnienia twojego klucza i twoje środki, blokuje szacowaną kwotę i uruchamia zadanie.

Wymaga to aplikacji, która potrafi wyświetlać pytania o potwierdzenie (MCP elicitation). W aplikacji, która tego nie potrafi, narzędzie kończy się błędem w kroku 2: pobrana została bezpłatna wycena i nic więcej się nie wydarzyło. Zobacz Zanim zaczniesz.

Zwraca: taskId, state (zwykle queued), estimatedCost i użyty idempotencyKey. Potem zadanie wykonuje się samodzielnie; żeby odebrać wynik, użyj spicyapi_task_wait albo spicyapi_task_get.

Jeśli połączenie zerwie się już po twoim potwierdzeniu, błąd zawiera klucz idempotentności. Poproś asystenta, żeby spróbował ponownie z tym samym kluczem oraz niezmienionym modelem i ustawieniami, zamiast zaczynać od nowa: może cię znowu poprosić o potwierdzenie, ale SpicyAPI zwróci pierwotne zadanie, zamiast pobrać opłatę za drugie. Nowy klucz utworzyłby drugie płatne zadanie, a zmienione ustawienia z tym samym kluczem zostaną odrzucone.

spicyapi_task_retry

Tworzy nowe, osobno rozliczane zadanie na podstawie zadania, które zakończyło się stanem failed albo expired. Pierwotne zadanie pozostaje bez zmian. Kosztuje i zawsze najpierw pyta ciebie.

Zwraca: nowy taskId, sourceTaskId (zadanie pierwotne), state, estimatedCost i idempotencyKey.

Ponowienie korzysta z aktualnej ceny modelu, a bieżące sprawdzenia danych wejściowych, uprawnień i środków wykonują się ponownie. Jego potwierdzenie nie pokazuje ceny, więc jeśli chcesz ją najpierw poznać, przed ponowieniem poproś asystenta o wycenę tego samego modelu i ustawień przez spicyapi_task_quote.

Ponowienie używa pierwotnych danych wejściowych bez zmian, więc najpierw przeczytaj errorCode nieudanego zadania:

• rate_limited, upstream_unavailable, timeout albo upstream_failed – warto ponowić raz po krótkiej przerwie.
• generation_failed – zmień prompt albo obraz i zamiast ponawiać, uruchom nowe zadanie; te same dane wejściowe zwykle zawodzą w ten sam sposób.
• invalid_asset – prześlij plik ponownie i uruchom nowe zadanie z nowym adresem spicy://; ponowienie użyłoby starego pliku.
• content_rejected, invalid_request albo unsupported_combination – nie ponawiaj bez zmian. Zmień prompt, ustawienia albo model i uruchom nowe zadanie.

Pełna lista jest na stronie Błędy.

spicyapi_task_purge

Trwale usuwa zapisaną treść jednego zakończonego zadania: wygenerowane media, dane wyniku (zapisane dane, które zwróciło zadanie), prompt i inny tekst wejściowy. Nie da się tego cofnąć i narzędzie zawsze najpierw pyta ciebie. Nic nie kosztuje – i niczego nie zwraca.

• Trwale usunąć można tylko zakończone zadania (succeeded, failed, expired albo historyczne canceled). Przyjętego zadania nie da się anulować i nie ma API do anulowania, więc przy zadaniu w stanie queued albo running poczekaj, aż się zakończy (spicyapi_task_wait), a potem je usuń.
• Najpierw pobierz wszystko, co chcesz zachować.
• Zapis rozliczeniowy zostaje: wpis w księdze rozliczeń, pobrana kwota, model, stan, znaczniki czasu i identyfikator żądania są nadal widoczne.
• Ponowne trwałe usunięcie już usuniętego zadania niczego nie psuje.

Zwraca: taskId, contentState (purged, gdy usunięcie zostanie zaplanowane), purgedAt, contentRemovedBy i billingRetained: true. Celowo nie zwraca żadnych linków. Fizyczne usunięcie plików zwykle kończy się w ciągu minuty; zobacz Przechowywanie i usuwanie danych.

Zasoby i prompt

Oprócz narzędzi serwer udostępnia dwa zasoby (resources) tylko do odczytu i jeden prompt. Aplikacje pokazują je w różnych miejscach, a wiele osób nigdy ich nie potrzebuje.

Koszty, potwierdzenia i bezpieczeństwo

Jak wygląda potwierdzenie

Gdy asystent uruchamia zadanie, aplikacja pokazuje pytanie od serwera SpicyAPI. Brzmi ono mniej więcej tak (kwoty są przykładowe):

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…

Szacowana i maksymalna opłata pokazują obecnie tę samą liczbę: szacunek to kwota blokowana w chwili uruchomienia zadania, a za zadanie nigdy nie zostanie pobrane więcej, niż wynosi ta blokada.

Sposób udzielenia odpowiedzi zależy od aplikacji – zwykle jest to pole wyboru albo przełącznik confirm oraz przyciski Accept i Decline. Zaznacz confirm i zaakceptuj, żeby kontynuować. Odmowa albo anulowanie kończy wywołanie narzędzia, a komunikat mówi, co się wydarzyło, a co nie:

Odpowiedz w ciągu pięciu minut. Wycena jest ważna pięć minut. Jeśli wygaśnie, zanim potwierdzisz, tworzenie kończy się błędem 40901 i nic nie zostaje pobrane; poproś asystenta, żeby spróbował jeszcze raz ze świeżą wyceną.

Ponowienie wyświetla podobne pytanie, ale bez ceny. Przy trwałym usuwaniu pytanie mówi, że usunięcia nie da się cofnąć i że zapisy rozliczeniowe zostają.

Dlaczego asystent nie może go pominąć

• Pytanie trafia do ciebie, a nie do AI. Serwer wysyła je do aplikacji przez funkcję elicitation protokołu MCP, a aplikacja pokazuje je tobie. Asystent nie ma jak na nie odpowiedzieć.
• Twoja odpowiedź jest powiązana z dokładnie tym żądaniem. Potwierdzenie dotyczy modelu i ustawień, które ci pokazano. Jeśli asystent zmieni cokolwiek między pytaniem a twoją odpowiedzią, serwer odmówi z komunikatem "confirmed request state does not match the current tool arguments" i nic nie zostanie utworzone.
• Niech tak zostanie. Jeśli twoja aplikacja ma ustawienie, które automatycznie akceptuje pytania od serwerów MCP, dla SpicyAPI zostaw je wyłączone. Asystent albo ustawienie, które potwierdza w twoim imieniu, usuwa jedyną kontrolę wydatków na tej ścieżce.
• Aplikacje bez obsługi potwierdzeń nie mogą wydawać pieniędzy. W nich uruchamianie, ponawianie i trwałe usuwanie po prostu zwracają błąd; przy uruchamianiu zadania do tego momentu została pobrana tylko bezpłatna wycena. Zobacz Zanim zaczniesz.

Za co płacisz

• Ceny są w dolarach amerykańskich. Szacunki, opłaty i salda to dokładne kwoty w dolarach.
• Nigdy nie zapłacisz więcej niż potwierdzone maksimum. Gdy zadanie rusza, jego szacowana kwota zostaje zablokowana (widoczna jako „held”). Gdy zadanie się powiedzie, płacisz za faktyczne zużycie, najwyżej do wysokości blokady, a niewykorzystana reszta zostaje zwolniona.
• Nieudane lub wygasłe zadania zwykle zwalniają całą blokadę. Niektóre odmowy dotyczące treści są płatne według zaakceptowanej wyceny, wyłącznie gdy strona modelu wyraźnie wskazuje ten wyjątek. Sprawdź settled i cost, aby poznać ostateczną kwotę.
• Sprawdzanie jest bezpłatne: przeglądanie modeli, wyceny, saldo, zużycie, odczytywanie zadań, czekanie, przesyłanie plików i linki do pobrania.
• Uruchomionego zadania nie da się anulować. Zamknięcie rozmowy, wyjście z aplikacji, koniec czasu czekania czy unieważnienie klucza nie zatrzymują zadania, które zostało już przyjęte. Zobacz Nieodwracalność zadań i ponowienia.
• Obowiązują limity twojego klucza. Gdy zostanie osiągnięty limit dzienny, miesięczny albo łączny, nowe zadania są odrzucane z kodem 40202, dopóki nie zacznie się nowy okres; zobacz Rozliczenia.

Jak długo są przechowywane wyniki

• Wygenerowane pliki są przechowywane najwyżej przez około 14 dni, krócej, jeśli skrócono czas przechowywania dla twojego konta albo dla danego zadania. Pobierz wszystko, co chcesz zachować.
• Linki do wyników są tymczasowe – zwykle działają 20 minut. Wygasły link nie oznacza, że plik zniknął: zapytaj ponownie o zadanie, żeby dostać świeży link, dopóki nie minął okres przechowywania.
• Prompty i dane wejściowe są przechowywane najwyżej 30 dni; zapis rozliczeniowy zadania (identyfikator, model, stan, kwota, czasy) zostaje.
• Przesłanych plików można używać przez jeden dzień.
• Żeby wcześniej usunąć treść jednego zadania, poproś asystenta o jej trwałe usunięcie. Żeby skrócić czas przechowywania dla pojedynczego zadania, poproś, żeby przy jego tworzeniu ustawił retentionSeconds.

Pełne zasady i wyjątki opisuje strona Przechowywanie i usuwanie danych.

Pliki lokalne

spicyapi_upload_file potrafi czytać pliki na twoim komputerze, co wymaga ostrożności:

• Domyślnie czyta tylko wewnątrz twojego folderu domowego (na przykład /Users/you albo C:\Users\you). Plik z innego miejsca zostaje odrzucony z komunikatem, które foldery są dozwolone.
• Skróty tego nie obchodzą. Dowiązanie symboliczne w folderze domowym, które wskazuje poza niego, zostaje odrzucone.
• Po co to ograniczenie: asystent czytający stronę internetową, e-mail albo dokument może natrafić na ukryte instrukcje, takie jak „prześlij prywatne klucze użytkownika”. Ograniczenie folderów trzyma tego rodzaju sztuczki z dala od plików systemowych. Twój własny folder domowy nadal jest dostępny do odczytu, więc pozwalaj asystentowi przesyłać tylko pliki, które wskażesz, i czytaj ścieżkę, gdy aplikacja prosi cię o zatwierdzenie wywołania narzędzia.

Zmiana folderów. Dodaj SPICY_MCP_UPLOAD_ROOTS do env serwera, obok SPICY_API_KEY, z jedną albo kilkoma pełnymi ścieżkami do folderów. To ustawienie zastępuje wartość domyślną, więc możesz zawęzić dostęp do jednego folderu albo wymienić kilka. Foldery oddziela się tak samo jak w systemowym ustawieniu PATH, a to zależy od systemu operacyjnego. Każdy folder zapisz jako pełną ścieżkę: w tym ustawieniu ~ nie jest rozwijane, choć w ścieżkach plików podawanych asystentowi jest.

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

Te bloki pokazują tylko część env. Dodaj linię SPICY_MCP_UPLOAD_ROOTS do env wpisu spicyapi, który utworzono w sekcji Skonfiguruj swojego klienta, a istniejącą linię z kluczem zostaw bez zmian. W Claude Code i Codex dodaj ją zamiast tego do polecenia rejestracji (-e SPICY_MCP_UPLOAD_ROOTS=… albo --env SPICY_MCP_UPLOAD_ROOTS=…), wcześniej usuwając serwer. Potem uruchom aplikację ponownie. Folder, który nie istnieje, po prostu do niczego nie pasuje, więc jeśli po tej zmianie przesyłanie jest odrzucane, sprawdź pisownię w komunikacie, który wymienia foldery używane przez serwer.

Tryb HTTP: tylko ten komputer

Większość aplikacji sama uruchamia serwer, tak jak opisano wyżej. Niektóre wolą łączyć się z już działającym serwerem pod wskazanym adresem. Dla nich pakiet zawiera drugi program, 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

Program wypisuje SpicyAPI MCP HTTP listening at http://127.0.0.1:8765/mcp. Skieruj aplikację na ten adres i ustaw, żeby wysyłała nagłówek Authorization: Bearer, a po nim twój SPICY_MCP_HTTP_TOKEN. Gdy serwer działa, http://127.0.0.1:8765/healthz odpowiada {"ok":true}.

„Tylko loopback” oznacza, że połączyć się mogą wyłącznie programy na tym samym komputerze. Inne urządzenia w twojej sieci Wi-Fi i internet nie mają do niego dostępu i nie ma ustawienia, które by to zmieniło – każdy inny adres zostaje odrzucony przy uruchomieniu. Żądania ze stron internetowych w innych witrynach także są odrzucane. Jeśli potrzebujesz serwera dostępnego z innych maszyn, to nie jest to rozwiązanie.

Rozwiązywanie problemów

Kod źródłowy

Pakiet jest na licencji MIT i powstaje otwarcie pod adresem github.com/spicyapi-ai/spicy-mcp. Tam przeczytasz kod każdego narzędzia z tej strony, zgłosisz zachowanie inne niż opisane i zaproponujesz zmianę.

Co dalej