Servidor MCP

@spicyapi/mcp permite que el asistente de IA que ya usas —Claude, Cursor, VS Code, Codex, Windsurf, Gemini CLI y otros— trabaje con SpicyAPI por ti. Una vez configurado, puedes escribir «hazme un video de cinco segundos a partir de esta foto» y el asistente busca un modelo adecuado, te dice el precio, espera tu visto bueno, inicia el trabajo y te entrega el enlace al resultado.

No hace falta escribir código. Necesitas Node.js, una clave de API y unos diez minutos.

Qué es MCP, en pocas palabras

MCP (Model Context Protocol) es un estándar abierto para dar capacidades adicionales a los asistentes de IA. Piensa en él como un enchufe: un asistente compatible con MCP puede cargar «servidores», y cada servidor añade un conjunto de herramientas que el asistente puede usar mientras habla contigo.

@spicyapi/mcp es uno de esos servidores. Añade 15 herramientas de SpicyAPI. Esto es lo que pasa cuando pides algo:

1. Escribes un mensaje normal, por ejemplo «Genera una imagen de un faro al amanecer».
2. Tu asistente decide qué herramientas de SpicyAPI necesita y las llama.
3. El servidor —un pequeño programa que se ejecuta en tu propio equipo y que tu aplicación de asistente inicia automáticamente— envía esas solicitudes a SpicyAPI con tu clave de API.
4. Todo lo que cuesta dinero se detiene primero: tu aplicación te muestra el precio y te pide que confirmes. El asistente no puede responder a esa pregunta por ti.
5. Los resultados vuelven a la conversación y el asistente te los explica.

No hay nada que alojar ni que mantener en marcha. La aplicación del asistente inicia el servidor cuando lo necesita y lo detiene cuando la cierras.

Te conviene si ya usas un asistente de IA y quieres probar modelos, comparar precios o producir imágenes y videos sin escribir un programa. Los desarrolladores también lo usan para explorar el catálogo desde su editor antes de construir una integración.

No es la herramienta adecuada para una aplicación o un backend en producción (usa el SDK o la API HTTP), para lotes grandes sin supervisión (usa la CLI) ni para recibir respuestas de chat en streaming, token a token: el servidor MCP envía tareas y hace su seguimiento; para el chat, consulta Texto y streaming.

¿MCP, CLI, SDK o Skill?

SpicyAPI publica cuatro paquetes independientes. A la mayoría de la gente le basta con uno o dos.

Si tu aplicación no está escrita en TypeScript, la fila del SDK tiene otras cuatro opciones: Python, Go, PHP y Java.

Qué puede hacer tu asistente

Estas son las 15 herramientas que añade el servidor. Nunca las llamas por su nombre: pides las cosas con tus propias palabras y el asistente elige. Los nombres te sirven para leer qué ha hecho el asistente o cuando tu aplicación te pide que apruebes una llamada a una herramienta.

«Te pregunta antes» significa que es el propio servidor de SpicyAPI el que se detiene y pide confirmación: el asistente no puede saltárselo. Muchas aplicaciones también te preguntan antes de ejecutar cualquier herramienta; eso es un ajuste de la propia aplicación y no tiene nada que ver con esto.

Antes de empezar

node --version

Configura tu cliente

Todas las aplicaciones de abajo ejecutan el mismo comando: npx --yes --package=@spicyapi/mcp spicyapi-mcp. El primer arranque descarga el paquete, lo que puede tardar unos segundos.

Nunca necesitas ejecutar ese comando tú mismo: lo inicia la aplicación. Si lo ejecutas a mano, se queda esperando en silencio a que la aplicación le hable, lo que parece un cuelgue pero es normal. Pulsa Ctrl+C para detenerlo.

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

Cada aplicación decide dónde guarda su configuración y con qué formato, y las dos cosas cambian entre versiones. Cuando un paso de arriba ya no coincida con tu aplicación, manda la propia documentación de MCP de esa aplicación. Cualquier otra aplicación compatible con MCP puede usar los mismos command, args y env de arriba.

Mantén tu clave a salvo

Cualquiera que tenga tu clave puede gastar tu saldo. Unos cuantos hábitos la mantienen bajo control:

