SpicyAPI MCP Server

Servidor MCP oficial para SpicyAPI. Permite que Claude, Cursor, Codex o cualquier cliente MCP navegue por más de 200 modelos de imagen, video, audio y chat, obtenga una cotización exacta en USD, suba archivos locales, cree tareas de generación y recopile los resultados. Cada paso de pago solicita tu confirmación primero.

GitHub

Documentación

@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.

SpicyAPI es una API de IA sin restricciones: una clave para más de 200 modelos de imagen, video, audio y chat (Seedance, Kling, Wan, MiniMax, Seedream, GPT Image, Suno y más), sin filtro de contenido añadido por la plataforma. Lo que una solicitud puede producir depende del modelo que elijas, y el catálogo marca qué modelos no están censurados.

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 natural — "haz un video de cinco segundos a partir de esta foto" — y el asistente:

encuentra un modelo adecuado en el catálogo en vivo y lee qué acepta;
sube tu archivo local si hay uno;
obtiene una cotización exacta en USD y se detiene para preguntarte antes de que se cobre cualquier cosa;
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 además requieren 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 generalmente contiene 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 el reintento y la purga no han enviado ninguna solicitud. Las herramientas de solo lectura siguen funcionando.

Obtén una clave primero

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.
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 obtienen el límite diario predeterminado de la plataforma a menos que ingreses 0 para no tener límite.
Copia la clave. Comienza con sk-spicy- y se muestra una sola vez.
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 simple falla con could not determine executable to run.

Claude Desktop

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.
Pega el bloque de abajo (o añade la entrada spicyapi a un mcpServers existente) y reemplaza YOUR_SPICY_API_KEY.
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 vaya a confirmar — 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 solicite 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 te 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:

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

Ninguna de estas tiene costo.

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 de salud 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 alcance 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` (por defecto `""`), `limit` (1–25, por defecto 10)
`spicyapi_models_list`	`modality` (`image` / `video` / `audio` / `text`), `provider`, `task`, `search`, `includeSchema`, `includeExamples` (ambos por defecto `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, por defecto 20), `cursor`
`spicyapi_task_get`	`taskId`
`spicyapi_task_wait`	`taskId`, `timeoutSeconds` (1–300, por defecto 60), `intervalSeconds` (1–60, por defecto adaptativo)
`spicyapi_upload_file`	`path` (absoluta; `~/`, 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 llegar al agente.

spicyapi_task_create acepta un retentionSeconds opcional que reduce 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, al igual que localhost, las direcciones de red privadas, los puertos explícitos distintos de 443 y 80, y las URL con 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 existe una 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 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 lleva solo el ID de 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, 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, por lo 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 ese idempotencyKey y la solicitud sin cambios devuelve la tarea original en lugar de un segundo cargo.
Las tareas fallidas y expiradas 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 cuando 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 búsqueda adicional de tarea ni ticket de descarga. Consulta de nuevo para activos pending o enlaces expirados; 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. Una transcripción también puede llevar output.transcript con tiempos de palabras y el idioma detectado, y la descomposición de capas devuelve una imagen por capa, apiladas por output.assets[].layer.zIndex.

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 USD exactas 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, máximo 92 días; tamaño de página 20, con tope de 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 API, falla cerrado, 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 herramienta de confirmación separada: nada en el lado de MCP retiene una subida a medias. 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; documentos de referencia hasta 90 MiB — PDF, Word, Excel, PowerPoint, Keynote, Pages, Numbers, texto plano y Markdown — para campos como reference_file_url. 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 de inicio. Si la extensión no se reconoce, no se sube nada y el error enumera cada extensión que la herramienta infiere: gif, jpeg, jpg, png, webp, mp4, webm, mp3, wav, pdf, doc, docx, xls, xlsx, ppt, pptx, key, pages, numbers, txt, md, markdown.

El servidor solo lee dentro del directorio de 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 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 estrechar 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 del 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	Usada por	Significado
`SPICY_API_KEY`	ambos puntos de entrada	Tu clave de API. Requerida para todo excepto estado y búsqueda en documentación
`SPICY_MCP_UPLOAD_ROOTS`	ambos puntos de entrada	Directorios que `spicyapi_upload_file` puede leer, separados por `:` (`;` en Windows). Predeterminado: directorio personal
`SPICY_MCP_HTTP_TOKEN`	`spicyapi-mcp-http`	Token portador requerido, de 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 se rechaza
`SPICY_MCP_PORT`	`spicyapi-mcp-http`	Puerto, predeterminado `8765`
`HTTPS_PROXY`	ambos puntos de entrada	Envía las llamadas a la 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, pon 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 haya iniciado 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 conectar siempre directamente.

Ponlo 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 y 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 informa network request failed. Los errores entonces lo dicen: nombran la variable de proxy que estaba establecida y no se usó. Los proxies socks5:// no son compatibles.

Punto de entrada HTTP

spicyapi-mcp-http sirve HTTP Streamable solo en loopback. La mayoría de los usuarios quieren el punto de entrada stdio de arriba; usa este 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, así que las páginas web de otros sitios no pueden controlarlo; los cuerpos de las solicitudes 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 ajustes; 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 cobró nada (la creación solo obtuvo su cotización gratuita). Actualízalo, o usa la CLI para tareas de pago
`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
`cannot tell the file type from its extension; …`	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 está en ejecución: espera de nuevo o consúltala 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 del 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 se sirven a través de 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.

Los modelos de texto que leen imágenes, video o audio los toman como partes de mensaje, y el URI spicy://f/… de spicyapi_upload_file es lo que va en una parte image_url, video_url o audio_url (las partes de video y audio se transportan mediante Chat Completions y jobs/stream) — consulta enviar medios a un modelo de texto.

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.