SpicyAPI MCP (spicyapi.ai)

@spicyapi/mcp

El servidor MCP local oficial para SpicyAPI. Permite que el asistente de IA que ya utilizas — Claude Desktop, Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI o cualquier cliente MCP — explore el catálogo de modelos en vivo, compare precios, cree tareas de generación y recoja resultados, con cada paso facturable confirmado por ti.

Este paquete instala spicyapi-mcp (stdio) y spicyapi-mcp-http (Streamable HTTP solo de loopback). No contiene la CLI ni la Agent Skill.

Guía completa y apta para principiantes: docs.spicyapi.ai/docs/mcp.

Qué hace, en palabras sencillas

MCP (Model Context Protocol) es un estándar abierto para dar habilidades adicionales a los asistentes de IA. Una vez que este servidor se añade a tu asistente, puedes pedir en lenguaje ordinario — "haz un video de cinco segundos a partir de esta foto" — y el asistente:

1. encuentra un modelo adecuado en el catálogo en vivo y lee qué acepta;
2. sube tu archivo local si hay uno;
3. obtiene una cotización exacta en USD y se detiene para preguntarte antes de que se cobre cualquier cosa;
4. inicia la tarea, espera a que termine y te da el enlace del resultado.

El servidor se ejecuta en tu propia computadora. Tu aplicación asistente lo inicia cuando es necesario; no hay nada que alojar.

Requisitos

• Node.js 22.13 o posterior (node --version). npx incluye Node.js.
• Una clave API de SpicyAPI (abajo) y fondos en la cuenta para tareas de pago. Navegar, cotizar y leer resultados es gratuito.
• Un cliente MCP. Crear, reintentar y purgar tareas requiere además un cliente que admita elicitation de formularios MCP (la forma que tiene el protocolo de hacer una pregunta al usuario). En un cliente sin esta función, esas tres herramientas devuelven un error, que suele contener did not declare the required capability. No se crea, reserva, cobra ni destruye nada: la creación solo ha obtenido su cotización gratuita hasta ese momento, y reintentar y purgar no han enviado ninguna solicitud. Las herramientas de solo lectura siguen funcionando.

Obtén una clave primero

1. Crea una cuenta en spicyapi.ai/register — si los registros están en pausa, esa página muestra cómo unirse a la lista de espera.
2. En la página de claves API elige Create key. Ponle el nombre del asistente que la usará. En Advanced puedes establecer un límite diario, presupuesto mensual, límite de por vida, modelos permitidos, lista blanca de IP y caducidad; las claves nuevas siempre reciben el límite diario predeterminado de la plataforma a menos que ingreses 0 para no tener límite.
3. Copia la clave. Comienza con sk-spicy- y se muestra una sola vez.
4. Para las configuraciones de terminal que aparecen abajo, expórtala en la terminal desde la que ejecutarás el comando de configuración:

export SPICY_API_KEY="sk-spicy-..."   # paste your own key

En Windows PowerShell: $env:SPICY_API_KEY = "sk-spicy-...".

Añádelo a tu cliente

Cada cliente de abajo ejecuta el mismo servidor stdio: npx --yes --package=@spicyapi/mcp spicyapi-mcp.

Nunca ejecutas este servidor tú mismo — tu cliente MCP lo inicia. Si lo lanzas manualmente, solo espera en silencio en stdin, lo que parece un cuelgue. Y necesita --package=@spicyapi/mcp delante del nombre del binario, porque este paquete incluye dos; npx @spicyapi/mcp sin más falla con could not determine executable to run.

Claude Desktop

1. Abre Settings → Developer → Edit Config. El archivo es ~/Library/Application Support/Claude/claude_desktop_config.json en macOS y %APPDATA%\Claude\claude_desktop_config.json en Windows.
2. Pega el bloque de abajo (o añade la entrada spicyapi a un mcpServers existente) y reemplaza YOUR_SPICY_API_KEY.
3. Cierra Claude Desktop por completo y vuelve a abrirlo — solo lee este archivo al iniciar.

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

Claude Code