• Pon la clave solo en archivos de usuario, los de tu carpeta personal que aparecen arriba, nunca en un archivo dentro de un proyecto o de un repositorio. Si haces copia de tus archivos de configuración en un repositorio público de «dotfiles», deja estos fuera.
• No pegues nunca la clave en el chat. El asistente no la necesita; el servidor la lee de la configuración.
• Fija un límite diario en la clave, para que un error tenga techo.
• Si una clave se filtra, revócala en la página Claves de API y crea una nueva. La revocación surte efecto al instante; las tareas ya aceptadas terminan igualmente y se cobran igualmente. Consulta Autenticación.

Comprueba que funciona

Pregunta estas tres cosas en una conversación nueva, por este orden:

1. «Comprueba el estado del servicio de SpicyAPI»: usa spicyapi_service_status. No necesita clave, así que, si funciona, el servidor está bien instalado.
2. «¿Cuánto saldo tengo en SpicyAPI?»: usa spicyapi_balance_get. Si funciona, tu clave llega al servidor.
3. «¿Qué herramientas de SpicyAPI tienes?»: el asistente debería enumerar 15 herramientas cuyo nombre empieza por spicyapi_.

Nada de esto cuesta dinero. Si algo falla, consulta Solución de problemas.

Pruébalo: conversaciones de ejemplo

Copia cualquiera de estas en tu asistente. Las descripciones muestran qué herramientas suele usar —cada asistente es distinto, así que el orden exacto puede variar— y en qué punto exacto se detiene para preguntarte.

Consultar tu saldo y tu gasto

¿Cuánto saldo tengo en SpicyAPI y cuánto he gastado esta semana?

El asistente llama a spicyapi_balance_get y a spicyapi_usage_get. Las dos son gratuitas y de solo lectura, así que nada pide confirmación. En el saldo, «held» (retenido) es el dinero apartado por tareas que todavía están en marcha.

Buscar y comparar modelos

Busca modelos de SpicyAPI que conviertan una imagen fija en un video y compara cuánto costaría un clip de 5 segundos en cada uno.

El asistente llama a spicyapi_models_list (filtrando los modelos de video que aceptan una imagen), puede llamar a spicyapi_model_get para ver detalles y puede llamar a spicyapi_task_quote una vez por candidato para obtener el precio exacto con tus ajustes. Las cotizaciones son gratuitas y no crean nada, así que no hay confirmación. La respuesta es una comparación entre la que puedes elegir.

Generar una imagen

Usa SpicyAPI para generar una imagen cuadrada de un local de ramen iluminado con neones en una noche de lluvia. Elige un modelo de imagen barato y dame el enlace cuando esté listo.

1. spicyapi_models_list para elegir un modelo, y spicyapi_model_get si necesita los campos que acepta ese modelo.
2. spicyapi_task_create. Aquí es donde se detiene. Tu aplicación muestra una confirmación con el modelo, el cargo estimado, el cargo máximo y cuándo caduca la cotización. No se cobra nada hasta que confirmas.
3. Después de que confirmes, la tarea empieza y spicyapi_task_wait espera a que termine.
4. El asistente te da el enlace al resultado de la tarea terminada.

Convertir en video una foto de tu equipo

Convierte la foto que está en /Users/me/Desktop/portrait.jpg en un video de 5 segundos en el que la cámara se acerque lentamente.

En Windows, da la ruta como C:\Users\me\Desktop\portrait.jpg.

1. spicyapi_upload_file sube la foto y devuelve una dirección spicy:// para ella. Subir es gratuito y no pide confirmación, pero sí envía ese archivo a SpicyAPI, así que da la ruta exacta del archivo al que te refieres.
2. spicyapi_models_list / spicyapi_model_get para elegir un modelo de imagen a video y ver sus opciones.
3. spicyapi_task_create: aquí se detiene para que confirmes, y te muestra el precio.
4. spicyapi_task_wait. Los videos suelen tardar varios minutos; cada espera dura como mucho cinco, así que puede que el asistente espere más de una vez, o puedes preguntar por la tarea más tarde.

Encontrar una tarea anterior

