Conecte o servidor MCP da fal.ai ao Claude Code e ao Codex em minutos. Veja os comandos para configurar OAuth e tokens, as onze ferramentas que seu agente recebe, um prompt para controlar custos, correções para erros comuns e uma segunda opção de MCP para imagens e vídeo.
Você está no meio de uma funcionalidade no Claude Code, a landing page precisa de uma imagem de destaque, e a rotina de sempre é um sofrimento: abrir uma aba do navegador, escolher um modelo, esperar a renderização, baixar o arquivo, renomeá-lo e arrastá-lo para o repositório. O servidor MCP da fal.ai elimina todo esse desvio. Depois de conectado, seu agente de código pode pesquisar o catálogo da fal com mais de 1.000 modelos generativos, ler o esquema de entrada de um modelo, consultar o preço, executar o job e devolver a URL de uma imagem sem sair do terminal.
Este artigo mostra como conectar o servidor ao Claude Code e ao Codex, quais comandos executar, quais ferramentas você recebe, como manter os gastos previsíveis e quais problemas aparecem com mais frequência. Ele também mostra onde o conector MCP próprio da PicassoIA se encaixa, caso você queira um segundo back end para o mesmo fluxo de trabalho. Os comandos seguem as páginas oficiais de configuração da fal e a documentação MCP de cada cliente. Quando as próprias páginas da fal divergem entre si, eu sinalizo.
MCP, o Model Context Protocol, é o padrão aberto que permite a um cliente de IA chamar ferramentas externas. O servidor da fal é um endpoint hospedado, então não há nada para instalar, compilar ou manter rodando na sua máquina. Seu agente chama as ferramentas, e a fal executa os modelos em suas próprias GPUs. A documentação da fal deixa a cobrança clara: você paga apenas pelas execuções de modelo que disparar, com os mesmos preços das chamadas diretas à API.
Isso faz diferença especialmente em trabalhos com imagens. Em vez de fixar um modelo no script, você deixa o agente escolher no catálogo, perguntar quais entradas o modelo aceita e verificar quanto ele vai custar, tudo em linguagem comum.
| Ferramenta | O que faz |
|---|---|
search_models | Pesquisa o catálogo por tema ou categoria |
get_model_schema | Lê os parâmetros de entrada e saída de um modelo |
get_pricing | Consulta o preço antes de uma execução |
search_docs | Pesquisa na documentação da fal |
recommend_model | Sugere modelos para uma tarefa específica |
run_model | Executa um modelo e espera, por padrão 45 segundos |
submit_job | Inicia um job longo sem esperar |
check_job | Informa o status de um job |
get_job_result | Busca o resultado de um job concluído |
cancel_job | Interrompe um job na fila ou em execução |
upload_file | Envia um arquivo para a CDN da fal para usar como entrada de um modelo |
💡 Dica: o anúncio da fal no blog lista nove ferramentas, enquanto a página atual da documentação lista onze. Espere que a lista continue mudando e, logo após conectar, pergunte ao seu agente "quais ferramentas da fal você consegue ver?".
get_pricing transforma "quanto isso vai custar?" em uma pergunta que o agente responde antes de agir.
A fal documenta duas rotas, e elas usam URLs diferentes. Escolha uma por máquina em vez de adicionar as duas com o mesmo nome.
A documentação aponta para https://mcp.fal.ai/mcp-relay, que usa Streamable HTTP e faz o login pelo navegador. Você nunca cola um token em um arquivo de configuração ou em um chat. Essa é a melhor escolha para um laptop onde você pode abrir uma janela do navegador.
O post da fal no blog descreve https://mcp.fal.ai/mcp, em que você envia seu token de API da fal em um cabeçalho Authorization: Bearer. Ela serve para servidores, contêineres e CI, onde não há navegador disponível. A fal afirma que o token nunca é armazenado do lado dela, mas trate-o como uma senha mesmo assim: guarde-o em uma variável de ambiente e nunca em um repositório.
| Rota | URL | Login | Melhor para |
|---|---|---|---|
| Relay OAuth | https://mcp.fal.ai/mcp-relay | Login pelo navegador | Laptops e desktops |
| Token Bearer | https://mcp.fal.ai/mcp | Cabeçalho de autorização | Servidores, CI, máquinas sem interface |
💡 Dica: depois de conectar qualquer uma das rotas, envie um prompt de teste inofensivo: "Use a fal para pesquisar modelos de geração de imagens. Não execute nenhum modelo." Uma lista de resultados de busca comprova que o login e as ferramentas funcionam, e não custa nada.
O Claude Code adiciona servidores remotos com claude mcp add. As duas rotas exigem um único comando. Para a rota OAuth:
claude mcp add --transport http fal https://mcp.fal.ai/mcp-relay
Abra o Claude Code e execute /mcp. Selecione fal e conclua o login no navegador. Isso segue a própria redação da fal: adicione o servidor remoto e depois autentique com /mcp.
Para a rota de token Bearer:
export FAL_TOKEN="paste-your-fal-token-here"
claude mcp add --transport http fal-ai https://mcp.fal.ai/mcp \
--header "Authorization: Bearer $FAL_TOKEN"
O nome da variável FAL_TOKEN é apenas um rótulo, então use o nome que preferir. Adicione --scope user para disponibilizar o servidor em todos os projetos, ou --scope project para gravá-lo em um .mcp.json compartilhado. Se uma equipe compartilha esse arquivo, referencie a variável ali em vez de colar o token.
Para verificar a conexão, liste seus servidores:
claude mcp list
Dentro de uma sessão, /mcp mostra todos os servidores e seus status. Se a fal aparecer como conectada, peça a lista de ferramentas. Se ela pedir autenticação, execute novamente a etapa de login.
O Codex guarda as configurações de MCP em ~/.codex/config.toml, e projetos confiáveis podem adicionar o próprio .codex/config.toml. Você pode editar o arquivo manualmente ou usar a família de comandos codex mcp. A rota de um único comando fica assim:
codex mcp add fal --url https://mcp.fal.ai/mcp-relay
codex mcp login fal
A etapa de login é a que a documentação da fal destaca para o Codex: adicione o servidor e depois execute codex mcp login fal. O Codex muda rápido, então, se alguma flag for rejeitada, execute codex mcp add --help para ver a sintaxe atual.
A rota do config.toml faz o mesmo trabalho manualmente:
[mcp_servers.fal]
url = "https://mcp.fal.ai/mcp-relay"
Para a rota de token Bearer, aponte o Codex para uma variável de ambiente em vez de gravar o token no arquivo:
[mcp_servers.fal_token]
url = "https://mcp.fal.ai/mcp"
bearer_token_env_var = "FAL_TOKEN"
Exporte FAL_TOKEN no seu shell antes de iniciar o Codex. Depois disso, codex mcp list deve mostrar o servidor.
| Etapa | Claude Code | Codex |
|---|---|---|
| Adicionar o servidor | claude mcp add --transport http | codex mcp add --url |
| Fazer login | /mcp dentro de uma sessão | codex mcp login fal |
| Local da configuração | .claude.json ou .mcp.json | ~/.codex/config.toml |
| Arquivo de regras do projeto | CLAUDE.md | AGENTS.md |
| Listar servidores | claude mcp list | codex mcp list |
Comece específico e faça o agente mostrar o que pretende antes de gastar qualquer coisa:
Use fal to find a fast photorealistic text-to-image model. Show me its price and input schema, wait for my OK, then generate one 16:9 image of a quiet harbor at dawn.
Uma sessão bem comportada executa search_models, depois get_model_schema e get_pricing, pausa para a sua aprovação e só então chama run_model. As próprias documentações da fal orientam os assistentes a mostrar o custo estimado e pedir aprovação antes de gerar, então esse fluxo segue o desenho pretendido.
Salve o resultado no seu repositório. A ferramenta devolve uma URL. Peça o próximo passo na mesma frase: "Baixe a imagem para public/images/harbor.jpg com curl e referencie-a no componente do hero." Um arquivo local significa que sua página não depende de um link remoto continuar no ar.
run_model espera até 45 segundos por padrão, o que atende à maioria dos modelos de imagem. Trabalhos mais lentos, como vídeo ou upscaling pesado, devem ir para a fila:
submit_job inicia o trabalho e retorna na hora.check_job informa o status.get_job_result busca o resultado quando o job termina.cancel_job interrompe um job que você iniciou por engano.Diga ao agente qual modo você quer. "Envie isso como job e verifique a cada 20 segundos" funciona bem para vídeo.
Coloque a regra onde o agente a lê em toda sessão: CLAUDE.md para o Claude Code, AGENTS.md para o Codex.
fal.ai rules:
- Call get_pricing before every run_model or submit_job.
- Show the estimated cost and wait for my approval when it is above $0.50.
- Never generate more than four images per request without asking.
Leia o esquema uma vez. get_model_schema lista as entradas de um modelo: proporção, número de imagens, seed, guidance. Quando o agente lê isso primeiro, você evita requisições que falham por um nome de parâmetro adivinhado de forma errada. Peça ao agente para salvar as configurações que funcionaram nas notas do projeto, para que a próxima sessão pule essa consulta.
A fal afirma que o servidor MCP respeita os mesmos limites de concorrência das chamadas diretas à API. Se você pedir doze variações de uma vez, espere que algumas fiquem na fila. Lotes de três ou quatro terminam mais rápido e são mais fáceis de revisar.
| Sintoma | Causa provável | Correção |
|---|---|---|
| Nenhuma ferramenta da fal aparece | A sessão começou antes de o servidor ser adicionado | Reinicie o Claude Code ou o Codex e depois verifique /mcp ou codex mcp list |
| O login pelo navegador nunca termina | A etapa OAuth foi pulada | Execute /mcp no Claude Code ou codex mcp login fal no Codex |
| Erro de não autorizado na rota de token | A variável está vazia ou o cabeçalho está malformado | Exporte FAL_TOKEN novamente e confirme que o cabeçalho começa com Bearer |
| Um job expira | run_model para de esperar após 45 segundos | Mude para submit_job e depois consulte com check_job |
| A lista de ferramentas mostra logs e apps em vez de modelos | O Platform MCP foi adicionado por engano | Remova-o para trabalhos com imagens e adicione o servidor principal da fal |
| A imagem sai com formato errado | A proporção ficou no padrão | Peça ao agente para ler get_model_schema e definir a proporção explicitamente |
O servidor hospedado não é a única forma de acessar a fal a partir de um agente, e a fal não é o único back end que vale a pena conectar.
| Servidor | Ferramentas | Onde roda | Destaque |
|---|---|---|---|
| raveenb/fal-mcp-server | 18 | Na sua máquina ou no Docker | Licença MIT, STDIO e HTTP/SSE, instalação como plugin do Claude Code |
| wynandw87/claude-code-fal_ai-mcp | 22 | Na sua máquina, com Node | Ferramentas de vídeo, sincronização labial, troca de rosto, 3D e música |
O primeiro se instala como plugin do Claude Code:
/plugin install fal-ai@raveenb/fal-mcp-server
Servidores da comunidade executam código no seu computador com o seu token da fal no ambiente, então leia o código-fonte antes de adicionar um. O servidor hospedado evita esse risco porque quem o executa é a fal.
A fal também oferece um Platform MCP separado em https://api.fal.ai/v1/mcp/platform. Ele é estritamente somente leitura, e suas 16 ferramentas são voltadas para administrar sua conta: apps serverless, histórico de requisições, logs e análises. Ele usa um esquema de autorização diferente do servidor principal, então nunca reutilize o cabeçalho entre os dois. Não é uma ferramenta de imagens, mas você pode conectar os dois ao mesmo tempo.
Se você quer o mesmo fluxo de trabalho com agentes em um back end diferente, a PicassoIA mantém um conector MCP próprio. Dentro do Claude, ele expõe nove ferramentas: generate_image, edit_image, generate_video_picassoia, generate_video_seedance, get_generation, list_generations, cancel_generation, list_models e get_account.
Os jobs são assíncronos. Uma chamada de geração retorna um predict_id assim que uma GPU aceita o job, e você consulta get_generation após o atraso sugerido até que o status diga succeeded ou failed. O conector atende quatro modelos: PicassoIA Image, PicassoIA Image Editor Pro, PicassoIA Video e Seedance 2.5 Lite, sendo que os dois últimos produzem vídeo. Uma conta permite cinco predições simultâneas, compartilhadas entre todas as conexões.
💡 Dica: a própria descrição do conector diz que as gerações nos modelos de GPU da PicassoIA são gratuitas nos planos Infinite e Wonder. Confira a página de preços para ver o que o seu plano inclui antes de montar um fluxo de trabalho em cima disso.
Qualquer que seja o servidor que você usar, o modelo certo depende da tarefa. Estes são os que eu testaria primeiro, todos disponíveis no catálogo da PicassoIA:
| Tarefa | Modelos para testar |
|---|---|
| Rascunhos rápidos | Flux Schnell, P Image |
| Imagens fotorrealistas | Flux 2 Pro, Imagen 4 Ultra |
| Texto dentro das imagens | GPT Image 2 |
| Saída nítida em 4K | Nano Banana Pro, Seedream 4.5 |
| Edição de uma imagem existente | Flux Kontext Pro, PicassoIA Image Editor Pro |
| Vídeo curto a partir de uma imagem | Seedance 2.5 Lite, Kling v3 Video |
O modelo de texto também importa, porque ele escreve o prompt que o seu modelo de imagem recebe. Claude Sonnet 5 e GPT 5.6 Sol estão ambos no catálogo da PicassoIA, então você pode testar a escrita de prompts lado a lado antes de se decidir por um.
Qual caminho serve para você? Esta tabela coloca as três opções lado a lado:
| Opção | Hospedagem | Ponto forte | Escolha quando |
|---|---|---|---|
| MCP da fal hospedado | fal | Mais de 1.000 modelos, verificação de preço e de esquema | Você quer o catálogo mais amplo sem nada para instalar |
| Servidor da fal da comunidade | Sua máquina | Ferramentas extras, como sincronização labial e 3D | Você quer controle local e pode revisar o código |
| Conector da PicassoIA | PicassoIA | Quatro modelos próprios e consulta assíncrona | Você quer um conjunto de ferramentas enxuto e focado em imagem e vídeo |
Conectar um servidor leva cinco minutos. Escolher bem um modelo exige alguns experimentos, e essa parte é mais divertida em um navegador. Abra a Picasso IA, navegue pela lista completa de modelos e execute um prompt em dois ou três modelos lado a lado. Comece com o PicassoIA Image, listado como gerador de texto para imagem ilimitado, e depois teste o Flux 2 Pro e o Seedream 4.5 com a mesma redação.
Quando você souber qual modelo entrega o visual que procura, leve essa escolha de volta ao Claude Code ou ao Codex e registre-a no seu arquivo de regras. Assim, seu agente para de adivinhar, e cada imagem de destaque do seu próximo projeto parte de um modelo que você escolheu de propósito.
Escolha seu idioma