claude mcp add spicyapi \
  -e SPICY_API_KEY=$SPICY_API_KEY \
  -- npx --yes --package=@spicyapi/mcp spicyapi-mcp

El ámbito predeterminado es el proyecto actual; añade --scope user para todos los proyectos. No uses --scope project, que escribe la clave en un .mcp.json dentro del repositorio. Verifica con claude mcp list o /mcp. En Windows nativo, si el servidor no se inicia, usa -- cmd /c npx --yes --package=@spicyapi/mcp spicyapi-mcp.

Codex

codex mcp add spicyapi \
  --env SPICY_API_KEY=$SPICY_API_KEY \
  -- npx --yes --package=@spicyapi/mcp spicyapi-mcp

Eso escribe ~/.codex/config.toml, que la CLI de Codex, la extensión del IDE y la aplicación de escritorio de ChatGPT leen todos — configúralo una vez y los tres lo detectan. Verifica con codex mcp list o /mcp.

Ambos comandos de terminal copian SPICY_API_KEY de tu shell actual a la configuración local de ese cliente, así que ejecútalos en una terminal donde la clave ya esté exportada. Si no lo estaba, elimina el servidor (claude mcp remove spicyapi / codex mcp remove spicyapi) y añádelo de nuevo.

Cursor, Windsurf y Gemini CLI

Cursor (~/.cursor/mcp.json), Windsurf (~/.codeium/windsurf/mcp_config.json) y Gemini CLI (~/.gemini/settings.json) comparten la misma forma que Claude Desktop:

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

En Windows estos se encuentran en %USERPROFILE%. Si un archivo ya tiene otras configuraciones, fusiona mcpServers en él — el archivo completo debe seguir siendo JSON válido, sin comentarios ni comas finales. Reinicia el cliente si las herramientas no aparecen (Gemini CLI: /mcp las lista).

Esos son archivos a nivel de usuario, fuera de tu repositorio. Nunca copies ese bloque, con una clave real, en un archivo de proyecto que se confirme — como un .cursor/mcp.json a nivel de proyecto.

VS Code

.vscode/mcp.json se confirma con tu repositorio, así que deja que VS Code pida la clave y la guarde en su propio almacenamiento secreto:

{
  "inputs": [
    {
      "id": "spicyapi-key",
      "type": "promptString",
      "description": "SpicyAPI key",
      "password": true
    }
  ],
  "servers": {
    "spicyapi": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"],
      "env": { "SPICY_API_KEY": "${input:spicyapi-key}" }
    }
  }
}

Inícialo desde el code lens sobre la entrada o MCP: List Servers, pega la clave cuando se pida y luego usa las herramientas desde Chat en modo Agent.

Cualquier otro cliente MCP

Usa los mismos command, args y env. Cada cliente tiene su propia ubicación y formato de configuración, y ambos cambian entre versiones — su propia documentación es la autoridad.

Comprueba que funciona

Pregunta a tu asistente, en orden:

1. "Check the SpicyAPI service status." — spicyapi_service_status no necesita clave, así que esto demuestra que el servidor se inicia.
2. "What is my SpicyAPI balance?" — spicyapi_balance_get demuestra que la clave llega al servidor.
3. "Which SpicyAPI tools do you have?" — espera 15 herramientas con el prefijo spicyapi_.

Nada de esto cuesta dinero.

Luego pide algo real

Use SpicyAPI to list the image models I can call, pick an inexpensive one, generate a cinematic night portrait, and give me the result link when it finishes.

El agente lee el catálogo, obtiene el esquema del modelo, consigue una cotización exacta y se detiene para tu confirmación antes de que se cobre cualquier cosa.

Más indicaciones para probar:

• "How much SpicyAPI balance do I have, and what did I spend this week?" — saldo y uso, gratuito.
• "Find SpicyAPI models that turn an image into a video and compare what a 5-second clip costs on each." — catálogo más cotizaciones, gratuito.
• "Turn /Users/me/Desktop/portrait.jpg into a 5-second video with a slow push-in." — subida y luego una tarea confirmada.
• "Show my SpicyAPI tasks from the last three days that failed, and why." — historial de tareas, gratuito; un reintento posterior pide confirmación.