Enséñame mis tareas de SpicyAPI de los últimos tres días que fallaron y dime por qué.

El asistente llama a spicyapi_tasks_list con un filtro de estado fallido y después a spicyapi_task_get con las que te interesen, para leer el error. Las tareas fallidas o vencidas normalmente liberan toda la retención. Algunos rechazos de contenido se cobran al precio aceptado, solo si la página del modelo indica expresamente esta excepción. Consulta settled y cost para conocer el importe final. Si luego dices «reintenta esa», llama a spicyapi_task_retry, que se detiene para que confirmes, porque un reintento es una tarea de pago nueva.

Obtener el archivo del resultado

Dame el enlace de descarga de mi último video de SpicyAPI.

El asistente encuentra la tarea con spicyapi_tasks_list y después la lee con spicyapi_task_get, que incluye enlaces al resultado listos para usar. Abre el enlace en un navegador para descargarlo. Los enlaces duran poco: si uno ha caducado, vuelve a pedirlo y el asistente obtiene uno nuevo.

El servidor MCP no guarda archivos en tu equipo por su cuenta. Los asistentes que además pueden ejecutar comandos —Claude Code o Codex, por ejemplo— pueden descargar el enlace en una carpeta por ti si se lo pides.

Referencia de herramientas

Cada herramienta, qué recibe y qué devuelve. Los importes de dinero son siempre dólares estadounidenses escritos como texto decimal exacto sin el signo $, por ejemplo "0.08". Las fechas están en UTC.

Comprobar el servicio y la documentación

spicyapi_service_status

Comprueba si la API pública de SpicyAPI responde y funciona bien. No necesita clave de API, no cuesta nada y no pregunta nada. Es una herramienta de diagnóstico: el asistente no necesita ejecutarla antes de crear una tarea.

Parámetros: ninguno.

Devuelve: operational (true o false), las comprobaciones individuales health y readiness con su estado HTTP, y checkedAt.

spicyapi_docs_search

Busca en un índice de páginas de documentación de SpicyAPI que viene incluido en el servidor, y devuelve los títulos, resúmenes y enlaces que coinciden. No necesita clave y no hace ninguna solicitud de red.

Devuelve: una lista de entradas, cada una con slug, title, summary, keywords y url. Los enlaces apuntan a este sitio de documentación, con la forma https://docs.spicyapi.ai/docs/retention. Si no hay coincidencias, la lista está vacía.

Explorar modelos

spicyapi_models_list

Lista los modelos que tu clave de API puede llamar, con precios que ya incluyen cualquier descuento de tu cuenta. Gratuita y de solo lectura.

Devuelve: total e items. Cada elemento incluye model (el ID exacto que hay que usar), displayName, provider, modality, tasks, enabled y available, availability, una lista pricing (cada entrada tiene una etiqueta de nivel, una unit que puede ser per_image, per_second, per_request o per_1k_tokens, y un price en USD), startingPrice, taskTimeoutSeconds, e inputSchema / examples cuando se piden.

Algunos ajustes, como la resolución o la duración, cambian el precio. La lista de precios sirve para comparar; el cargo exacto de una solicitud concreta sale de una cotización.

spicyapi_model_get

Devuelve un modelo completo: las entradas que acepta (inputSchema, una descripción legible por máquina de cada campo, su tipo, sus valores permitidos y sus valores predeterminados), los precios, la disponibilidad y los ejemplos. Gratuita y de solo lectura.

Devuelve: los mismos campos que un elemento de spicyapi_models_list, siempre con inputSchema.

Tu cuenta

spicyapi_balance_get

Muestra tu saldo. Gratuita y de solo lectura. No hace falta antes de crear una tarea: la creación ya comprueba los fondos.

Parámetros: ninguno.

Devuelve: available, held (lo retenido por tareas que todavía están en marcha) y total, en USD. También puede incluir un desglose funding con los fondos prepagados, los bonos promocionales y cualquier línea de crédito aprobada; consulta Facturación.

spicyapi_usage_get

Informa de lo que hizo esta clave de API: cuántas tareas, cuántas salieron bien o fallaron, y el gasto liquidado, agrupado por día y por modelo. Gratuita y de solo lectura. Solo cubre la clave de tu configuración, no toda tu cuenta, y no es tu saldo.

