SpicyAPI MCP Server

@spicyapi/mcp

O servidor MCP local oficial para SpicyAPI. Ele permite que o assistente de IA que você já usa — Claude Desktop, Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI ou qualquer cliente MCP — navegue pelo catálogo de modelos ao vivo, compare preços, crie tarefas de geração e colecione resultados, com cada etapa cobrável confirmada por você.

SpicyAPI é uma API de IA sem restrições: uma chave para mais de 200 modelos de imagem, vídeo, áudio e chat (Seedance, Kling, Wan, MiniMax, Seedream, GPT Image, Suno e outros), sem filtro de conteúdo adicionado pela plataforma. O que uma solicitação pode produzir depende do modelo que você escolher, e o catálogo marca quais modelos não são censurados.

Este pacote instala spicyapi-mcp (stdio) e spicyapi-mcp-http (Streamable HTTP somente loopback). Ele não contém a CLI ou a Agent Skill.

Guia completo e amigável para iniciantes: docs.spicyapi.ai/docs/mcp.

O que ele faz, em palavras simples

MCP (Model Context Protocol) é um padrão aberto para dar habilidades extras aos assistentes de IA. Uma vez que este servidor é adicionado ao seu assistente, você pode pedir em linguagem comum — "faça um vídeo de cinco segundos a partir desta foto" — e o assistente:

1. encontra um modelo adequado no catálogo ao vivo e lê o que ele aceita;
2. envia seu arquivo local, se houver um;
3. obtém uma cotação exata em USD e para para perguntar a você antes que qualquer coisa seja cobrada;
4. inicia a tarefa, aguarda por ela e fornece o link do resultado.

O servidor roda no seu próprio computador. Seu aplicativo assistente o inicia quando necessário; não há nada para hospedar.

Requisitos

• Node.js 22.13 ou posterior (node --version). npx acompanha o Node.js.
• Uma chave de API SpicyAPI (abaixo) e fundos na conta para tarefas pagas. Navegar, cotar e ler resultados são gratuitos.
• Um cliente MCP. Criar, tentar novamente e limpar tarefas adicionalmente exigem um cliente que suporte elicitação de formulário MCP (a forma do protocolo de fazer uma pergunta ao usuário). Em um cliente sem isso, essas três ferramentas retornam um erro, geralmente contendo did not declare the required capability. Nada é criado, reservado, cobrado ou destruído: a criação buscou apenas sua cotação gratuita até então, e tentar novamente e limpar não enviaram nenhuma solicitação. As ferramentas somente leitura ainda funcionam.

Obtenha uma chave primeiro

1. Crie uma conta em spicyapi.ai/register — se os cadastros estiverem pausados, essa página mostra como entrar na lista de espera.
2. Na página API keys, escolha Create key. Dê a ela o nome do assistente que a usará. Em Advanced, você pode definir um limite diário, orçamento mensal, limite vitalício, modelos permitidos, lista de permissões de IP e expiração; novas chaves sempre recebem o limite diário padrão da plataforma, a menos que você insira 0 para sem limite.
3. Copie a chave. Ela começa com sk-spicy- e é mostrada apenas uma vez.
4. Para as configurações baseadas em terminal abaixo, exporte-a no terminal de onde você executará o comando de configuração:

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

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

Adicione ao seu cliente

Cada cliente abaixo executa o mesmo servidor stdio: npx --yes --package=@spicyapi/mcp spicyapi-mcp.

Você nunca executa este servidor você mesmo — seu cliente MCP o inicia. Iniciado manualmente, ele apenas aguarda silenciosamente no stdin, o que parece um travamento. E ele precisa de --package=@spicyapi/mcp antes do nome do binário, porque este pacote inclui dois deles; npx @spicyapi/mcp simples falha com could not determine executable to run.

Claude Desktop

1. Abra Settings → Developer → Edit Config. O arquivo é ~/Library/Application Support/Claude/claude_desktop_config.json no macOS e %APPDATA%\Claude\claude_desktop_config.json no Windows.
2. Cole o bloco abaixo (ou adicione a entrada spicyapi a um mcpServers existente) e substitua YOUR_SPICY_API_KEY.
3. Saia completamente do Claude Desktop e reabra-o — ele lê este arquivo apenas na inicialização.