Los IDs de modelo siempre provienen del catálogo en vivo. Cualquier marcador de posición como MODEL_ID_FROM_CATALOG en la documentación de SpicyAPI significa un ID exacto seleccionado de ese catálogo, no un valor literal.

Herramientas

Herramienta	Propósito	Solo lectura	Facturable	Confirmación
spicyapi_service_status	Estado público y disponibilidad; no necesita clave	Sí	No	No
spicyapi_docs_search	Busca en el índice de documentación de primera parte incluido; sin clave	Sí	No	No
spicyapi_models_list	Modelos habilitados y precios específicos de la cuenta	Sí	No	No
spicyapi_model_get	Un modelo y su esquema de entrada actual	Sí	No	No
spicyapi_balance_get	Saldo disponible, retenido y total	Sí	No	No
spicyapi_usage_get	Uso en USD liquidado para la clave actual	Sí	No	No
spicyapi_tasks_list	Una página de metadatos de tareas para la clave actual	Sí	No	No
spicyapi_task_get	Lee una tarea, incluidos los enlaces de resultados listos	Sí	No	No
spicyapi_task_wait	Espera hasta 300 segundos a que una tarea llegue a un estado terminal	Sí	No	No
spicyapi_task_quote	Cotiza una solicitud exacta sin crear nada	Sí	No	No
spicyapi_upload_file	Lee, sube y confirma un archivo local; devuelve su URI spicy://	No	No	No
spicyapi_download_url_create	URL firmada de corta duración para una salida de tarea	No	No	No
spicyapi_task_create	Crea una tarea de generación asíncrona	No	Sí	Siempre
spicyapi_task_retry	Crea una tarea nueva a partir de una fallida o caducada	No	Sí	Siempre
spicyapi_task_purge	Destruye el contenido almacenado de una tarea terminal (destructiveHint)	No	No	Siempre

El servidor también registra dos recursos — spicyapi://docs/index y spicyapi://contract/openapi — y un prompt. spicyapi_generation_workflow es un prompt, no una herramienta — está registrado con registerPrompt, toma goal y un model opcional, y no aparece en SPICYAPI_MCP_TOOLS. Los hosts lo muestran donde sea que listen los prompts MCP.

Parámetros

Herramienta	Parámetros (obligatorios en negrita)
spicyapi_service_status	ninguno
spicyapi_docs_search	query (predeterminado ""), limit (1–25, predeterminado 10)
spicyapi_models_list	modality (image / video / audio / text), provider, task, search, includeSchema, includeExamples (ambos predeterminados false)
spicyapi_model_get	model
spicyapi_balance_get	ninguno
spicyapi_usage_get	from, to (YYYY-MM-DD, UTC)
spicyapi_tasks_list	from, to, state, model, limit (1–100, predeterminado 20), cursor
spicyapi_task_get	taskId
spicyapi_task_wait	taskId, timeoutSeconds (1–300, predeterminado 60), intervalSeconds (1–60, predeterminado adaptativo)
spicyapi_upload_file	path (absoluto; ~/, y ~\ en Windows, se expande), contentType (solo cuando la extensión falta o es incorrecta)
spicyapi_download_url_create	taskId, key
spicyapi_task_quote	model, input, callBackUrl
spicyapi_task_create	model, input, callBackUrl, idempotencyKey, retentionSeconds
spicyapi_task_retry	taskId, idempotencyKey
spicyapi_task_purge	taskId

Los esquemas de entrada del modelo se devuelven como JSON Schema simple: las anotaciones de solo visualización y de tarifa se eliminan antes de que lleguen al agente.

spicyapi_task_create acepta un retentionSeconds opcional que acorta cuánto tiempo se conservan los medios generados, el payload del resultado, el prompt y otro texto de entrada de esa tarea; nunca puede extenderlos, 0 los elimina una vez que la tarea alcanza un estado terminal, y los registros de facturación siempre se conservan.