Devuelve: from, to, currency, totalCalls, totalSpend, y las listas days y models con calls, succeeded, failed y spend. Solo se cuentan los cargos liquidados; el dinero que siguen reteniendo las tareas en marcha no, y una liquidación tardía puede actualizar un día anterior.

Tareas

spicyapi_tasks_list

Lista las tareas creadas con esta clave de API, de la más reciente a la más antigua; sirve para encontrar una tarea después de cerrar el chat. Solo muestra metadatos: ni prompts, ni entradas, ni enlaces a resultados. Gratuita y de solo lectura.

Devuelve: items (cada uno con taskId, model, state, cost, settled, createdAt, deadlineAt y, cuando ha terminado, completedAt), hasMore y nextCursor. cost solo es definitivo cuando settled vale true.

spicyapi_task_get

Abre una tarea creada con esta clave de API. Gratuita y de solo lectura.

Devuelve: taskId, model, state, cost, settled, createdAt, completedAt y, según la tarea:

• output.assets: los resultados. Cada archivo listo tiene una url que puedes abrir directamente, con su expiresAt, su tipo mime y su tamaño o duración. Un archivo marcado como pending todavía se está guardando: vuelve a preguntar en unos segundos. Uno marcado como unavailable se ha perdido para siempre.
• errorCode y errorMessage cuando la tarea falló; los códigos están en Errores.
• input: lo que se envió, hasta que termina el plazo de conservación del prompt.
• contentState (present, expired o purged) y retention, que indica cuándo se eliminarán los resultados y los prompts.
• sourceTaskId cuando esta tarea es un reintento.

Un ID de tarea que no existe y uno que pertenece a otra persona devuelven los dos «not found».

spicyapi_task_wait

Consulta una tarea una y otra vez hasta que termina o se agota la espera, y después la devuelve. Gratuita y de solo lectura. Que se agote el tiempo de espera no cancela la tarea ni la hace fallar: sigue en marcha, y puedes volver a esperar o consultarla más tarde.

Devuelve: la tarea terminada, con la misma forma que spicyapi_task_get. Si antes se agota el tiempo, la herramienta informa de que la tarea no terminó en ese tiempo.

Archivos

spicyapi_upload_file

Lee un archivo de tu equipo, lo sube a SpicyAPI, completa la subida y devuelve una dirección spicy:// que se puede poner en la entrada de un modelo, todo en una sola llamada y sin segundo paso. Es gratuita y no pide confirmación, pero sí envía el archivo, así que no es de solo lectura.

Los archivos que ya están en internet con una dirección pública https:// no necesitan subida: el asistente puede pasar esa dirección directamente al modelo si el modelo acepta una URL.

Archivos admitidos: imágenes JPEG, PNG, WebP y GIF de hasta 10 MiB; video MP4 y WebM y audio MP3 y WAV de hasta 90 MiB y 600 segundos. Cada modelo puede fijar sus propios límites, más estrictos.

Qué carpetas: de forma predeterminada, solo se pueden leer archivos dentro de tu carpeta personal. Consulta Archivos locales.