{
  "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

O escopo padrão é o projeto atual; adicione --scope user para todos os projetos. Não use --scope project, que escreve a chave em um .mcp.json dentro do repositório. Verifique com claude mcp list ou /mcp. No Windows nativo, se o servidor falhar ao iniciar, use -- 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

Isso escreve ~/.codex/config.toml, que o Codex CLI, a extensão do IDE e o aplicativo de desktop do ChatGPT leem — configure uma vez e todos os três o detectam. Verifique com codex mcp list ou /mcp.

Ambos os comandos de terminal copiam SPICY_API_KEY do seu shell atual para a configuração local desse cliente, então execute-os em um terminal onde a chave já esteja exportada. Se não estiver, remova o servidor (claude mcp remove spicyapi / codex mcp remove spicyapi) e adicione-o novamente.

Cursor, Windsurf e Gemini CLI

Cursor (~/.cursor/mcp.json), Windsurf (~/.codeium/windsurf/mcp_config.json) e Gemini CLI (~/.gemini/settings.json) compartilham o mesmo formato do Claude Desktop:

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

No Windows, eles ficam em %USERPROFILE%. Se um arquivo já tiver outras configurações, mescle mcpServers nele — o arquivo inteiro deve permanecer JSON válido, sem comentários ou vírgulas finais. Reinicie o cliente se as ferramentas não aparecerem (Gemini CLI: /mcp as lista).

Esses são arquivos de nível de usuário fora do seu repositório. Nunca copie esse bloco, com uma chave real nele, para um arquivo de projeto que seja commitado — como um .cursor/mcp.json de nível de projeto.

VS Code

.vscode/mcp.json é commitado com seu repositório, então deixe o VS Code solicitar a chave e mantê-la em seu próprio armazenamento 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}" }
    }
  }
}

Inicie-o a partir do code lens acima da entrada ou MCP: List Servers, cole a chave quando solicitado e use as ferramentas do Chat no modo Agent.

Qualquer outro cliente MCP

Use os mesmos command, args e env. Cada cliente possui sua própria localização e formato de configuração, e ambos mudam entre versões — a documentação deles é a autoridade.

Verifique se funciona

Pergunte ao seu assistente, em ordem:

1. "Verifique o status do serviço SpicyAPI." — spicyapi_service_status não precisa de chave, então isso prova que o servidor inicia.
2. "Qual é o meu saldo SpicyAPI?" — spicyapi_balance_get prova que a chave alcança o servidor.
3. "Quais ferramentas SpicyAPI você tem?" — espere 15 ferramentas com prefixo spicyapi_.

Nenhuma dessas ações custa nada.

Então peça algo real

Use SpicyAPI para listar os modelos de imagem que posso chamar, escolha um barato, gere um retrato noturno cinematográfico e me dê o link do resultado quando terminar.

O agente lê o catálogo, busca o schema do modelo, obtém uma cotação exata e para para sua confirmação antes que qualquer coisa seja cobrada.

Mais prompts para experimentar:

• "Quanto saldo SpicyAPI eu tenho e quanto gastei esta semana?" — saldo e uso, grátis.
• "Encontre modelos SpicyAPI que transformam uma imagem em vídeo e compare quanto custa um clipe de 5 segundos em cada um." — catálogo mais cotações, grátis.
• "Transforme /Users/me/Desktop/portrait.jpg em um vídeo de 5 segundos com aproximação lenta." — upload, depois uma tarefa confirmada.
• "Mostre minhas tarefas SpicyAPI dos últimos três dias que falharam e por quê." — histórico de tarefas, grátis; uma nova tentativa depois pede confirmação.

Os IDs de modelo sempre vêm do catálogo ao vivo. Qualquer espaço reservado como MODEL_ID_FROM_CATALOG na documentação SpicyAPI significa um ID exato selecionado desse catálogo, não um valor literal.

