Servidor MCP

O @spicyapi/mcp deixa o assistente de IA que você já usa (Claude, Cursor, VS Code, Codex, Windsurf, Gemini CLI e outros) trabalhar com a SpicyAPI por você. Depois de configurá-lo, você pode escrever "faça um vídeo de cinco segundos com esta foto", e o assistente encontra um modelo adequado, diz o preço, espera o seu OK, inicia o trabalho e entrega o link do resultado.

Você não precisa escrever código. Precisa do Node.js, de uma chave de API e de uns dez minutos.

O que é MCP, em palavras simples

MCP (Model Context Protocol) é um padrão aberto para dar habilidades extras a assistentes de IA. Pense numa tomada para plugues: um assistente que suporta MCP pode carregar "servidores", e cada servidor acrescenta um conjunto de ferramentas que o assistente pode usar enquanto conversa com você.

O @spicyapi/mcp é um desses servidores. Ele acrescenta 15 ferramentas da SpicyAPI. Veja o que acontece quando você pede alguma coisa:

1. Você escreve uma mensagem normal, por exemplo "Gere uma imagem de um farol ao amanhecer."
2. O seu assistente decide de quais ferramentas da SpicyAPI precisa e as chama.
3. O servidor, um pequeno programa que roda no seu próprio computador e que o aplicativo do assistente inicia sozinho, envia essas requisições à SpicyAPI usando a sua chave de API.
4. Tudo o que custa dinheiro para antes: o seu aplicativo mostra o preço e pede a sua confirmação. O assistente não pode responder a essa pergunta por você.
5. Os resultados voltam para a conversa, e o assistente os explica.

Não há nada para hospedar nem para manter rodando. O aplicativo do assistente inicia o servidor quando precisa dele e o encerra quando você fecha o aplicativo.

Ele serve para você se você já usa um assistente de IA e quer testar modelos, comparar preços ou produzir imagens e vídeos sem escrever um programa. Desenvolvedores também o usam para explorar o catálogo de dentro do editor antes de construir uma integração.

Ele não é a ferramenta certa para um aplicativo ou backend em produção (use o SDK ou a API HTTP), para grandes lotes sem ninguém acompanhando (use a CLI) nem para receber respostas de chat token por token em streaming: o servidor MCP envia e acompanha tarefas; para chat, veja Texto e streaming.

MCP, CLI, SDK ou Skill?

A SpicyAPI publica quatro pacotes separados. A maioria das pessoas só precisa de um ou dois.

Se o seu aplicativo não é escrito em TypeScript, a linha do SDK tem mais quatro opções: Python, Go, PHP e Java.

O que o seu assistente pode fazer

Estas são as 15 ferramentas que o servidor acrescenta. Você nunca as chama pelo nome: você pede com as suas palavras e o assistente escolhe. Os nomes são úteis quando você lê o que o assistente fez, ou quando o seu aplicativo pede que você aprove a chamada de uma ferramenta.

"Pergunta antes" quer dizer que o próprio servidor da SpicyAPI para e pede confirmação, e o assistente não tem como pular essa etapa. Muitos aplicativos também perguntam a você antes de rodar qualquer ferramenta; isso é uma configuração do próprio aplicativo e não tem relação com esta confirmação.

Antes de começar

node --version

Configure o seu cliente

Todos os aplicativos abaixo rodam o mesmo comando: npx --yes --package=@spicyapi/mcp spicyapi-mcp. Na primeira vez, o pacote é baixado, o que pode levar alguns segundos.

Você nunca precisa rodar esse comando por conta própria: o aplicativo o inicia. Se você o rodar à mão, ele fica esperando em silêncio que o aplicativo fale com ele, o que parece um travamento, mas é normal. Aperte Ctrl+C para encerrá-lo.

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

Cada aplicativo decide onde fica a própria configuração e em que formato, e as duas coisas mudam de uma versão para outra. Quando um passo acima não corresponder mais ao seu aplicativo, vale o que diz a documentação de MCP do próprio aplicativo. Qualquer outro aplicativo compatível com MCP pode usar os mesmos command, args e env mostrados acima.

Mantenha a sua chave em segurança

