Serveur MCP

@spicyapi/mcp permet à l’assistant IA que vous utilisez déjà (Claude, Cursor, VS Code, Codex, Windsurf, Gemini CLI et bien d’autres) de travailler avec SpicyAPI pour vous. Une fois la configuration terminée, vous pouvez écrire « fais-moi une vidéo de cinq secondes à partir de cette photo » : l’assistant trouve un modèle adapté, vous indique le prix, attend votre accord, lance le travail et vous remet le lien du résultat.

Vous n’avez pas besoin d’écrire de code. Il vous faut Node.js, une clé API et une dizaine de minutes.

Le MCP, en termes simples

Le MCP (Model Context Protocol) est un standard ouvert qui permet de donner des capacités supplémentaires aux assistants IA. Voyez-le comme une prise multiple : un assistant compatible MCP peut charger des « serveurs », et chaque serveur ajoute un ensemble d’outils dont l’assistant peut se servir pendant qu’il discute avec vous.

@spicyapi/mcp est l’un de ces serveurs. Il ajoute 15 outils SpicyAPI. Voici ce qui se passe quand vous demandez quelque chose :

1. Vous écrivez un message ordinaire, par exemple « Génère une image d’un phare à l’aube. »
2. Votre assistant détermine de quels outils SpicyAPI il a besoin et les appelle.
3. Le serveur, un petit programme qui s’exécute sur votre propre ordinateur et que votre application d’assistant démarre automatiquement, envoie ces requêtes à SpicyAPI avec votre clé API.
4. Tout ce qui coûte de l’argent marque d’abord une pause : votre application vous montre le prix et vous demande de confirmer. L’assistant ne peut pas répondre à cette question à votre place.
5. Les résultats reviennent dans la conversation, et l’assistant vous les explique.

Il n’y a rien à héberger ni à maintenir en marche. L’application d’assistant démarre le serveur quand elle en a besoin et l’arrête quand vous la quittez.

Il vous convient si vous utilisez déjà un assistant IA et voulez essayer des modèles, comparer des prix ou produire des images et des vidéos sans écrire de programme. Les développeurs s’en servent aussi pour explorer le catalogue depuis leur éditeur avant de construire une intégration.

Ce n’est pas le bon outil pour une application ou un backend en production (utilisez le SDK ou l’API HTTP), pour de gros lots exécutés sans surveillance (utilisez la CLI), ni pour recevoir des réponses de chat en streaming, token par token : le serveur MCP soumet et suit des tâches ; pour le chat, voir Texte et streaming.

MCP, CLI, SDK ou Skill ?

SpicyAPI publie quatre paquets distincts. La plupart des gens n’en ont besoin que d’un ou deux.

Si votre application n’est pas écrite en TypeScript, la ligne SDK offre quatre possibilités de plus : Python, Go, PHP et Java.

Ce que votre assistant peut faire

Voici les 15 outils qu’ajoute le serveur. Vous ne les appelez jamais par leur nom : vous demandez avec vos propres mots et l’assistant choisit. Les noms vous servent quand vous relisez ce qu’a fait l’assistant, ou quand votre application vous demande d’approuver un appel d’outil.

« Vous demande d’abord » signifie que le serveur SpicyAPI lui-même s’arrête et demande une confirmation : l’assistant ne peut pas la sauter. Beaucoup d’applications vous demandent aussi votre accord avant d’exécuter n’importe quel outil ; c’est un réglage propre à l’application, indépendant de celui-ci.

Avant de commencer

node --version

Configurer votre client

Toutes les applications ci-dessous exécutent la même commande : npx --yes --package=@spicyapi/mcp spicyapi-mcp. Le premier démarrage télécharge le paquet, ce qui peut prendre quelques secondes.

Vous n’avez jamais besoin de lancer cette commande vous-même : c’est l’application qui la démarre. Si vous la lancez à la main, elle attend en silence que l’application lui parle ; on dirait qu’elle est bloquée, mais c’est normal. Appuyez sur Ctrl+C pour l’arrêter.

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