Ferramentas

Ferramenta	Finalidade	Somente leitura	Cobrável	Confirmação
spicyapi_service_status	Saúde e prontidão públicas; nenhuma chave necessária	Sim	Não	Não
spicyapi_docs_search	Pesquisar o índice de documentação de primeira parte incluído; sem chave	Sim	Não	Não
spicyapi_models_list	Modelos habilitados e preços específicos da conta	Sim	Não	Não
spicyapi_model_get	Um modelo e seu schema de entrada atual	Sim	Não	Não
spicyapi_balance_get	Saldo disponível, retido e total	Sim	Não	Não
spicyapi_usage_get	Uso em USD liquidado para a chave atual	Sim	Não	Não
spicyapi_tasks_list	Uma página de metadados de tarefas para a chave atual	Sim	Não	Não
spicyapi_task_get	Ler uma tarefa, incluindo links de resultados prontos	Sim	Não	Não
spicyapi_task_wait	Aguardar até 300 segundos por uma tarefa atingir um estado terminal	Sim	Não	Não
spicyapi_task_quote	Precificar uma solicitação exata sem criar nada	Sim	Não	Não
spicyapi_upload_file	Ler, enviar e confirmar um arquivo local; retornar seu URI spicy://	Não	Não	Não
spicyapi_download_url_create	URL assinada de curta duração para uma saída de tarefa	Não	Não	Não
spicyapi_task_create	Criar uma tarefa de geração assíncrona	Não	Sim	Sempre
spicyapi_task_retry	Criar uma nova tarefa a partir de uma falha ou expirada	Não	Sim	Sempre
spicyapi_task_purge	Destruir o conteúdo armazenado de uma tarefa terminal (destructiveHint)	Não	Não	Sempre

O servidor também registra dois recursos — spicyapi://docs/index e spicyapi://contract/openapi — e um prompt. spicyapi_generation_workflow é um prompt, não uma ferramenta — ele é registrado com registerPrompt, recebe goal e um model opcional, e não aparece em SPICYAPI_MCP_TOOLS. Os hosts o exibem onde quer que listem prompts MCP.

Parâmetros

Ferramenta	Parâmetros (obrigatórios em negrito)
spicyapi_service_status	nenhum
spicyapi_docs_search	query (padrão ""), limit (1–25, padrão 10)
spicyapi_models_list	modality (image / video / audio / text), provider, task, search, includeSchema, includeExamples (ambos padrão false)
spicyapi_model_get	model
spicyapi_balance_get	nenhum
spicyapi_usage_get	from, to (YYYY-MM-DD, UTC)
spicyapi_tasks_list	from, to, state, model, limit (1–100, padrão 20), cursor
spicyapi_task_get	taskId
spicyapi_task_wait	taskId, timeoutSeconds (1–300, padrão 60), intervalSeconds (1–60, padrão adaptativo)
spicyapi_upload_file	path (absoluto; ~/, e ~\ no Windows, é expandido), contentType (somente quando a extensão está ausente ou incorreta)
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

Os esquemas de entrada do modelo são retornados como JSON Schema simples: anotações somente de exibição e de tabela de preços são removidas antes de chegarem ao agente.

spicyapi_task_create aceita um retentionSeconds opcional que encurta por quanto tempo a mídia gerada, o payload de resultado, o prompt e outros textos de entrada daquela tarefa são mantidos; ele nunca pode estendê-los, 0 os remove assim que a tarefa atinge um estado terminal, e os registros de cobrança são sempre mantidos.

Seu callBackUrl opcional deve ser um endereço https:// público. http:// simples é recusado, assim como localhost, endereços de rede privada, portas explícitas diferentes de 443 e 80, e URLs com credenciais; cada um retorna 400 com Invalid callback URL. http:// não tem exceção de desenvolvimento porque o corpo da entrega carrega o prompt e links assinados para o resultado.