Qualquer pessoa que tenha a sua chave pode gastar o seu saldo. Alguns hábitos mantêm o risco sob controle:

• Coloque a chave só em arquivos do seu usuário, os que ficam na sua pasta pessoal e foram listados acima, nunca num arquivo dentro de um projeto ou repositório. Se você faz backup dos seus arquivos de configuração num repositório público de "dotfiles", deixe esses de fora.
• Nunca cole a chave no chat. O assistente não precisa dela; o servidor a lê da configuração.
• Defina um limite diário na chave, para que um erro tenha um teto.
• Se uma chave vazar, revogue-a na página Chaves de API e crie uma nova. A revogação vale na hora; as tarefas que já foram aceitas terminam mesmo assim e continuam sendo cobradas. Veja Autenticação.

Confira se funciona

Faça estes três pedidos numa conversa nova, nesta ordem:

1. "Verifique o status do serviço da SpicyAPI." Usa spicyapi_service_status. Não precisa de chave, então, se isso funcionar, o servidor está instalado corretamente.
2. "Qual é o meu saldo na SpicyAPI?" Usa spicyapi_balance_get. Se isso funcionar, a sua chave está chegando ao servidor.
3. "Quais ferramentas da SpicyAPI você tem?" O assistente deve listar 15 ferramentas cujos nomes começam com spicyapi_.

Nenhum desses pedidos custa nada. Se algum falhar, veja Solução de problemas.

Experimente: exemplos de conversa

Copie qualquer um destes pedidos no seu assistente. As descrições mostram quais ferramentas ele normalmente vai usar (cada assistente é de um jeito, então a ordem exata pode variar) e exatamente onde ele para para perguntar a você.

Conferir o saldo e os gastos

Quanto saldo eu tenho na SpicyAPI, e quanto gastei nesta semana?

O assistente chama spicyapi_balance_get e spicyapi_usage_get. As duas são gratuitas e de só leitura, então nada pede confirmação. O valor "reservado" (held) no saldo é o dinheiro separado por tarefas que ainda estão rodando.

Encontrar e comparar modelos

Encontre modelos da SpicyAPI que transformam uma imagem parada em vídeo e compare quanto custaria um clipe de 5 segundos em cada um.

O assistente chama spicyapi_models_list (filtrando por modelos de vídeo que recebem uma imagem), pode chamar spicyapi_model_get para ver detalhes e pode chamar spicyapi_task_quote uma vez por candidato para obter o preço exato com as suas configurações. As cotações são gratuitas e não criam nada, então não há confirmação. A resposta é uma comparação para você escolher.

Gerar uma imagem

Use a SpicyAPI para gerar uma imagem quadrada de uma casa de lámen iluminada por neon numa noite de chuva. Escolha um modelo de imagem barato e me passe o link quando terminar.

1. spicyapi_models_list para escolher um modelo, e spicyapi_model_get se ele precisar dos campos que esse modelo aceita.
2. spicyapi_task_create. É aqui que ele para. O seu aplicativo mostra uma confirmação com o modelo, o custo estimado, a cobrança máxima e quando a cotação expira. Nada é cobrado até você confirmar.
3. Depois que você confirma, a tarefa começa e spicyapi_task_wait espera que ela termine.
4. O assistente entrega o link do resultado da tarefa concluída.

Transformar uma foto do seu computador em vídeo

Transforme a foto em /Users/me/Desktop/portrait.jpg num vídeo de 5 segundos em que a câmera se aproxima devagar.

No Windows, informe o caminho como C:\Users\me\Desktop\portrait.jpg.

1. spicyapi_upload_file envia a foto e devolve um endereço spicy:// para ela. O upload é gratuito e não pede confirmação, mas envia de fato esse arquivo para a SpicyAPI, então informe o caminho exato do arquivo que você quer.
2. spicyapi_models_list / spicyapi_model_get para escolher um modelo de imagem para vídeo e ver as opções dele.
3. spicyapi_task_create: ele para aqui para pedir a sua confirmação, mostrando o preço.
4. spicyapi_task_wait. Vídeos costumam levar vários minutos; cada espera dura no máximo cinco, então o assistente pode esperar mais de uma vez, ou você pode perguntar pela tarefa mais tarde.