Chaque application choisit l’emplacement et le format de sa configuration, et les deux changent d’une version à l’autre. Quand une étape ci-dessus ne correspond plus à votre application, c’est la documentation MCP de l’application qui fait foi. Toute autre application compatible MCP peut utiliser les mêmes command, args et env que ci-dessus.

Protéger votre clé

Quiconque détient votre clé peut dépenser votre solde. Quelques habitudes limitent les dégâts :

• Ne mettez la clé que dans des fichiers au niveau utilisateur, c’est-à-dire ceux de votre dossier personnel listés ci-dessus, jamais dans un fichier à l’intérieur d’un projet ou d’un dépôt. Si vous sauvegardez vos fichiers de réglages dans un dépôt « dotfiles » public, laissez ceux-ci de côté.
• Ne collez jamais la clé dans la conversation. L’assistant n’en a pas besoin ; le serveur la lit dans la configuration.
• Fixez un plafond quotidien sur la clé, pour qu’une erreur ait une limite.
• Si une clé a fuité, révoquez-la sur la page Clés API et créez-en une nouvelle. La révocation prend effet immédiatement ; les tâches déjà acceptées vont tout de même jusqu’au bout et sont facturées. Voir Authentification.

Vérifier que tout fonctionne

Posez ces trois questions dans une nouvelle conversation, dans cet ordre :

1. « Vérifie l’état du service SpicyAPI. » Cette question utilise spicyapi_service_status, qui ne demande aucune clé : si elle fonctionne, le serveur est correctement installé.
2. « Quel est mon solde SpicyAPI ? » Cette question utilise spicyapi_balance_get. Si elle fonctionne, votre clé parvient bien au serveur.
3. « Quels outils SpicyAPI as-tu à ta disposition ? » L’assistant doit lister 15 outils dont le nom commence par spicyapi_.

Aucune de ces questions ne coûte quoi que ce soit. Si l’une d’elles échoue, voir Dépannage.

Essayez : exemples de conversations

Copiez l’un de ces messages dans votre assistant. Les descriptions indiquent quels outils il utilise habituellement (les assistants varient, et l’ordre exact peut donc changer) et à quel endroit précis il s’arrête pour vous demander votre accord.

Consulter votre solde et vos dépenses

Combien me reste-t-il sur mon solde SpicyAPI, et combien ai-je dépensé cette semaine ?

L’assistant appelle spicyapi_balance_get et spicyapi_usage_get. Les deux sont gratuits et en lecture seule : aucune confirmation n’est donc demandée. Dans le solde, held désigne l’argent réservé par des tâches encore en cours.

Trouver et comparer des modèles

Trouve des modèles SpicyAPI capables de transformer une image fixe en vidéo, et compare ce que coûterait un clip de 5 secondes avec chacun d’eux.

L’assistant appelle spicyapi_models_list (filtré sur les modèles vidéo qui prennent une image), peut appeler spicyapi_model_get pour obtenir les détails, et peut appeler spicyapi_task_quote une fois par candidat pour obtenir le prix exact avec vos réglages. Les devis sont gratuits et ne créent rien : il n’y a donc aucune confirmation. La réponse est un comparatif dans lequel vous pouvez choisir.

Générer une image

Utilise SpicyAPI pour générer une image carrée d’un restaurant de ramen éclairé au néon, par une nuit pluvieuse. Choisis un modèle d’image peu coûteux et donne-moi le lien quand c’est prêt.

1. spicyapi_models_list pour choisir un modèle, et spicyapi_model_get si l’assistant a besoin des champs qu’accepte ce modèle.
2. spicyapi_task_create. C’est ici que l’assistant s’arrête. Votre application affiche une confirmation avec le modèle, le montant estimé, le montant maximal et l’heure d’expiration du devis. Rien n’est facturé tant que vous n’avez pas confirmé.
3. Une fois que vous avez confirmé, la tâche démarre et spicyapi_task_wait attend qu’elle se termine.
4. L’assistant vous donne le lien du résultat, tiré de la tâche terminée.