spicyapi_task_purge é anotado como destructiveHint: true e remove a mídia gerada, o payload de resultado, o prompt e outros textos de entrada de uma tarefa terminal. Ele destrói conteúdo, não o registro do que custou — a entrada no razão, o valor cobrado, o modelo, o estado, os carimbos de data/hora e o ID da solicitação sobrevivem — portanto, nunca é um reembolso. Somente tarefas terminais são aceitas. Uma tarefa aceita não pode ser cancelada e não há API de cancelamento, então, para uma tarefa na fila ou em execução, aguarde até que ela termine (spicyapi_task_wait) e então a remova. Ela não aceita chave de idempotência, porque o ID da tarefa é a chave de idempotência: uma repetição após uma resposta perdida retorna o purgedAt original e não muda nada. Seu resultado carrega apenas o ID da tarefa, o estado do conteúdo e metadados de remoção: sem links, tickets ou chaves de saída, porque deixar uma forma de buscar o conteúdo na mesma mensagem que relata sua destruição anularia o propósito.

Como os gastos são protegidos

Ferramentas cobráveis usam elicitação de protocolo e estado de solicitação assinado. A criação de tarefas busca e vincula a cotação exata e então pede que você confirme sua estimativa em USD e o valor máximo. Um agente não pode contornar essa confirmação.

• A pergunta vai para o usuário, não para o modelo. O cliente a renderiza; o agente não tem como respondê-la.
• A resposta está vinculada aos argumentos exatos. Se o modelo, a entrada ou qualquer outro argumento mudar entre a pergunta e a resposta, a chamada falha com confirmed request state does not match the current tool arguments e nada é criado.
• Recusar não cria, cobra ou destrói nada. Uma confirmação recusada ou cancelada retorna operation declined; … com o que aconteceu e o que não aconteceu. Para criação de tarefas, isso é no task was created and no funds were reserved or charged (only the free price quote had been requested) — a cotação mostrada na pergunta já foi buscada. Repetição e remoção não enviam nenhuma solicitação antes da confirmação, então as delas terminam em no SpicyAPI request was made. Deixe qualquer configuração de "aceitação automática de elicitação" desativada para este servidor.
• Sem elicitação, sem gastos. Um cliente sem elicitação de formulário não pode responder à pergunta, então a criação falha logo após a cotação gratuita e nada é criado ou cobrado.
• Cotações duram cinco minutos. Confirmar depois disso falha com 40901; peça novamente uma cotação nova.
• Confirmações de repetição não trazem preço. Uma repetição é uma nova tarefa ao preço atual do modelo; use spicyapi_task_quote primeiro se quiser o número.
• A recuperação reutiliza a chave de idempotência. A confirmação a mostra, e uma falha após a confirmação a retorna com uma dica de recuperação. Chamar spicyapi_task_create novamente com essa idempotencyKey e a solicitação inalterada retorna a tarefa original em vez de uma segunda cobrança.
• Tarefas com falha e expiradas nunca são cobradas; a retenção é liberada automaticamente. Uma tarefa bem-sucedida é liquidada com base no uso real, limitada à retenção aceita. Tarefas aceitas não podem ser canceladas.

Chame a criação diretamente quando a entrada do modelo estiver pronta. A ferramenta separada spicyapi_task_quote é para comparações de preço independentes, não um pré-requisito. Verificações de saúde e saldo são diagnósticos opcionais, não uma lista de verificação por tarefa.

Resultados

spicyapi_task_get, spicyapi_task_wait e webhooks v2 verificados incluem links output.assets[].url prontos. Use-os diretamente — nunca envie a chave da API para armazenamento. Um callback verificado completo não precisa de consulta extra de tarefa nem de ticket de download. Consulte novamente para ativos pending ou links expirados; spicyapi_download_url_create permanece disponível para integrações legadas e renovação explícita de links, e sua URL assinada dura 20 minutos.

Alguns modelos respondem em output.text em vez de com um arquivo — transcrição de áudio é o caso simples, uma tarefa assíncrona comum cujo resultado são palavras. Um output.assets vazio em tal modelo é o formato esperado, não uma falha, então relate o texto em vez de procurar um link ausente. Uma transcrição também pode conter output.transcript com marcações de tempo das palavras e o idioma detectado, e a decomposição em camadas retorna uma imagem por camada, empilhadas por output.assets[].layer.zIndex.