Su callBackUrl opcional debe ser una dirección https:// pública. El http:// simple se rechaza, y también se rechazan localhost, direcciones de red privadas, puertos explícitos distintos de 443 y 80, y URL que lleven credenciales; cada uno devuelve 400 con Invalid callback URL. http:// no tiene excepción de desarrollo porque el cuerpo de entrega lleva el prompt y enlaces firmados al resultado.

spicyapi_task_purge está anotado como destructiveHint: true y elimina los medios generados, el payload del resultado, el prompt y otro texto de entrada de una tarea terminal. Destruye contenido, no el registro de lo que costó — la entrada del libro mayor, el monto cobrado, el modelo, el estado, las marcas de tiempo y el ID de solicitud sobreviven — por lo que nunca es un reembolso. Solo se aceptan tareas terminales. Una tarea aceptada no se puede cancelar y no hay API de cancelación, así que para una tarea en cola o en ejecución, espera a que termine (spicyapi_task_wait) y luego púrgala. No toma clave de idempotencia, porque el ID de la tarea es la clave de idempotencia: una repetición después de una respuesta perdida devuelve el purgedAt original y no cambia nada. Su resultado solo lleva el ID de la tarea, el estado del contenido y los metadatos de eliminación: sin enlaces, tickets ni claves de salida, porque dejar una forma de recuperar el contenido en el mismo mensaje que informa su destrucción anularía el propósito.

Cómo se protege el gasto

Las herramientas facturables usan elicitación de protocolo y estado de solicitud firmado. La creación de tareas obtiene y vincula la cotización exacta, y luego te pide confirmar su estimación en USD y el cargo máximo. Un agente no puede omitir esa confirmación.

• La pregunta va al usuario, no al modelo. El cliente la muestra; el agente no tiene forma de responderla.
• La respuesta está vinculada a los argumentos exactos. Si el modelo, la entrada o cualquier otro argumento cambia entre la pregunta y la respuesta, la llamada falla con confirmed request state does not match the current tool arguments y no se crea nada.
• Rechazar no crea, cobra ni destruye nada. Una confirmación rechazada o cancelada devuelve operation declined; … con lo que ocurrió y lo que no. Para la creación de tareas, eso es no task was created and no funds were reserved or charged (only the free price quote had been requested) — la cotización mostrada en la pregunta ya se obtuvo. Reintentar y purgar no envían ninguna solicitud antes de la confirmación, así que las suyas terminan en no SpicyAPI request was made. Deja desactivada cualquier opción de "autoaceptar elicitación" para este servidor.
• Sin elicitación, sin gasto. Un cliente sin elicitación de formularios no puede responder la pregunta, por lo que la creación falla justo después de la cotización gratuita y no se crea ni cobra nada.
• Las cotizaciones duran cinco minutos. Confirmar después de eso falla con 40901; vuelve a pedir una cotización nueva.
• Las confirmaciones de reintento no llevan precio. Un reintento es una tarea nueva al precio actual del modelo; usa spicyapi_task_quote primero si quieres el número.
• La recuperación reutiliza la clave de idempotencia. La confirmación la muestra, y un fallo después de la confirmación la devuelve con una pista de recuperación. Llamar a spicyapi_task_create de nuevo con esa idempotencyKey y la solicitud sin cambios devuelve la tarea original en lugar de un segundo cargo.
• Las tareas fallidas y vencidas nunca se cobran; la retención se libera automáticamente. Una tarea exitosa se liquida según el uso real, con un tope en la retención aceptada. Las tareas aceptadas no se pueden cancelar.

Llama a la creación directamente una vez que la entrada del modelo esté lista. La herramienta separada spicyapi_task_quote es para comparaciones de precios independientes, no un requisito previo. Las comprobaciones de salud y saldo son diagnósticos opcionales, no una lista de verificación por tarea.

Resultados

spicyapi_task_get, spicyapi_task_wait y los webhooks v2 verificados incluyen enlaces output.assets[].url listos. Úsalos directamente — nunca envíes la clave de API al almacenamiento. Una devolución de llamada verificada completa no necesita una búsqueda de tarea adicional ni un ticket de descarga. Consulta de nuevo para activos pending o enlaces vencidos; spicyapi_download_url_create sigue disponible para integraciones heredadas y renovación explícita de enlaces, y su URL firmada dura 20 minutos.