Transformer une photo de votre ordinateur en vidéo

Transforme la photo /Users/me/Desktop/portrait.jpg en une vidéo de 5 secondes où la caméra avance lentement.

Sous Windows, indiquez le chemin sous la forme C:\Users\me\Desktop\portrait.jpg.

1. spicyapi_upload_file téléverse la photo et renvoie une adresse spicy:// qui la désigne. Le téléversement est gratuit et ne demande pas de confirmation, mais il envoie bel et bien ce fichier à SpicyAPI : donnez donc le chemin exact du fichier que vous visez.
2. spicyapi_models_list / spicyapi_model_get pour choisir un modèle image-vers-vidéo et voir ses options.
3. spicyapi_task_create : l’assistant s’arrête ici pour vous demander confirmation, en affichant le prix.
4. spicyapi_task_wait. Une vidéo prend souvent plusieurs minutes ; chaque attente dure au plus cinq minutes, si bien que l’assistant peut attendre plusieurs fois, ou que vous pouvez lui demander des nouvelles de la tâche plus tard.

Retrouver une tâche antérieure

Montre-moi mes tâches SpicyAPI des trois derniers jours qui ont échoué, et dis-moi pourquoi.

L’assistant appelle spicyapi_tasks_list avec un filtre sur l’état échoué, puis spicyapi_task_get sur les tâches qui vous intéressent pour lire l’erreur. Les tâches échouées ou expirées libèrent normalement toute la réservation. Certains refus de contenu sont facturés au devis accepté, uniquement si la page du modèle indique explicitement cette exception. Consultez settled et cost pour connaître le montant final. Si vous dites ensuite « relance celle-là », il appelle spicyapi_task_retry, qui s’arrête pour vous demander confirmation, car une relance est une nouvelle tâche payante.

Récupérer le fichier de résultat

Donne-moi le lien de téléchargement de ma dernière vidéo SpicyAPI.

L’assistant trouve la tâche avec spicyapi_tasks_list, puis la lit avec spicyapi_task_get, qui inclut des liens de résultat prêts à l’emploi. Ouvrez le lien dans un navigateur pour télécharger le fichier. Les liens ont une durée de vie courte : si l’un d’eux a expiré, redemandez-le et l’assistant en récupère un neuf.

Le serveur MCP n’enregistre pas de fichiers sur votre ordinateur de lui-même. Les assistants qui savent aussi exécuter des commandes, comme Claude Code ou Codex, peuvent télécharger le lien dans un dossier pour vous si vous le leur demandez.

Référence des outils

Chaque outil, ce qu’il prend et ce qu’il renvoie. Les montants sont toujours des dollars américains écrits sous forme de texte décimal exact, sans signe $, par exemple "0.08". Les dates sont en UTC.

Vérifier le service et la documentation

spicyapi_service_status

Vérifie que l’API publique de SpicyAPI est joignable et en bonne santé. L’outil ne demande aucune clé API, ne coûte rien et ne pose aucune question. C’est un outil de diagnostic : l’assistant n’a pas besoin de le lancer avant de créer une tâche.

Paramètres : aucun.

Renvoie : operational (true ou false), les vérifications individuelles health et readiness avec leur statut HTTP, et checkedAt.

spicyapi_docs_search

Cherche dans un index des pages de documentation SpicyAPI intégré au serveur, et renvoie les titres, les résumés et les liens correspondants. L’outil ne demande aucune clé et n’effectue aucune requête réseau.

Renvoie : une liste d’entrées, chacune avec slug, title, summary, keywords et url. Les liens pointent vers ce site de documentation, sous la forme https://docs.spicyapi.ai/docs/retention. Quand rien ne correspond, la liste est vide.

Parcourir les modèles

spicyapi_models_list