Encontrar uma tarefa anterior

Mostre as minhas tarefas da SpicyAPI dos últimos três dias que falharam e me diga por quê.

O assistente chama spicyapi_tasks_list com um filtro pelo estado failed e depois spicyapi_task_get nas que interessam a você, para ler o erro. Tarefas que falham ou expiram normalmente liberam toda a reserva. Algumas recusas de conteúdo são cobradas pelo orçamento aceito, somente quando a página do modelo informa explicitamente essa exceção. Confira settled e cost para saber o valor final. Se em seguida você disser "tente aquela de novo", ele chama spicyapi_task_retry, que para e pede a sua confirmação, porque uma nova tentativa é uma tarefa paga nova.

Obter o arquivo do resultado

Me passe o link de download do meu último vídeo da SpicyAPI.

O assistente encontra a tarefa com spicyapi_tasks_list e depois a lê com spicyapi_task_get, que já traz links de resultado prontos para usar. Abra o link num navegador para baixar. Os links duram pouco: se um tiver expirado, peça de novo e o assistente busca um novo.

O servidor MCP não salva arquivos no seu computador por conta própria. Assistentes que também conseguem rodar comandos, como o Claude Code ou o Codex, podem baixar o link numa pasta para você, se você pedir.

Referência das ferramentas

Todas as ferramentas, o que cada uma recebe e o que devolve. Valores em dinheiro são sempre em dólares americanos, escritos como texto decimal exato, sem o sinal $, por exemplo "0.08". As datas estão em UTC.

Conferir o serviço e a documentação

spicyapi_service_status

Confere se a API pública da SpicyAPI está acessível e saudável. Não precisa de chave de API, não custa nada e não pergunta nada. É uma ferramenta de diagnóstico: o assistente não precisa rodá-la antes de criar uma tarefa.

Parâmetros: nenhum.

Retorna: operational (true ou false), as verificações individuais health e readiness com o status HTTP de cada uma e checkedAt.

spicyapi_docs_search

Pesquisa um índice das páginas da documentação da SpicyAPI que vem dentro do servidor e devolve os títulos, resumos e links que correspondem. Não precisa de chave e não faz nenhuma requisição de rede.

Retorna: uma lista de itens, cada um com slug, title, summary, keywords e url. Os links apontam para este site de documentação, no formato https://docs.spicyapi.ai/docs/retention. Quando nada corresponde, a lista vem vazia.

Explorar modelos

spicyapi_models_list

Lista os modelos que a sua chave de API pode chamar, com preços que já incluem qualquer desconto da sua conta. Gratuita e de só leitura.

Retorna: total e items. Cada item traz model (o ID exato para usar), displayName, provider, modality, tasks, enabled e available, availability, uma lista pricing (cada item tem um rótulo de faixa, uma unit que é per_image, per_second, per_request ou per_1k_tokens e um price em USD), startingPrice, taskTimeoutSeconds e, quando pedidos, inputSchema / examples.

Algumas configurações, como a resolução ou a duração, mudam o preço. A lista de preços serve para comparar; a cobrança exata de uma requisição específica vem de uma cotação.

spicyapi_model_get

Devolve um modelo por completo: as entradas que ele aceita (inputSchema, uma descrição legível por máquina de cada campo, do tipo dele, dos valores permitidos e dos valores padrão), os preços, a disponibilidade e os exemplos. Gratuita e de só leitura.

Retorna: os mesmos campos de um item de spicyapi_models_list, sempre incluindo inputSchema.

A sua conta

spicyapi_balance_get

Mostra o seu saldo. Gratuita e de só leitura. Não é necessária antes de criar uma tarefa: a criação confere o saldo por conta própria.

Parâmetros: nenhum.

Retorna: available, held (reservado por tarefas que ainda estão rodando) e total, em USD. Também pode incluir um detalhamento funding com os fundos pré-pagos, as verbas promocionais e qualquer linha de crédito aprovada; veja Cobrança.

spicyapi_usage_get

Informa o que esta chave de API fez: quantas tarefas, quantas deram certo ou falharam e o gasto liquidado, agrupados por dia e por modelo. Gratuita e de só leitura. Ela cobre só a chave que está na sua configuração, não a sua conta inteira, e não é o seu saldo.