Devuelve: uri (la dirección spicy://), fileId, bytes, contentType, sha256, width / height / durationSeconds cuando se conocen, y expiresAt. De forma predeterminada, la dirección se puede usar durante un día.

La subida ya está completada cuando la herramienta responde, así que no hay ningún paso de «commit» aparte que ejecutar. El servidor no tiene ninguna herramienta para completar una subida que haya empezado otro programa; el código que sube archivos en pasos separados la completa con commitUploadedFile del SDK.

spicyapi_download_url_create

Emite un enlace de descarga firmado nuevo para un resultado de una de tus tareas. Gratuita. Normalmente no hace falta: spicyapi_task_get y spicyapi_task_wait ya incluyen enlaces listos, y volver a pedir la tarea los renueva.

Devuelve: key, url y expiresAt. El enlace funciona durante 20 minutos y no se puede revocar una vez emitido, así que no lo compartas ni lo guardes. Consulta Carga y descarga de medios.

Cotizar, crear y borrar

spicyapi_task_quote

Calcula el precio exacto de una solicitud concreta sin iniciar nada ni retener dinero. Gratuita y de solo lectura. El asistente la usa para comparar opciones; no la necesita antes de crear una tarea, porque la creación obtiene su propia cotización.

Devuelve: quoteId, model, estimatedCost, maxCharge, currency, quantity, unit y expiresAt. Una cotización es válida durante cinco minutos y solo para esa solicitud exacta.

spicyapi_task_create

Inicia una generación. Cuesta dinero y siempre te pregunta antes.

Qué pasa, por orden:

1. El servidor obtiene una cotización exacta de la solicitud. Una cotización es gratuita: no crea nada ni retiene dinero.
2. Tu aplicación te muestra una confirmación con el modelo, el cargo estimado, el cargo máximo, cuándo caduca la cotización y una clave de idempotencia (una referencia que impide que la misma solicitud se cobre dos veces).
3. Si la rechazas, no se crea ninguna tarea y no se retiene ni se cobra dinero. La única solicitud enviada hasta ese momento es la cotización gratuita del paso 1.
4. Si confirmas, SpicyAPI comprueba las entradas, el precio, los permisos de tu clave y tus fondos, retiene el importe estimado e inicia la tarea.

Hace falta una aplicación que pueda mostrar preguntas de confirmación (elicitation de MCP). En una aplicación que no puede, la herramienta falla en el paso 2: se obtuvo la cotización gratuita y no pasó nada más. Consulta Antes de empezar.

Devuelve: taskId, state (normalmente queued), estimatedCost y la idempotencyKey usada. A partir de ahí la tarea se ejecuta sola; usa spicyapi_task_wait o spicyapi_task_get para recoger el resultado.

Si la conexión se corta después de que confirmaras, el error incluye la clave de idempotencia. Pide al asistente que lo vuelva a intentar con esa misma clave y sin cambiar el modelo ni los ajustes, en lugar de empezar de cero: puede que se te pida confirmar otra vez, pero SpicyAPI devuelve la tarea original en lugar de cobrar una segunda. Una clave nueva crearía una segunda tarea de pago, y con la misma clave se rechazan los ajustes cambiados.

spicyapi_task_retry

Crea una tarea nueva y que se cobra aparte a partir de una que terminó como failed o expired. La tarea original se queda como estaba. Cuesta dinero y siempre te pregunta antes.

Devuelve: el nuevo taskId, sourceTaskId (la original), state, estimatedCost e idempotencyKey.

El reintento usa el precio actual del modelo, y se vuelven a hacer las comprobaciones actuales de entradas, permisos y fondos. Su confirmación no muestra ningún precio, así que, si quieres saberlo antes, pide al asistente que cotice el mismo modelo con los mismos ajustes mediante spicyapi_task_quote antes de reintentar.

Un reintento reutiliza la entrada original sin cambios, así que lee primero el errorCode de la tarea fallida:

• rate_limited, upstream_unavailable, timeout o upstream_failed: merece la pena un reintento tras una breve espera.
• generation_failed: cambia el prompt o la imagen e inicia una tarea nueva; la misma entrada suele fallar de la misma manera.
• invalid_asset: vuelve a subir el archivo e inicia una tarea nueva con la nueva dirección spicy://; un reintento reutilizaría el archivo antiguo.
• content_rejected, invalid_request o unsupported_combination: no reintentes sin cambios. Cambia el prompt, los ajustes o el modelo e inicia una tarea nueva.

La lista completa está en Errores.

spicyapi_task_purge

Borra para siempre el contenido guardado de una tarea terminada: los medios generados, el resultado (los datos guardados del resultado), el prompt y el resto del texto de entrada. No se puede deshacer y siempre te pregunta antes. No cuesta nada, y tampoco reembolsa nada.

• Solo se pueden purgar las tareas terminadas (succeeded, failed, expired o una antigua canceled). Una tarea aceptada no se puede cancelar y no existe ninguna API de cancelación, así que, con una tarea queued o running, espera a que termine (spicyapi_task_wait) y después púrgala.
• Descarga antes lo que quieras conservar.
• El registro de facturación se mantiene: el movimiento contable, el importe cobrado, el modelo, el estado, las marcas de tiempo y el ID de solicitud siguen visibles después.
• Volver a purgar una tarea ya purgada no causa ningún problema.

Devuelve: taskId, contentState (purged en cuanto el borrado queda programado), purgedAt, contentRemovedBy y billingRetained: true. A propósito, no devuelve ningún enlace. El borrado físico de los archivos suele completarse en menos de un minuto; consulta Conservación y destrucción.

Recursos y prompt

Además de las herramientas, el servidor ofrece dos recursos de solo lectura y un prompt. Cada aplicación los muestra en un sitio distinto, y mucha gente no los necesita nunca.

Costos, confirmación y seguridad

Cómo es la confirmación

Cuando el asistente inicia una tarea, tu aplicación muestra una pregunta del servidor de SpicyAPI. El texto es de este estilo (los importes son de ejemplo):

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…

Ahora mismo, el cargo estimado y el cargo máximo muestran la misma cifra: la estimación es el importe que se retiene cuando empieza la tarea, y a la tarea nunca se le cobra más que lo retenido.

La forma de responder depende de la aplicación: lo habitual es una casilla o un interruptor confirm más los botones Accept y Decline. Marca confirm y acepta para seguir adelante. Si rechazas o cancelas, la llamada a la herramienta termina y el mensaje indica qué ha pasado y qué no:

Responde en menos de cinco minutos. La cotización es válida durante cinco minutos. Si ya ha caducado cuando confirmas, la creación falla con el error 40901 y no se cobra nada; pide al asistente que lo vuelva a intentar para obtener una cotización nueva.

Al reintentar se muestra una pregunta parecida, sin precio. Al purgar se indica que el borrado no se puede deshacer y que los registros de facturación se conservan.

Por qué el asistente no puede saltársela

• La pregunta te llega a ti, no a la IA. El servidor la envía a tu aplicación mediante la función de elicitation de MCP, y la aplicación te la muestra a ti. El asistente no tiene forma de responderla.
• Tu respuesta queda ligada a esa solicitud exacta. La confirmación está vinculada al modelo y a los ajustes que se te mostraron. Si el asistente cambia algo entre la pregunta y tu respuesta, el servidor lo rechaza con "confirmed request state does not match the current tool arguments" y no se crea nada.
• Déjalo así. Si tu aplicación ofrece un ajuste que acepta automáticamente las preguntas de los servidores MCP, déjalo desactivado para SpicyAPI. Un asistente o un ajuste que confirma en tu nombre elimina el único control de gasto de este camino.
• Las aplicaciones sin confirmación no pueden gastar. En ellas, iniciar, reintentar y purgar simplemente devuelven un error; al iniciar una tarea, para entonces solo se ha obtenido su cotización gratuita. Consulta Antes de empezar.

Qué pagas

• Los precios están en dólares estadounidenses. Las estimaciones, los cargos y los saldos son importes exactos en dólares.
• Nunca se te cobra más que el máximo que confirmaste. Cuando una tarea empieza, su importe estimado queda retenido (aparece como «held»). Cuando sale bien, pagas el uso real, con ese importe retenido como tope, y lo que no se use se libera.
• Las tareas fallidas o vencidas normalmente liberan toda la retención. Algunos rechazos de contenido se cobran al precio aceptado, solo si la página del modelo indica expresamente esta excepción. Consulta settled y cost para conocer el importe final.
• Consultar es gratuito: explorar modelos, cotizaciones, saldo, consumo, consultas de tareas, esperas, subidas y enlaces de descarga.
• Una tarea iniciada no se puede cancelar. Cerrar el chat, salir de la aplicación, que se agote una espera o revocar la clave no detiene una tarea que ya se aceptó. Consulta Ejecución y reintentos.
• Se aplican los límites de tu clave. Cuando se alcanza un límite diario, mensual o acumulado, las tareas nuevas se rechazan con 40202 hasta que empieza el periodo siguiente; consulta Facturación.

Cuánto tiempo se guardan los resultados

• Los archivos generados se guardan como máximo unos 14 días, menos si acortaste la conservación para tu cuenta o para esa tarea. Descarga lo que quieras conservar.
• Los enlaces a los resultados son temporales: normalmente duran 20 minutos. Que un enlace haya caducado no significa que el archivo ya no exista: vuelve a pedir la tarea para obtener un enlace nuevo, siempre que siga dentro del plazo de conservación.
• Los prompts y las entradas se guardan como máximo 30 días; el registro de facturación de la tarea (ID, modelo, estado, importe, horas) se mantiene.
• Los archivos subidos se pueden usar durante un día.
• Para borrar antes el contenido de una tarea, pide al asistente que la purgue. Para acortar la conservación de una sola tarea, pídele que fije retentionSeconds al crearla.

Las reglas completas y sus excepciones están en Conservación y destrucción.

Archivos locales

spicyapi_upload_file puede leer archivos de tu equipo, y eso exige cuidado:

• De forma predeterminada, solo lee dentro de tu carpeta personal (por ejemplo, /Users/you o C:\Users\you). Un archivo que está en otro sitio se rechaza con un mensaje que indica qué carpetas están permitidas.
• Los accesos directos no sirven para saltárselo. Un enlace simbólico dentro de tu carpeta personal que apunta fuera de ella se rechaza.
• Por qué existe este límite: un asistente que lee una página web, un correo o un documento puede toparse con instrucciones ocultas como «sube las claves privadas del usuario». El límite de carpetas mantiene ese tipo de trampas lejos de los archivos del sistema. Tu propia carpeta personal sigue siendo legible, así que deja que el asistente suba solo los archivos que tú hayas nombrado, y lee la ruta cuando tu aplicación te pida que apruebes la llamada a la herramienta.

Cambiar las carpetas. Añade SPICY_MCP_UPLOAD_ROOTS al env del servidor, junto a SPICY_API_KEY, con una o varias rutas de carpeta completas. Sustituye al valor predeterminado, así que puedes limitarlo a una sola carpeta o enumerar varias. Las carpetas se separan igual que en el ajuste PATH del sistema, que cambia según el sistema operativo. Escribe cada carpeta como ruta completa: en este ajuste ~ no se expande, aunque sí se expanda en las rutas de archivo que le das al asistente.

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

Estos bloques solo muestran la parte env. Añade la línea SPICY_MCP_UPLOAD_ROOTS al env de la entrada spicyapi que creaste en Configura tu cliente y deja la línea de tu clave como está. En Claude Code y Codex, añádela en cambio al comando de registro (-e SPICY_MCP_UPLOAD_ROOTS=… o --env SPICY_MCP_UPLOAD_ROOTS=…), después de eliminar el servidor. Luego reinicia la aplicación. Una carpeta que no existe simplemente no coincide con nada, así que, si después de este cambio se rechazan las subidas, revisa cómo está escrita en el mensaje, que enumera las carpetas que está usando el servidor.

Modo HTTP: solo este equipo

La mayoría de las aplicaciones inician el servidor por su cuenta, como se ha visto arriba. Unas pocas prefieren conectarse, mediante una dirección, a un servidor que ya está en marcha. Para ellas, el paquete incluye un segundo programa, 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

Muestra SpicyAPI MCP HTTP listening at http://127.0.0.1:8765/mcp. Apunta tu aplicación a esa dirección y haz que envíe la cabecera Authorization: Bearer seguida de tu SPICY_MCP_HTTP_TOKEN. Mientras está en marcha, http://127.0.0.1:8765/healthz responde {"ok":true}.

«Solo loopback» significa que solo pueden conectarse los programas de este mismo equipo. Los demás dispositivos de tu wifi e internet no pueden llegar a él, y no hay ningún ajuste para abrirlo: cualquier otra dirección se rechaza al arrancar. También se rechazan las solicitudes que vienen de páginas web de otros sitios. Si necesitas un servidor al que se pueda llegar desde otras máquinas, este no es.

Solución de problemas

Código fuente

El paquete tiene licencia MIT y se desarrolla en abierto en github.com/spicyapi-ai/spicy-mcp. Ahí puedes leer el código detrás de cualquier herramienta de esta página, avisar de un comportamiento que no coincida con lo descrito o proponer un cambio.

Siguientes pasos