Liste les modèles que votre clé API peut appeler, avec des prix qui incluent déjà toute remise applicable à votre compte. Gratuit et en lecture seule.

Renvoie : total et items. Chaque élément comprend model (l’identifiant exact à utiliser), displayName, provider, modality, tasks, enabled et available, availability, une liste pricing (chaque entrée a une étiquette de niveau, une unit parmi per_image, per_second, per_request ou per_1k_tokens, et un price en USD), startingPrice, taskTimeoutSeconds, ainsi que inputSchema et examples si vous les demandez.

Certains réglages, comme la résolution ou la durée, modifient le prix. La liste des prix sert à comparer ; le montant exact d’une requête précise vient d’un devis.

spicyapi_model_get

Renvoie un modèle en entier : ses entrées acceptées (inputSchema, une description lisible par une machine de chaque champ, de son type, de ses valeurs autorisées et de ses valeurs par défaut), ses prix, sa disponibilité et ses exemples. Gratuit et en lecture seule.

Renvoie : les mêmes champs qu’un élément de spicyapi_models_list, avec toujours inputSchema.

Votre compte

spicyapi_balance_get

Affiche votre solde. Gratuit et en lecture seule. Inutile avant de créer une tâche : la création vérifie elle-même les fonds.

Paramètres : aucun.

Renvoie : available, held (réservé par des tâches encore en cours) et total, en USD. La réponse peut aussi inclure un détail funding des fonds prépayés, des dotations promotionnelles et d’une éventuelle ligne de crédit approuvée ; voir Facturation.

spicyapi_usage_get

Indique ce qu’a fait cette clé API : combien de tâches, combien ont réussi ou échoué, et les dépenses réglées, regroupées par jour et par modèle. Gratuit et en lecture seule. L’outil ne couvre que la clé de votre configuration, pas votre compte entier, et ce n’est pas votre solde.

Renvoie : from, to, currency, totalCalls, totalSpend, ainsi que des listes days et models avec calls, succeeded, failed et spend. Seuls les montants réglés sont comptés ; l’argent encore réservé par des tâches en cours ne l’est pas, et un règlement tardif peut modifier un jour antérieur.

Tâches

spicyapi_tasks_list

Liste les tâches créées avec cette clé API, des plus récentes aux plus anciennes : pratique pour retrouver une tâche après avoir fermé la conversation. L’outil n’affiche que des métadonnées : ni prompts, ni entrées, ni liens de résultat. Gratuit et en lecture seule.

Renvoie : items (chacun avec taskId, model, state, cost, settled, createdAt, deadlineAt et, une fois la tâche terminée, completedAt), hasMore et nextCursor. cost n’est définitif que lorsque settled vaut true.

spicyapi_task_get

Ouvre une tâche créée avec cette clé API. Gratuit et en lecture seule.

Renvoie : taskId, model, state, cost, settled, createdAt, completedAt et, selon la tâche :

• output.assets : les résultats. Chaque fichier prêt a une url que vous pouvez ouvrir directement, avec son expiresAt, son type mime et sa taille ou sa durée. Un fichier marqué pending est encore en cours de stockage : redemandez la tâche dans quelques secondes. Un fichier marqué unavailable a définitivement disparu.
• errorCode et errorMessage quand la tâche a échoué ; les codes sont listés dans Erreurs.
• input : ce qui a été envoyé, jusqu’à la fin de la durée de conservation du prompt.
• contentState (present, expired ou purged) et retention, qui indique quand les résultats et les prompts seront supprimés.
• sourceTaskId quand cette tâche est une relance.

Un identifiant de tâche qui n’existe pas et un identifiant qui appartient à quelqu’un d’autre renvoient tous deux « not found ».

spicyapi_task_wait

Consulte une tâche à plusieurs reprises jusqu’à ce qu’elle se termine ou que le temps d’attente soit écoulé, puis la renvoie. Gratuit et en lecture seule. Quand le temps d’attente est écoulé, la tâche n’est ni annulée ni mise en échec : elle continue de s’exécuter, et vous pouvez attendre de nouveau ou la consulter plus tard.