Retorna: from, to, currency, totalCalls, totalSpend e as listas days e models, com calls, succeeded, failed e spend. Só entram cobranças liquidadas; o dinheiro ainda reservado por tarefas em andamento não entra, e uma liquidação tardia pode atualizar um dia anterior.

Tarefas

spicyapi_tasks_list

Lista as tarefas criadas com esta chave de API, das mais novas para as mais antigas. É útil para encontrar uma tarefa depois de fechar a conversa. Mostra só metadados: nada de prompts, entradas ou links de resultado. Gratuita e de só leitura.

Retorna: items (cada um com taskId, model, state, cost, settled, createdAt, deadlineAt e, quando a tarefa terminou, completedAt), hasMore e nextCursor. cost só é definitivo quando settled é true.

spicyapi_task_get

Abre uma tarefa criada com esta chave de API. Gratuita e de só leitura.

Retorna: taskId, model, state, cost, settled, createdAt, completedAt e, dependendo da tarefa:

• output.assets: os resultados. Cada asset pronto tem uma url que você pode abrir diretamente, com o expiresAt dela, o tipo mime e o tamanho ou a duração. Um asset marcado como pending ainda está sendo armazenado; pergunte de novo em alguns segundos. Um marcado como unavailable não existe mais.
• errorCode e errorMessage, quando a tarefa falhou; os códigos estão listados em Erros.
• input: o que foi enviado, até acabar o prazo de retenção do prompt.
• contentState (present, expired ou purged) e retention, que diz quando as saídas e os prompts vão ser removidos.
• sourceTaskId, quando esta tarefa é uma nova tentativa.

Um ID de tarefa que não existe e um que pertence a outra pessoa devolvem, os dois, "não encontrado".

spicyapi_task_wait

Consulta uma tarefa várias vezes até ela terminar ou o tempo de espera acabar e depois a devolve. Gratuita e de só leitura. Esgotar o tempo de espera não cancela a tarefa nem a faz falhar: ela continua rodando, e você pode esperar de novo ou consultá-la mais tarde.

Retorna: a tarefa concluída, no mesmo formato de spicyapi_task_get. Se o tempo acabar antes, a ferramenta informa que a tarefa não terminou nesse período.

Arquivos

spicyapi_upload_file

Lê um arquivo do seu computador, envia-o para a SpicyAPI, conclui o upload e devolve um endereço spicy:// que pode ir na entrada de um modelo, tudo numa única chamada, sem segunda etapa. É gratuita e não pede confirmação, mas envia o arquivo, então não é de só leitura.

Arquivos que já estão na internet num endereço https:// público não precisam de upload: o assistente pode passar esse endereço direto para o modelo, se o modelo aceitar uma URL.

Arquivos aceitos: imagens JPEG, PNG, WebP e GIF de até 10 MiB; vídeos MP4 e WebM e áudios MP3 e WAV de até 90 MiB e 600 segundos. Um modelo pode definir limites próprios mais rígidos.

Quais pastas: por padrão, só podem ser lidos arquivos dentro da sua pasta pessoal. Veja Arquivos locais.