Algunos modelos responden en output.text en lugar de con un archivo — la transcripción de audio es el caso simple, una tarea asíncrona ordinaria cuyo resultado son palabras. Un output.assets vacío en ese tipo de modelo es la forma esperada, no un fallo, así que informa el texto en lugar de buscar un enlace faltante.

spicyapi_task_wait sondea de forma adaptativa por defecto, comenzando en unos dos segundos y retrocediendo hasta diez como máximo. Establece intervalSeconds solo para un intervalo fijo. La espera está limitada a 60 segundos por defecto y 300 como máximo por llamada; un tiempo de espera local no cancela la tarea aceptada.

Los artefactos generados se conservan durante unos 14 días como máximo, los prompts durante 30 días, las subidas durante un día — consulta Retención y destrucción. Copia cualquier cosa que quieras conservar.

Informes de uso

spicyapi_usage_get toma fechas from y to opcionales en YYYY-MM-DD. Consulta solo la clave de API configurada para este proceso MCP — no hay anulación de usuario, clave o espacio de trabajo.

• Rango UTC [from,to), hasta 92 días. Por defecto, to es mañana UTC y from es siete días antes.
• Los recuentos de tareas se agrupan por día de creación y modelo.
• totalSpend y cada spend son cadenas decimales exactas en USD que cubren solo cargos liquidados; las retenciones pendientes se excluyen y la liquidación tardía puede cambiar días anteriores.
• Este es un informe de uso, no el saldo de la cuenta ni el presupuesto restante de la clave, y nunca se requiere antes de generar. Observa Retry-After cuando el informe esté limitado por tasa.

spicyapi_tasks_list encuentra tareas después de un reinicio o una devolución de llamada perdida. Devuelve una página de metadatos sin entradas, sin URL de resultados y sin solicitudes automáticas de detalles. Filtros: from, to, state, model, limit, cursor. Mantén las fechas UTC fijas mientras paginas y pasa nextCursor sin cambios. Ventana predeterminada de siete días que termina mañana UTC, 92 días máximo; tamaño de página 20, con tope en 100. cost es final solo cuando settled es verdadero. No uses el historial para sondeo de estado ni como requisito previo para la generación.

Este endpoint tiene su propio bucket a nivel de cuenta: una ráfaga de 30 solicitudes, que se rellena a 30 por minuto, compartido por cada clave de la cuenta. A diferencia del límite general de la API, falla de forma cerrada, por lo que aún rechaza cuando el limitador está degradado. Úsalo para conciliación, no para sondeo.

Archivos locales

spicyapi_upload_file toma la ruta absoluta que dio el usuario, lee el archivo, sube los bytes desde esta máquina y confirma la subida en una sola llamada, luego devuelve el URI spicy:// confirmado para poner en un campo de entrada del modelo. No hay una herramienta de confirmación separada: nada en el lado de MCP retiene una subida a medio terminar. Las subidas por pasos (ticket, PUT, confirmación) pertenecen al código del SDK, que las finaliza con commitUploadedFile. Imágenes (JPEG, PNG, WebP, GIF) hasta 10 MiB; video MP4 / WebM y audio MP3 / WAV hasta 90 MiB. El tipo de contenido se infiere de la extensión. Las URL de medios HTTPS públicas no necesitan subida. Las rutas relativas se rechazan; un ~/ inicial (y ~\ en Windows) se expande al directorio inicio. Si la extensión no se reconoce, el error enumera las nueve que infiere: gif, jpeg, jpg, png, webp, mp4, webm, mp3, wav.

El servidor solo lee dentro del directorio inicio del usuario. Los enlaces simbólicos se resuelven antes de la verificación, por lo que un enlace que apunte fuera de una raíz permitida se rechaza. La protección existe contra la inyección de prompts — una ruta que llega dentro de un correo, una página web o una descripción de tarea es dato, no una instrucción — no para restringir a la persona que ejecuta el servidor, que ya puede leer sus propios archivos.