spicyapi_task_wait faz polling adaptativo por padrão, começando em cerca de dois segundos e reduzindo para no máximo dez. Defina intervalSeconds somente para um intervalo fixo. A espera é limitada a 60 segundos por padrão e 300 no máximo por chamada; um timeout local não cancela a tarefa aceita.

Os artefatos gerados são mantidos por cerca de 14 dias no máximo, prompts por 30 dias, uploads por um dia — veja Retenção e destruição. Copie qualquer coisa que queira manter.

Relatórios de uso

spicyapi_usage_get aceita datas from e to opcionais em YYYY-MM-DD. Ele consulta apenas a chave da API configurada para este processo MCP — não há override de usuário, chave ou workspace.

• Intervalo UTC [from,to), até 92 dias. Por padrão, to é amanhã UTC e from é sete dias antes.
• As contagens de tarefas são agrupadas por dia de criação e modelo.
• totalSpend e cada spend são strings exatas de USD decimal cobrindo apenas cobranças liquidadas; retenções pendentes são excluídas e liquidação tardia pode alterar dias anteriores.
• Este é um relatório de uso, não saldo de conta ou orçamento restante da chave, e nunca é necessário antes de gerar. Observe Retry-After quando o relatório estiver limitado por taxa.

spicyapi_tasks_list encontra tarefas após uma reinicialização ou um callback perdido. Ele retorna uma página de metadados sem entradas, sem URLs de resultado e sem solicitações automáticas de detalhes. Filtros: from, to, state, model, limit, cursor. Mantenha as datas UTC fixas durante a paginação e passe nextCursor inalterado. Janela padrão de sete dias terminando amanhã UTC, máximo de 92 dias; tamanho de página 20, limitado a 100. cost é final somente quando settled é verdadeiro. Não use o histórico para polling de status ou como pré-requisito para geração.

Este endpoint tem seu próprio bucket de toda a conta: uma rajada de 30 solicitações, reabastecendo 30 por minuto, compartilhado por cada chave na conta. Diferente do limite geral da API, ele falha fechado, então ainda rejeita quando o limitador está degradado. Use-o para reconciliação, não para polling.

Arquivos locais

spicyapi_upload_file aceita o caminho absoluto que o usuário forneceu, lê o arquivo, envia os bytes desta máquina e confirma o upload em uma única chamada, então retorna o URI spicy:// confirmado para colocar em um campo de entrada do modelo. Não há ferramenta separada de confirmação: nada no lado do MCP jamais mantém um upload pela metade. Uploads em etapas divididas (ticket, PUT, confirmação) pertencem ao código do SDK, que os finaliza com commitUploadedFile. Imagens (JPEG, PNG, WebP, GIF) até 10 MiB; vídeo MP4 / WebM e áudio MP3 / WAV até 90 MiB; documentos de referência até 90 MiB — PDF, Word, Excel, PowerPoint, Keynote, Pages, Numbers, texto simples e Markdown — para campos como reference_file_url. O tipo de conteúdo é inferido da extensão. URLs de mídia HTTPS públicas não precisam de upload. Caminhos relativos são recusados; um ~/ inicial (e ~\ no Windows) é expandido para o diretório inicial. Se a extensão não for reconhecida, nada é enviado e o erro lista todas as extensões que a ferramenta infere: gif, jpeg, jpg, png, webp, mp4, webm, mp3, wav, pdf, doc, docx, xls, xlsx, ppt, pptx, key, pages, numbers, txt, md, markdown.

O servidor lê somente sob o diretório inicial do usuário. Symlinks são resolvidos antes da verificação, então um link apontando para fora de uma raiz permitida é recusado. A proteção existe para injeção de prompt — um caminho que chega dentro de um e-mail, uma página web ou uma descrição de tarefa é dado, não uma instrução — não para restringir a pessoa que executa o servidor, que já pode ler seus próprios arquivos. Defina SPICY_MCP_UPLOAD_ROOTS no env do servidor para restringir ou ampliar isso; ele substitui o padrão. As entradas são separadas como PATH: : no macOS e Linux, ; no Windows. ~ não é expandido nesta variável, então escreva caminhos completos.

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