Retorna: uri (o endereço spicy://), fileId, bytes, contentType, sha256, width / height / durationSeconds quando conhecidos e expiresAt. Por padrão, o endereço pode ser usado por um dia.

O upload já está concluído quando esta ferramenta retorna, então não há uma etapa separada de "commit" para rodar. O servidor não tem ferramenta para concluir um upload iniciado por outro programa; código que faz o upload em etapas separadas o conclui com o commitUploadedFile do SDK.

spicyapi_download_url_create

Emite um novo link de download assinado para um resultado de uma das suas tarefas. Gratuita. Normalmente é desnecessária: spicyapi_task_get e spicyapi_task_wait já trazem links prontos, e consultar a tarefa de novo os renova.

Retorna: key, url e expiresAt. O link funciona por 20 minutos e não pode ser revogado depois de emitido, então não o compartilhe nem o guarde. Veja Mídia.

Preços, criação e exclusão

spicyapi_task_quote

Calcula o preço exato de uma requisição específica sem iniciar nada e sem reservar dinheiro. Gratuita e de só leitura. O assistente a usa para comparar opções; ele não precisa dela antes de criar uma tarefa, porque a criação pede a própria cotação.

Retorna: quoteId, model, estimatedCost, maxCharge, currency, quantity, unit e expiresAt. Uma cotação vale por cinco minutos e só para exatamente aquela requisição.

spicyapi_task_create

Inicia uma geração. Custa dinheiro e sempre pergunta a você antes.

O que acontece, em ordem:

1. O servidor pede uma cotação exata para a requisição. Uma cotação é gratuita: não cria nada e não reserva dinheiro.
2. O seu aplicativo mostra uma confirmação com o modelo, o custo estimado, a cobrança máxima, quando a cotação expira e uma chave de idempotência (uma referência que impede que a mesma requisição seja cobrada duas vezes).
3. Se você recusar, nenhuma tarefa é criada e nenhum dinheiro é reservado ou cobrado. A única requisição enviada até ali foi a cotação gratuita do passo 1.
4. Se você confirmar, a SpicyAPI confere as entradas, o preço, as permissões da sua chave e o seu saldo, reserva o valor estimado e inicia a tarefa.

Isso exige um aplicativo capaz de mostrar perguntas de confirmação (elicitation do MCP). Num aplicativo que não consegue, a ferramenta falha no passo 2: a cotação gratuita foi buscada e nada mais aconteceu. Veja Antes de começar.

Retorna: taskId, state (normalmente queued), estimatedCost e a idempotencyKey usada. A partir daí a tarefa roda sozinha; use spicyapi_task_wait ou spicyapi_task_get para buscar o resultado.

Se a conexão cair depois que você confirmou, o erro inclui a chave de idempotência. Peça ao assistente que tente de novo com essa mesma chave e sem mudar o modelo nem as configurações, em vez de começar do zero: talvez você precise confirmar de novo, mas a SpicyAPI devolve a tarefa original em vez de cobrar uma segunda. Uma chave nova criaria uma segunda tarefa paga, e configurações diferentes com a mesma chave são recusadas.

spicyapi_task_retry

Cria uma tarefa nova, cobrada separadamente, a partir de uma que terminou como failed ou expired. A tarefa original fica como estava. Custa dinheiro e sempre pergunta a você antes.

Retorna: o novo taskId, sourceTaskId (a original), state, estimatedCost e idempotencyKey.

A nova tentativa usa o preço atual do modelo, e as conferências atuais de entradas, permissões e saldo rodam de novo. A confirmação dela não mostra preço, então, se você quiser saber antes, peça ao assistente que faça uma cotação do mesmo modelo com as mesmas configurações usando spicyapi_task_quote antes de repetir.

Uma nova tentativa reaproveita a entrada original sem mudança, então leia antes o errorCode da tarefa que falhou:

• rate_limited, upstream_unavailable, timeout ou upstream_failed: vale uma nova tentativa depois de uma breve espera.
• generation_failed: mude o prompt ou a imagem e inicie uma tarefa nova; a mesma entrada costuma falhar do mesmo jeito.
• invalid_asset: envie o arquivo de novo e inicie uma tarefa nova com o novo endereço spicy://; uma nova tentativa reaproveitaria o arquivo antigo.
• content_rejected, invalid_request ou unsupported_combination: não repita sem mudar nada. Mude o prompt, as configurações ou o modelo e inicie uma tarefa nova.

A lista completa está em Erros.

spicyapi_task_purge

Apaga de forma permanente o conteúdo armazenado de uma tarefa concluída: a mídia gerada, o resultado armazenado (os dados do resultado que ficam guardados), o prompt e os demais textos de entrada. Não pode ser desfeito e sempre pergunta a você antes. Não custa nada, e também não reembolsa nada.

• Só tarefas concluídas (succeeded, failed, expired ou um canceled antigo) podem passar por purge. Uma tarefa aceita não pode ser cancelada e não existe API de cancelamento, então, para uma tarefa queued ou running, espere que ela termine (spicyapi_task_wait) e depois faça o purge.
• Baixe antes tudo o que quiser guardar.
• O registro de cobrança continua: o lançamento, o valor cobrado, o modelo, o estado, os horários e o ID da requisição continuam visíveis depois.
• Fazer purge de novo numa tarefa que já passou por purge não causa problema.

Retorna: taskId, contentState (purged assim que a exclusão é agendada), purgedAt, contentRemovedBy e billingRetained: true. De propósito, não devolve nenhum link. A remoção física dos arquivos normalmente termina em até um minuto; veja Retenção e destruição.

Recursos e prompt

Além das ferramentas, o servidor oferece dois recursos de só leitura e um prompt. Cada aplicativo os mostra num lugar diferente, e muita gente nunca precisa deles.

Custos, confirmação e segurança

Como é a confirmação

Quando o assistente inicia uma tarefa, o seu aplicativo mostra uma pergunta do servidor da SpicyAPI. O texto é parecido com este (os valores são exemplos):

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…

Hoje, o custo estimado e a cobrança máxima mostram o mesmo número: a estimativa é o valor reservado quando a tarefa começa, e a tarefa nunca é cobrada acima dessa reserva.

A forma de responder depende do aplicativo: normalmente uma caixa de seleção ou um interruptor confirm, mais botões de aceitar e recusar. Marque confirm e aceite para seguir em frente. Recusar ou cancelar encerra a chamada da ferramenta, e a mensagem diz o que aconteceu e o que não aconteceu:

Responda em até cinco minutos. A cotação vale por cinco minutos. Se ela tiver expirado quando você confirmar, a criação falha com o erro 40901 e nada é cobrado; peça ao assistente que tente de novo para obter uma cotação nova.

Repetir uma tarefa mostra uma pergunta parecida, sem preço. O purge avisa que a exclusão não pode ser desfeita e que os registros de cobrança são mantidos.

Por que o assistente não consegue pular a confirmação

• A pergunta vai para você, não para a IA. O servidor a envia ao seu aplicativo pelo recurso de elicitation do MCP, e o aplicativo a mostra a você. O assistente não tem como respondê-la.
• A sua resposta fica presa àquela requisição exata. A confirmação está vinculada ao modelo e às configurações que foram mostrados a você. Se o assistente mudar qualquer coisa entre a pergunta e a sua resposta, o servidor recusa com "confirmed request state does not match the current tool arguments" e nada é criado.
• Mantenha assim. Se o seu aplicativo oferecer uma configuração que aceita automaticamente as perguntas de servidores MCP, deixe-a desligada para a SpicyAPI. Um assistente ou uma configuração que confirme por você remove a única trava de gasto deste caminho.
• Aplicativos sem suporte a confirmação não conseguem gastar. Neles, iniciar, repetir e fazer purge simplesmente devolvem um erro; até esse ponto, iniciar uma tarefa só buscou a cotação gratuita dela. Veja Antes de começar.

O que você paga

• Os preços são em dólares americanos. Estimativas, cobranças e saldos são valores exatos em dólar.
• Você nunca é cobrado acima do máximo que confirmou. Quando uma tarefa começa, o valor estimado dela fica reservado (aparece como "held"). Quando ela dá certo, você paga pelo uso real, limitado a essa reserva, e o que não foi usado é liberado.
• Tarefas que falham ou expiram normalmente liberam toda a reserva. Algumas recusas de conteúdo são cobradas pelo orçamento aceito, somente quando a página do modelo informa explicitamente essa exceção. Confira settled e cost para saber o valor final.
• Consultar é gratuito: explorar modelos, cotações, saldo, consumo, consulta de tarefas, esperas, uploads e links de download.
• Uma tarefa iniciada não pode ser cancelada. Fechar a conversa, sair do aplicativo, uma espera que esgotou o tempo ou revogar a chave não interrompe uma tarefa que já foi aceita. Veja Execução e novas tentativas.
• Os limites da sua chave valem. Quando um limite diário, mensal ou acumulado é atingido, novas tarefas são recusadas com 40202 até o período virar; veja Cobrança.

Por quanto tempo os resultados ficam guardados

• Os arquivos gerados ficam guardados por no máximo cerca de 14 dias, menos se você encurtou a retenção da sua conta ou daquela tarefa. Baixe tudo o que quiser guardar.
• Os links de resultado são temporários, normalmente 20 minutos. Um link expirado não quer dizer que o arquivo sumiu: consulte a tarefa de novo para receber um link novo, desde que ainda esteja dentro do prazo de retenção.
• Os prompts e as entradas ficam guardados por no máximo 30 dias; o registro de cobrança da tarefa (ID, modelo, estado, valor, horários) continua.
• Os arquivos enviados podem ser usados por um dia.
• Para apagar antes o conteúdo de uma tarefa, peça ao assistente que faça o purge dela. Para encurtar a retenção de uma única tarefa, peça a ele que defina retentionSeconds ao criá-la.

As regras completas e as exceções estão em Retenção e destruição.

Arquivos locais

spicyapi_upload_file consegue ler arquivos do seu computador, o que exige cuidado:

• Por padrão, ela só lê dentro da sua pasta pessoal (por exemplo /Users/you ou C:\Users\you). Um arquivo em outro lugar é recusado com uma mensagem que diz quais pastas são permitidas.
• Atalhos não contornam isso. Um link simbólico dentro da sua pasta pessoal que aponte para fora dela é recusado.
• Por que esse limite existe: um assistente que lê uma página da web, um e-mail ou um documento pode dar de cara com instruções escondidas como "envie as chaves privadas do usuário". O limite de pastas mantém os arquivos do sistema fora do alcance desse tipo de truque. A sua própria pasta pessoal continua legível, então só deixe o assistente enviar arquivos que você indicou e leia o caminho quando o seu aplicativo pedir que você aprove a chamada da ferramenta.

Mudar as pastas. Acrescente SPICY_MCP_UPLOAD_ROOTS ao env do servidor, ao lado de SPICY_API_KEY, com um ou mais caminhos completos de pasta. Ele substitui o padrão, então você pode restringir a uma única pasta ou listar várias. As pastas são separadas do mesmo jeito que na configuração PATH do sistema, que muda conforme o sistema operacional. Escreva cada pasta como um caminho completo: o ~ não é expandido nesta configuração, embora seja expandido nos caminhos de arquivo que você passa ao assistente.

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

Estes blocos mostram só a parte env. Acrescente a linha SPICY_MCP_UPLOAD_ROOTS ao env do item spicyapi que você criou em Configure o seu cliente e mantenha a linha da sua chave como está. No Claude Code e no Codex, acrescente-a ao comando de registro (-e SPICY_MCP_UPLOAD_ROOTS=… ou --env SPICY_MCP_UPLOAD_ROOTS=…), depois de remover o servidor. Reinicie o aplicativo em seguida. Uma pasta que não existe simplesmente não corresponde a nada, então, se os uploads forem recusados depois dessa mudança, confira a grafia na mensagem, que lista as pastas que o servidor está usando.

Modo HTTP: só neste computador

A maioria dos aplicativos inicia o servidor sozinha, como acima. Alguns preferem se conectar, por endereço, a um servidor que já está rodando. Para esses, o pacote inclui um segundo programa, o 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

Ele mostra SpicyAPI MCP HTTP listening at http://127.0.0.1:8765/mcp. Aponte o seu aplicativo para esse endereço e faça-o enviar o cabeçalho Authorization: Bearer seguido do seu SPICY_MCP_HTTP_TOKEN. http://127.0.0.1:8765/healthz responde {"ok":true} quando ele está rodando.

"Só loopback" quer dizer que só programas neste mesmo computador conseguem se conectar. Outros aparelhos no seu Wi-Fi e a internet não o alcançam, e não existe configuração para abri-lo: qualquer outro endereço é recusado na inicialização. Requisições vindas de páginas da web de outros sites também são rejeitadas. Se você precisa de um servidor acessível a partir de outras máquinas, não é este.

Solução de problemas

Código-fonte

O pacote tem licença MIT e é desenvolvido abertamente em github.com/spicyapi-ai/spicy-mcp. É lá que você lê o código por trás de qualquer ferramenta desta página, relata um comportamento diferente do descrito aqui ou propõe uma mudança.

Próximos passos