Establece SPICY_MCP_UPLOAD_ROOTS en el env del servidor para reducir o ampliar eso; reemplaza el valor predeterminado. Las entradas se separan como PATH: : en macOS y Linux, ; en Windows. ~ no se expande en esta variable, así que escribe rutas completas.

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

En Windows, la misma entrada se lee como "SPICY_MCP_UPLOAD_ROOTS": "C:\\Users\\you\\Pictures;D:\\Renders" (las barras invertidas se duplican dentro de JSON). Una raíz que no existe no coincide con nada; el mensaje de rechazo enumera las raíces en vigor.

Variables de entorno

Variable	Usado por	Significado
SPICY_API_KEY	ambos puntos de entrada	Tu clave de API. Requerida para todo excepto estado y búsqueda de documentación
SPICY_MCP_UPLOAD_ROOTS	ambos puntos de entrada	Directorios que spicyapi_upload_file puede leer, separados por : (; en Windows). Predeterminado: directorio de inicio
SPICY_MCP_HTTP_TOKEN	spicyapi-mcp-http	Token de portador requerido, al menos 32 bytes, diferente de SPICY_API_KEY
SPICY_MCP_HOST	spicyapi-mcp-http	127.0.0.1 (predeterminado), localhost o ::1; cualquier otra cosa es rechazada
SPICY_MCP_PORT	spicyapi-mcp-http	Puerto, predeterminado 8765
HTTPS_PROXY	ambos puntos de entrada	Envía llamadas de API a través de este proxy; consulta Detrás de un proxy

Detrás de un proxy

Si tu red llega a internet a través de un proxy HTTP, coloca HTTPS_PROXY (y NO_PROXY, si lo necesitas) en el bloque env del servidor. El servidor lo usa por sí solo en Node.js 22.21+ o 24+. El fetch integrado de Node.js ignora las variables de proxy a menos que se inicie con NODE_USE_ENV_PROXY=1, así que cuando el servidor encuentra un proxy http:// o https://, se reinicia una vez con ese interruptor activado. Establece NODE_USE_ENV_PROXY=0 para conectarse siempre directamente.

Colócalo en el bloque env en lugar de depender de tu shell. Las aplicaciones de escritorio no ven las variables que exportas en una terminal, y Codex solo pasa una lista corta fija de ellas a los servidores MCP:

codex mcp add spicyapi \
  --env SPICY_API_KEY=$SPICY_API_KEY \
  --env HTTPS_PROXY=http://127.0.0.1:7890 \
  -- npx --yes --package=@spicyapi/mcp spicyapi-mcp

Un proxy que curl usa en tu terminal y este servidor no, es la razón habitual por la que curl llega a la API mientras el servidor reporta network request failed. Los errores entonces lo dicen: nombran la variable de proxy que estaba configurada y no se usó. Los proxies socks5:// no son compatibles.

Punto de entrada HTTP

spicyapi-mcp-http sirve Streamable HTTP solo en loopback. La mayoría de los usuarios quieren el punto de entrada stdio de arriba en su lugar; usa esto para un cliente que se conecta a un servidor ya en ejecución por URL.

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
# SpicyAPI MCP HTTP listening at http://127.0.0.1:8765/mcp

• El endpoint MCP es /mcp y requiere Authorization: Bearer <SPICY_MCP_HTTP_TOKEN>; sin él, el servidor responde 401.
• GET /healthz devuelve {"ok":true} sin autenticación.
• Se niega a iniciar en una dirección que no sea loopback, con un token de menos de 32 bytes, o con un token igual a SPICY_API_KEY.
• Los encabezados Host y Origin deben ser locales, para que las páginas web de otros sitios no puedan manejarlo; los cuerpos de solicitud están limitados a 2 MiB.

Loopback significa que solo los programas en la misma computadora pueden conectarse, no otros dispositivos en la red.

Solución de problemas