Renvoie : la tâche terminée, sous la même forme que spicyapi_task_get. Si le temps s’écoule avant, l’outil indique que la tâche ne s’est pas terminée dans ce délai.

Fichiers

spicyapi_upload_file

Lit un fichier sur votre ordinateur, le téléverse sur SpicyAPI, finalise le téléversement et renvoie une adresse spicy:// utilisable dans l’entrée d’un modèle, le tout en un seul appel, sans seconde étape. Gratuit et sans demande de confirmation ; mais l’outil envoie bel et bien le fichier, il n’est donc pas en lecture seule.

Les fichiers déjà en ligne à une adresse https:// publique n’ont pas besoin d’être téléversés : l’assistant peut transmettre cette adresse directement au modèle, si le modèle accepte une URL.

Fichiers acceptés : images JPEG, PNG, WebP et GIF jusqu’à 10 MiB ; vidéo MP4 et WebM et audio MP3 et WAV jusqu’à 90 MiB et 600 secondes. Un modèle peut fixer ses propres limites, plus strictes.

Quels dossiers : par défaut, seuls les fichiers situés dans votre dossier personnel peuvent être lus. Voir Fichiers locaux.

Renvoie : uri (l’adresse spicy://), fileId, bytes, contentType, sha256, width / height / durationSeconds quand ils sont connus, et expiresAt. L’adresse est utilisable pendant un jour par défaut.

Le téléversement est déjà finalisé quand cet outil rend la main : il n’y a pas d’étape de validation (« commit ») séparée à lancer. Le serveur n’a pas d’outil pour finaliser un téléversement commencé par un autre programme ; un code qui téléverse en plusieurs étapes le finalise avec commitUploadedFile du SDK.

spicyapi_download_url_create

Émet un nouveau lien de téléchargement signé pour un résultat de l’une de vos tâches. Gratuit. Généralement inutile : spicyapi_task_get et spicyapi_task_wait incluent déjà des liens prêts, et redemander la tâche les renouvelle.

Renvoie : key, url et expiresAt. Le lien fonctionne pendant 20 minutes et ne peut pas être révoqué une fois émis : ne le partagez pas et ne le stockez pas. Voir Médias.

Prix, création et suppression

spicyapi_task_quote

Calcule le prix exact d’une requête précise sans rien lancer et sans réserver d’argent. Gratuit et en lecture seule. L’assistant s’en sert pour comparer des options ; il n’en a pas besoin avant de créer une tâche, car la création obtient son propre devis.

Renvoie : quoteId, model, estimatedCost, maxCharge, currency, quantity, unit et expiresAt. Un devis est valable cinq minutes, et uniquement pour cette requête exacte.

spicyapi_task_create

Lance une génération. Coûte de l’argent et vous demande toujours votre accord au préalable.

Ce qui se passe, dans l’ordre :

1. Le serveur obtient un devis exact pour la requête. Un devis est gratuit : il ne crée rien et ne réserve aucun argent.
2. Votre application vous affiche une confirmation avec le modèle, le montant estimé, le montant maximal, l’heure d’expiration du devis et une clé d’idempotence (une référence qui empêche de facturer deux fois la même requête).
3. Si vous refusez, aucune tâche n’est créée et aucun argent n’est réservé ni facturé. La seule requête envoyée jusque-là est le devis gratuit de l’étape 1.
4. Si vous confirmez, SpicyAPI vérifie les entrées, le prix, les autorisations de votre clé et vos fonds, réserve le montant estimé et lance la tâche.

Cela nécessite une application capable d’afficher des questions de confirmation (l’elicitation du MCP). Dans une application qui en est incapable, l’outil échoue à l’étape 2 : le devis gratuit a été récupéré, et rien d’autre ne s’est produit. Voir Avant de commencer.

Renvoie : taskId, state (normalement queued), estimatedCost et l’idempotencyKey utilisée. La tâche s’exécute ensuite d’elle-même ; utilisez spicyapi_task_wait ou spicyapi_task_get pour récupérer le résultat.

Si la connexion coupe après votre confirmation, l’erreur contient la clé d’idempotence. Demandez à l’assistant de réessayer avec cette même clé, sans changer le modèle ni les réglages, plutôt que de repartir de zéro : il peut vous être demandé de confirmer de nouveau, mais SpicyAPI renvoie la tâche d’origine au lieu d’en facturer une seconde. Une nouvelle clé créerait une seconde tâche payante, et des réglages modifiés sous la même clé sont refusés.

spicyapi_task_retry

Crée une nouvelle tâche, facturée séparément, à partir d’une tâche failed ou expired. La tâche d’origine reste telle quelle. Coûte de l’argent et vous demande toujours votre accord au préalable.

Renvoie : le nouveau taskId, sourceTaskId (la tâche d’origine), state, estimatedCost et idempotencyKey.

La relance utilise le prix actuel du modèle, et les vérifications en vigueur sur les entrées, les autorisations et les fonds s’appliquent de nouveau. Sa confirmation n’affiche pas de prix : si vous voulez le connaître d’abord, demandez à l’assistant un devis pour le même modèle et les mêmes réglages avec spicyapi_task_quote avant de relancer.

Une relance réutilise l’entrée d’origine telle quelle : lisez donc d’abord l’errorCode de la tâche échouée.

• rate_limited, upstream_unavailable, timeout ou upstream_failed : une relance après une courte pause vaut la peine.
• generation_failed : modifiez le prompt ou l’image et lancez plutôt une nouvelle tâche ; la même entrée échoue généralement de la même façon.
• invalid_asset : téléversez de nouveau le fichier et lancez une nouvelle tâche avec la nouvelle adresse spicy:// ; une relance réutiliserait l’ancien fichier.
• content_rejected, invalid_request ou unsupported_combination : ne relancez pas sans modification. Changez le prompt, les réglages ou le modèle, et lancez une nouvelle tâche.

La liste complète se trouve dans Erreurs.

spicyapi_task_purge

Supprime définitivement le contenu stocké d’une tâche terminée : les médias générés, le résultat (les données de résultat stockées), le prompt et les autres textes d’entrée. L’opération est irréversible et vous demande toujours votre accord au préalable. Elle ne coûte rien, et ne rembourse rien.

• Seules les tâches terminées (succeeded, failed, expired ou un ancien canceled) peuvent être détruites. Une tâche acceptée ne peut pas être annulée et il n’existe pas d’API d’annulation : pour une tâche queued ou running, attendez qu’elle se termine (spicyapi_task_wait), puis détruisez son contenu.
• Téléchargez d’abord tout ce que vous voulez garder.
• L’enregistrement de facturation reste : l’écriture comptable, le montant facturé, le modèle, l’état, les horodatages et l’identifiant de requête restent visibles ensuite.
• Détruire de nouveau une tâche déjà détruite est sans conséquence.

Renvoie : taskId, contentState (purged une fois la suppression programmée), purgedAt, contentRemovedBy et billingRetained: true. L’outil ne renvoie volontairement aucun lien. La suppression physique des fichiers se termine normalement en moins d’une minute ; voir Conservation et destruction.

Ressources et prompt

En plus des outils, le serveur propose deux ressources en lecture seule et un prompt. Les applications les affichent à des endroits différents, et beaucoup de gens n’en ont jamais besoin.

Coûts, confirmation et sécurité

À quoi ressemble la confirmation

Quand l’assistant lance une tâche, votre application affiche une question envoyée par le serveur SpicyAPI. La formulation ressemble à ceci (les montants sont des exemples) :

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…

Le montant estimé et le montant maximal affichent actuellement le même nombre : l’estimation est le montant réservé au démarrage de la tâche, et la tâche n’est jamais facturée plus que cette réservation.

La façon de répondre dépend de l’application : en général, une case à cocher ou un interrupteur confirm, plus un bouton pour accepter et un autre pour refuser. Cochez confirm et acceptez pour continuer. Refuser ou annuler met fin à l’appel d’outil, et le message indique ce qui s’est produit et ce qui ne s’est pas produit :

Répondez dans les cinq minutes. Le devis est valable cinq minutes. S’il a expiré au moment où vous confirmez, la création échoue avec l’erreur 40901 et rien n’est facturé ; demandez à l’assistant de réessayer pour obtenir un nouveau devis.

La relance affiche une question similaire, sans prix. La destruction indique que la suppression est irréversible et que les enregistrements de facturation sont conservés.

Pourquoi l’assistant ne peut pas la contourner

• La question vous est adressée, pas à l’IA. Le serveur l’envoie à votre application grâce à la fonctionnalité d’elicitation du MCP, et l’application vous l’affiche. L’assistant n’a aucun moyen d’y répondre.
• Votre réponse est liée à cette requête précise. La confirmation porte sur le modèle et les réglages qui vous ont été montrés. Si l’assistant modifie quoi que ce soit entre la question et votre réponse, le serveur refuse avec « confirmed request state does not match the current tool arguments » et rien n’est créé.
• Gardez ce fonctionnement. Si votre application propose un réglage qui accepte automatiquement les questions des serveurs MCP, laissez-le désactivé pour SpicyAPI. Un assistant ou un réglage qui confirme à votre place supprime le seul contrôle des dépenses sur ce chemin.
• Les applications sans prise en charge de la confirmation ne peuvent rien dépenser. Dans celles-ci, lancer, relancer et détruire renvoient simplement une erreur ; à ce stade, le lancement d’une tâche n’a récupéré que son devis gratuit. Voir Avant de commencer.

Ce que vous payez

• Les prix sont en dollars américains. Les estimations, les montants facturés et les soldes sont des montants exacts en dollars.
• Vous n’êtes jamais facturé plus que le maximum que vous avez confirmé. Quand une tâche démarre, son montant estimé est réservé (affiché comme « held »). Quand elle réussit, vous payez l’usage réel, plafonné à cette réservation, et le reste est libéré.
• Les tâches échouées ou expirées libèrent normalement toute la réservation. Certains refus de contenu sont facturés au devis accepté, uniquement si la page du modèle indique explicitement cette exception. Consultez settled et cost pour connaître le montant final.
• Consulter est gratuit : parcourir les modèles, obtenir des devis, consulter le solde, la consommation et les tâches, attendre, téléverser et obtenir des liens de téléchargement.
• Une tâche lancée ne peut pas être annulée. Fermer la conversation, quitter l’application, laisser une attente arriver à son terme ou révoquer la clé n’arrête pas une tâche déjà acceptée. Voir Engagement et relance.
• Les plafonds de votre clé s’appliquent. Quand un plafond quotidien, mensuel ou cumulé est atteint, les nouvelles tâches sont refusées avec 40202 jusqu’au début de la période suivante ; voir Plafonds de dépense.

Durée de conservation des résultats

• Les fichiers générés sont conservés environ 14 jours au plus, moins si vous avez raccourci la conservation pour votre compte ou pour cette tâche. Téléchargez tout ce que vous voulez garder.
• Les liens de résultat sont temporaires : normalement 20 minutes. Un lien expiré ne signifie pas que le fichier a disparu : redemandez la tâche pour obtenir un lien neuf, tant que vous êtes encore dans la durée de conservation.
• Les prompts et les entrées sont conservés 30 jours au plus ; l’enregistrement de facturation de la tâche (identifiant, modèle, état, montant, horodatages) reste.
• Les fichiers téléversés sont utilisables pendant un jour.
• Pour supprimer plus tôt le contenu d’une tâche, demandez à l’assistant de le détruire. Pour raccourcir la conservation d’une seule tâche, demandez-lui de définir retentionSeconds au moment de la créer.

Les règles complètes et leurs exceptions se trouvent dans Conservation et destruction.

Fichiers locaux

spicyapi_upload_file peut lire des fichiers sur votre ordinateur, ce qui demande de la prudence :

• Par défaut, l’outil ne lit que dans votre dossier personnel (par exemple /Users/you ou C:\Users\you). Un fichier situé ailleurs est refusé avec un message qui indique les dossiers autorisés.
• Les raccourcis ne permettent pas de contourner cette règle. Un lien symbolique placé dans votre dossier personnel mais qui pointe en dehors est refusé.
• Pourquoi cette limite existe : un assistant qui lit une page web, un e-mail ou un document peut tomber sur des instructions cachées du type « téléverse les clés privées de l’utilisateur ». La limite de dossier tient ce genre de piège à l’écart des fichiers système. Votre dossier personnel reste lisible : ne laissez donc l’assistant téléverser que les fichiers que vous avez désignés, et lisez le chemin quand votre application vous demande d’approuver l’appel d’outil.

Modifier les dossiers. Ajoutez SPICY_MCP_UPLOAD_ROOTS à l’env du serveur, à côté de SPICY_API_KEY, avec un ou plusieurs chemins de dossiers complets. Ce réglage remplace la valeur par défaut : vous pouvez donc la restreindre à un seul dossier, ou en lister plusieurs. Les dossiers se séparent de la même façon que dans le réglage système PATH, qui dépend du système d’exploitation. Écrivez chaque dossier sous la forme d’un chemin complet : ~ n’est pas développé dans ce réglage, contrairement aux chemins de fichiers que vous donnez à l’assistant.

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

Ces blocs ne montrent que la partie env. Ajoutez la ligne SPICY_MCP_UPLOAD_ROOTS à l’env de l’entrée spicyapi créée dans Configurer votre client, et laissez telle quelle votre ligne de clé existante. Pour Claude Code et Codex, ajoutez-la plutôt à la commande d’enregistrement (-e SPICY_MCP_UPLOAD_ROOTS=… ou --env SPICY_MCP_UPLOAD_ROOTS=…), après avoir supprimé le serveur. Redémarrez ensuite l’application. Un dossier qui n’existe pas ne correspond simplement à rien : si les téléversements sont refusés après cette modification, vérifiez l’orthographe dans le message, qui liste les dossiers qu’utilise le serveur.

Mode HTTP : uniquement sur cet ordinateur

La plupart des applications démarrent le serveur elles-mêmes, comme ci-dessus. Quelques-unes préfèrent se connecter, par son adresse, à un serveur déjà en marche. Pour elles, le paquet contient un second programme, 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

Il affiche SpicyAPI MCP HTTP listening at http://127.0.0.1:8765/mcp. Indiquez cette adresse à votre application et faites-lui envoyer l’en-tête Authorization: Bearer suivi de votre SPICY_MCP_HTTP_TOKEN. http://127.0.0.1:8765/healthz répond {"ok":true} quand le serveur tourne.

« Boucle locale uniquement » (loopback) signifie que seuls les programmes de ce même ordinateur peuvent se connecter. Les autres appareils de votre réseau Wi-Fi et internet ne peuvent pas l’atteindre, et aucun réglage ne permet de l’ouvrir : toute autre adresse est refusée au démarrage. Les requêtes provenant de pages web d’autres sites sont également rejetées. Si vous avez besoin d’un serveur joignable depuis d’autres machines, ce n’est pas celui-ci.

Dépannage

Le code source

Le paquet est sous licence MIT et développé au grand jour sur github.com/spicyapi-ai/spicy-mcp. C’est là qu’on lit le code derrière chaque outil de cette page, qu’on signale un comportement qui s’écarte de ce qui est décrit ici et qu’on propose une modification.

Étapes suivantes