No Windows, a mesma entrada é lida como "SPICY_MCP_UPLOAD_ROOTS": "C:\\Users\\you\\Pictures;D:\\Renders" (com barras invertidas duplicadas dentro do JSON). Uma raiz que não existe não corresponde a nada; a mensagem de recusa lista as raízes em vigor.

Variáveis de ambiente

Variável	Usada por	Significado
SPICY_API_KEY	ambos os entrypoints	Sua chave de API. Obrigatória para tudo, exceto status e busca na documentação
SPICY_MCP_UPLOAD_ROOTS	ambos os entrypoints	Diretórios que spicyapi_upload_file pode ler, separados por : (; no Windows). Padrão: diretório pessoal
SPICY_MCP_HTTP_TOKEN	spicyapi-mcp-http	Token bearer obrigatório, com pelo menos 32 bytes, diferente de SPICY_API_KEY
SPICY_MCP_HOST	spicyapi-mcp-http	127.0.0.1 (padrão), localhost ou ::1; qualquer outra coisa é recusada
SPICY_MCP_PORT	spicyapi-mcp-http	Porta, padrão 8765
HTTPS_PROXY	ambos os entrypoints	Enviar chamadas de API por este proxy; veja Atrás de um proxy

Atrás de um proxy

Se sua rede acessa a internet por um proxy HTTP, coloque HTTPS_PROXY (e NO_PROXY, se precisar) no bloco env do servidor. O servidor o usa por conta própria no Node.js 22.21+ ou 24+. O fetch embutido do Node.js ignora variáveis de proxy a menos que tenha sido iniciado com NODE_USE_ENV_PROXY=1, então quando o servidor encontra um proxy http:// ou https:// ele se reinicia uma vez com essa opção ativada. Defina NODE_USE_ENV_PROXY=0 para sempre conectar diretamente.

Coloque-o no bloco env em vez de depender do seu shell. Aplicativos de desktop não veem as variáveis que você exporta em um terminal, e o Codex passa apenas uma lista curta e fixa delas para 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

Um proxy que curl no seu terminal usa e este servidor não usa é o motivo usual de curl alcançar a API enquanto o servidor relata network request failed. Os erros então dizem isso: eles nomeiam a variável de proxy que foi definida e não usada. Proxies socks5:// não são suportados.

Entrypoint HTTP

spicyapi-mcp-http serve HTTP Streamable apenas em loopback. A maioria dos usuários quer o entrypoint stdio acima; use este para um cliente que se conecta a um servidor já em execução 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

• O endpoint MCP é /mcp e exige Authorization: Bearer <SPICY_MCP_HTTP_TOKEN>; sem ele o servidor responde 401.
• GET /healthz retorna {"ok":true} sem autenticação.
• Ele se recusa a iniciar em um endereço que não seja loopback, com um token menor que 32 bytes, ou com um token igual a SPICY_API_KEY.
• Os cabeçalhos Host e Origin devem ser locais, então páginas web em outros sites não podem controlá-lo; os corpos das requisições são limitados a 2 MiB.

Loopback significa que apenas programas no mesmo computador podem conectar — não outros dispositivos na rede.

Solução de problemas