Síntoma	Solución
Sin herramientas de SpicyAPI en el cliente	Reinicia el cliente por completo; valida el JSON (sin comentarios ni comas finales); verifica la ruta del archivo; comprueba que node --version sea 22.13 o posterior
npx: command not found / spawn npx ENOENT	Instala Node.js desde nodejs.org, o usa la ruta absoluta de which npx / where npx; en Windows prueba "command": "cmd" con argumentos /c npx …
could not determine executable to run	Agrega --package=@spicyapi/mcp antes de spicyapi-mcp
SPICY_API_KEY is required for authenticated API operations	La clave no está llegando al servidor: corrige el bloque env, o vuelve a agregar el servidor desde un shell donde la clave esté exportada
HTTPS_PROXY is set, but this request did not use it	Actualiza Node.js a 22.21+ o 24+, o agrega NODE_USE_ENV_PROXY=1 al bloque env; consulta Detrás de un proxy
401	Clave mal escrita, revocada o caducada: crea una nueva clave
40201 / 40202 / 40301	Recarga; aumenta el límite de la clave o espera el reinicio UTC; permite el modelo en la clave
40310	Verifica el correo de tu cuenta: abre el enlace que enviamos, o envía uno nuevo desde la consola
40003	Los bytes subidos no coinciden con su ticket; llama a spicyapi_upload_file de nuevo y usa el nuevo URI spicy://
40004	Ningún despliegue puede servir esa combinación exacta de configuraciones; cambia el parámetro nombrado en el mensaje según el esquema del modelo, no solo reintentes
503	Una dependencia no está disponible brevemente; espera Retry-After, luego repite la llamada
50302	Una generación síncrona falló aguas arriba y ya fue reembolsada; enviar la misma solicitud de nuevo es seguro
did not declare the required capability	El cliente carece de soporte de elicitación; no se creó ni se cobró nada (la creación solo obtuvo su cotización gratuita). Actualízalo, o usa la CLI para tareas pagadas
confirmed request state does not match the current tool arguments	La solicitud cambió después de que se hizo la pregunta; inicia la creación de nuevo
40901	Cotización caducada o precio cambiado; cotiza y confirma de nuevo
path must be absolute / no such file / may only read files under …	Da la ruta completa; verifica que exista; mueve el archivo bajo una raíz permitida
contentType is required unless the file extension is one of: …	Renombra el archivo con una extensión listada, o pasa contentType
operation declined; …	La confirmación fue rechazada o cancelada; el mensaje dice si solo se había solicitado la cotización gratuita
task … did not reach a terminal state within …	La tarea aún se está ejecutando: espera de nuevo o búscala más tarde; no fue cancelada

Los errores de la API llevan status, code y requestId; conserva el ID de solicitud para soporte. Consulta Errores para cada código.

Una tarea fallida es diferente de una llamada fallida: regresa con state: "failed", un errorCode de un conjunto cerrado, y un errorMessage. Transmite errorMessage al usuario — cuando el servicio de modelo dio una razón específica, se pasa en inglés, sin traducir, con nombres de servicios, hosts, URLs, IDs de solicitud y tarea y detalles de cuenta eliminados — pero ramifica solo en errorCode, que no cambia con la redacción o el idioma.

Lo que este servidor no hace

Envía y rastrea tareas asíncronas nativas; no transmite tokens de chat, y no tiene una herramienta de chat para agregar. Los modelos de texto del catálogo son servidos por las capas compatibles en su lugar — POST /v1/chat/completions y POST /v1/responses (OpenAI), POST /v1/messages (Anthropic) y POST /v1beta/models/{model}:generateContent (Google Gemini), todos bajo https://api.spicyapi.ai — así que un cliente que ya habla uno de esos protocolos solo necesita apuntar su URL base a SpicyAPI. Usa jobs/stream nativo cuando necesites confirmación de cotización y el sobre de eventos de la plataforma — consulta la guía de transmisión de chat.

No puede cancelar una tarea aceptada — ninguna API pública puede — y nunca responde una confirmación de facturación en tu nombre.

Más

• Guía de MCP: configuración, cada herramienta, costos y solución de problemas
• Configuración del cliente en el centro de desarrolladores
• Guía de agentes y automatización
• ¿Quieres que el agente también conozca el flujo de trabajo correcto? Agrega @spicyapi/skill.