Sintoma	Correção
Nenhuma ferramenta SpicyAPI no cliente	Reinicie o cliente completamente; valide o JSON (sem comentários ou vírgulas finais); verifique o caminho do arquivo; verifique se node --version é 22.13 ou posterior
npx: command not found / spawn npx ENOENT	Instale o Node.js de nodejs.org, ou use o caminho absoluto de which npx / where npx; no Windows tente "command": "cmd" com argumentos /c npx …
could not determine executable to run	Adicione --package=@spicyapi/mcp antes de spicyapi-mcp
SPICY_API_KEY is required for authenticated API operations	A chave não está chegando ao servidor: corrija o bloco env, ou re-adicione o servidor de um shell onde a chave está exportada
HTTPS_PROXY is set, but this request did not use it	Atualize o Node.js para 22.21+ ou 24+, ou adicione NODE_USE_ENV_PROXY=1 ao bloco env; veja Atrás de um proxy
401	Chave digitada errada, revogada ou expirada — crie uma nova chave
40201 / 40202 / 40301	Recarregue; aumente o limite da chave ou aguarde o reset UTC; permita o modelo na chave
40310	Verifique o email da sua conta: abra o link que enviamos, ou envie um novo pelo console
40003	Os bytes enviados não correspondem ao ticket; chame spicyapi_upload_file novamente e use o novo URI spicy://
40004	Nenhum deployment pode servir essa combinação exata de configurações; altere o parâmetro nomeado na mensagem de acordo com o schema do modelo, não apenas tente novamente
503	Uma dependência está temporariamente indisponível; aguarde Retry-After, então repita a chamada
50302	Uma geração síncrona falhou upstream e já foi reembolsada; enviar a mesma requisição novamente é seguro
did not declare the required capability	O cliente não tem suporte a elicitação; nada foi criado ou cobrado (a criação buscou apenas sua cotação gratuita). Atualize-o, ou use o CLI para tarefas pagas
confirmed request state does not match the current tool arguments	A requisição mudou depois que a pergunta foi feita; inicie a criação novamente
40901	Cotação expirada ou preço mudou; cotar e confirmar novamente
path must be absolute / no such file / may only read files under …	Dê o caminho completo; verifique se existe; mova o arquivo para uma raiz permitida
cannot tell the file type from its extension; …	Renomeie o arquivo com uma extensão listada, ou passe contentType
operation declined; …	A confirmação foi recusada ou cancelada; a mensagem diz se apenas a cotação gratuita havia sido solicitada
task … did not reach a terminal state within …	A tarefa ainda está em execução — aguarde novamente ou consulte depois; ela não foi cancelada

Erros da API carregam status, code e requestId; guarde o ID da requisição para suporte. Veja Erros para cada código.

Uma tarefa falha é diferente de uma chamada falha: ela retorna com state: "failed", um errorCode de um conjunto fechado, e um errorMessage. Repasse errorMessage ao usuário — quando o serviço de modelo deu um motivo específico, ele é passado em inglês, sem tradução, com nomes de serviços, hosts, URLs, IDs de requisição e tarefa e detalhes de conta removidos — mas ramifique apenas em errorCode, que não muda com a redação ou o idioma.

O que este servidor não faz

Ele submete e rastreia tarefas assíncronas nativas; ele não transmite tokens de chat, e não tem ferramenta de chat para adicionar. Os modelos de texto do catálogo são servidos pelas camadas compatíveis — POST /v1/chat/completions e POST /v1/responses (OpenAI), POST /v1/messages (Anthropic) e POST /v1beta/models/{model}:generateContent (Google Gemini), todos sob https://api.spicyapi.ai — então um cliente que já fala um desses protocolos só precisa apontar sua URL base para o SpicyAPI. Use jobs/stream nativo quando precisar de confirmação de cotação e o envelope de eventos da plataforma — veja o guia de streaming de chat.

Modelos de texto que leem imagens, vídeo ou áudio os recebem como partes de mensagem, e o URI spicy://f/… de spicyapi_upload_file é o que vai em uma parte image_url, video_url ou audio_url (partes de vídeo e áudio são transportadas por Chat Completions e jobs/stream) — veja enviando mídia para um modelo de texto.

Ele não pode cancelar uma tarefa aceita — nenhuma API pública pode — e nunca responde a uma confirmação de cobrança em seu nome.

Mais

• Guia MCP: configuração, todas as ferramentas, custos e solução de problemas
• Configuração do cliente no hub de desenvolvedores
• Guia de agentes e automação
• Quer que o agente também saiba o fluxo de trabalho correto? Adicione @spicyapi/skill.