Configuração MCP no Windsurf: Gerar imagens no Cascade

Um servidor MCP no Windsurf é uma caixa de ferramentas externa que o agente pode acionar no meio de uma conversa: você o declara uma vez em mcp_config.json, e o Cascade ganha habilidades que o modelo base não possui nativamente. A geração de imagens é a lacuna mais óbvia. O Windsurf cria com facilidade a estrutura de uma tela de configurações, conecta rotas e escreve testes, deixando para trás três retângulos cinzas onde deveriam estar as ilustrações.

Em resumo, caso queira apenas o essencial: crie uma chave no seu perfil BananaBanana e adicione o seguinte bloco a ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "bananabanana": {
      "serverUrl": "https://bananabanana.pro/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BB_API_KEY}"
      }
    }
  }
}

Exporte BB_API_KEY=bb_live_SUA_CHAVE, recarregue os servidores MCP e dez ferramentas aparecerão no Cascade. As imagens custam a partir de $0.03 cada em um saldo pré-pago, o vídeo a partir de $0.10, sem assinaturas e sem a necessidade de criar um projeto próprio na nuvem. Um aviso antes de colar: em versões recentes, esse arquivo pode não ser mais o que o seu agente lê. Mais detalhes a seguir.

Por que dar um gerador de imagens ao Cascade?

Porque o momento em que você precisa de uma imagem quase nunca é uma boa hora para sair do editor de código. Você está no meio de um fluxo de onboarding, o estado vazio precisa de arte, e a alternativa é abrir uma aba do navegador, digitar um prompt, baixar, renomear, arrastar para public/ e depois procurar onde você tinha parado.

Uma única instrução substitui todo esse desvio. O Cascade escreve o prompt, chama generate_image, move o arquivo para a pasta correta e escreve a tag <img> com o texto alt. Você apenas revisa o diff.

Há um segundo argumento ainda mais importante para este cliente. O Cascade foi construído para criar funcionalidades inteiras, não edições isoladas; portanto, os recursos de que precisa chegam em conjuntos: três estados vazios, seis miniaturas de categorias, um pacote de avatares temporários. Gerar esses pacotes manualmente em abas do navegador é onde o fluxo de trabalho se perde.

A alternativa a um servidor remoto é rodar um servidor MCP local de imagens, o que exige um processo Node ou Python na sua máquina mais uma chave de provedor upstream própria, com cotas e faturamento na sua conta. Um servidor remoto dispensa ambos. O endpoint já roda em nossa infraestrutura, no mesmo pipeline do gerador web, e sua única credencial é uma string bb_live_ que você pode revogar a qualquer momento na página de perfil.

Onde o Windsurf guarda as configurações MCP agora?

Este é o ponto que confunde muitos desenvolvedores em agosto de 2026, e vale a pena checar antes de editar qualquer arquivo. O Windsurf agora faz parte do Devin Desktop da Cognition: o site windsurf.com redireciona para devin.ai/desktop, e a URL antiga docs.windsurf.com/windsurf/cascade/mcp redireciona via 307 para docs.devin.ai/desktop/cascade/mcp. O aplicativo continua se chamando Windsurf no disco, o esquema de links continua windsurf:// e a pasta de configuração permanece ~/.codeium/windsurf/. Apenas a marca mudou.

O que mudou de fato é que agora existem dois agentes com dois sistemas de configuração distintos, e a documentação do Cascade MCP avisa isso no topo da página: o arquivo mcp_config.json se aplica ao agente Cascade legado, enquanto o agente Devin Local (padrão em novas abas) lê as configurações da CLI do Devin. Verificado em 20 de agosto de 2026.

Portanto, escolha o arquivo de acordo com o agente com o qual você está conversando.

Cascade legado lê ~/.codeium/windsurf/mcp_config.json (%USERPROFILE%\.codeium\windsurf\mcp_config.json no Windows). Servidores remotos aceitam o campo serverUrl ou url mais headers, correspondente ao trecho no início deste artigo.

Agente Devin Local lê os arquivos de configuração da CLI: ~/.config/devin/mcp_config.json para o escopo do usuário, .devin/mcp_config.json para projetos compartilhados no git, e .devin/mcp_config.local.json para chaves pessoais (ignorado automaticamente no git). Os nomes dos campos diferem levemente:

{
  "mcpServers": {
    "bananabanana": {
      "url": "https://bananabanana.pro/api/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer ${env:BB_API_KEY}"
      }
    }
  }
}

Ou ignore o editor: devin mcp add bananabanana https://bananabanana.pro/api/mcp cria a entrada no escopo local, bastando depois adicionar o bloco headers. Comandos como devin mcp list e devin mcp get bananabanana informam com precisão o que a CLI carregou.

Em ambos os casos, o endpoint é https://bananabanana.pro/api/mcp. Não /mcp, que é a página de documentação para leitura humana. Uma requisição POST ali retorna HTML e desorienta o agente. Nossa página de documentação do servidor MCP traz esses mesmos trechos e uma tabela de compatibilidade para todos os clientes verificados:

Após a conexão, list_models e get_account são chamadas gratuitas — peça ao Cascade para executar uma delas como teste rápido. get_account retorna seu saldo, o nome da chave e o limite diário, o que permite validar a autenticação sem gastar com uma geração.

Caso de uso: conjunto de estados vazios para o app que o Cascade acabou de criar

O cenário real sobre o qual montei estas demonstrações. O Cascade monta a estrutura de uma ferramenta interna, os três estados vazios aparecem como divs cinzas temporárias e, em vez de abrir um software de design, você fornece ao agente uma frase de estilo para gerar todo o conjunto.

A frase de estilo resolve tudo. Estados vazios só funcionam como grupo: a paleta de cores, a espessura dos traços e o espaço negativo precisam se manter de uma imagem para a outra. Escreva a frase uma vez, oriente o agente a reutilizá-la literalmente em cada chamada e mude apenas o tema:

→ generate_image {"prompt": "A flat vector illustration for an app empty
   state: an open cardboard box floating above a soft shadow with three small
   paper envelopes drifting out of it, muted teal and warm coral palette on an
   off-white background, thin confident outlines, generous negative space,
   centered composition, no text", "model": "nano-banana-pro",
   "aspect_ratio": "4:3"}
← {"job_id": "…", "status": "processing", "cost_charged_usd": 0.11}

Depois, a mesma frase com outro tema para a tela de «sem resultados»:

Combinam perfeitamente como par, que é exatamente o objetivo de imagens temporárias. Caso precise de uma proximidade ainda maior, generate_image aceita o parâmetro seed — repetir a mesma semente com a mesma cláusula estilística aproxima os resultados. Para personagens ou mascotes que precisam se manter consistentes em várias imagens, a técnica de prompting conta mais do que o cliente em si, conforme detalhado em nosso guia de consistência de personagens.

Duas notas transparentes. Gerei estes exemplos no Nano Banana Pro a $0.11 por se tratarem de imagens desta página e exigirem nitidez. Para placeholders temporários que um designer substituirá em duas semanas, nano-banana-2-lite a $0.03 é a escolha mais inteligente, e nosso guia da versão Lite explica onde este modelo econômico atende plenamente. Ele é também o modelo padrão da ferramenta, sendo escolhido automaticamente pelo agente se nada for especificado.

A geração de vídeo funciona no mesmo chat. generate_video nunca debita na primeira chamada: retorna uma cotação prévia e o agente precisa repetir a chamada com confirm_cost preenchido com esse valor exato antes que a renderização se inicie. Vídeo mudo de 4 segundos em 720p no Veo 3.1 Lite começa em $0.10; o Omni Flash cobra $0.10 por segundo com áudio sempre presente, totalizando $0.30 para um clipe de 3 segundos.

Peculiaridades do Windsurf para ter em mente

Cinco pontos práticos que destacaria a um colega de equipe, observados durante a configuração.

1. Variáveis de ambiente não definidas falham silenciosamente. A documentação é clara: ${env:NOME_DA_VARIAVEL} é substituída pelo valor da variável e, se ela não existir, torna-se uma string vazia. Sem avisos ou erros explícitos. O cabeçalho é enviado como Bearer , nosso servidor responde 401 e a situação parece um problema no servidor e não uma variável ausente. Aplicativos iniciados pela interface gráfica não carregam o perfil do terminal, tornando invisível um export em .zshrc se o Windsurf não foi aberto pelo terminal. Se list_models acusar erro de autenticação, verifique a variável antes de qualquer outra coisa.

2. A sintaxe ${file:…} é mais confiável e exclusiva do Windsurf. A mesma configuração suporta ${file:/caminho/do/arquivo}, substituído pelo conteúdo limpo do arquivo, suportando caminhos com til ~. Com isso, "Authorization": "Bearer ${file:~/.secrets/bb_key.txt}" funciona sem variáveis de ambiente e elimina o problema de inicialização por GUI. Recomendo essa opção no Windsurf. Nem o Cursor nem o VS Code contam com esse recurso.

3. O Cascade é limitado a 100 ferramentas. É um teto rígido considerando todos os seus servidores MCP conectados. Na tela de configurações de cada servidor é possível desativar ferramentas individuais. Nós adicionamos dez. Se você já utiliza servidores grandes (o do GitHub sozinho tem dezenas), desative o que não for usar: generate_speech, edit_video e list_generations são fáceis de desligar caso deseje apenas imagens.

4. O link direto em um clique não inclui sua chave, o que é ótimo para a segurança. O Windsurf suporta links do tipo windsurf://windsurf-mcp-registry?serverName=<name> que abrem uma tela do catálogo para revisão antes da instalação. Observe o detalhe: sem configurações codificadas, ao contrário de instaladores que usam blocos inteiros em base64, não há risco de vazar credenciais em URLs compartilhadas. Como ainda não estamos no catálogo público, a configuração é feita via JSON manual.

5. Em planos de equipe, o ID do servidor diferencia maiúsculas de minúsculas. Assim que um administrador aprova um servidor MCP na lista de permissões, todos os demais são bloqueados para a equipe, e o Server ID autorizado precisa corresponder com exatidão ao nome da chave no seu mcp_config.json. Em suma: se o admin liberou bananabanana e o seu arquivo diz BananaBanana, a conexão falhará sem explicar o motivo. Equipes Enterprise também podem apontar o Windsurf para seu próprio registro MCP em vez do catálogo padrão.

Uma limitação de interface para sermos transparentes: generate_speech entrega o áudio como URL em vez de um player inline no Cascade, exigindo que você abra o arquivo separadamente. Imagens, por outro lado, contam com uma prévia visual direta ao lado do link, o que é bem mais prático.

E quanto ao OAuth em vez de uma chave de API?

Ambos os métodos estão disponíveis e atendem a agentes diferentes.

A CLI do Devin (o agente Local) possui suporte nativo a OAuth: devin mcp login <name> abre o fluxo no navegador, armazena os tokens localmente e os renova de forma automática com registro dinâmico de clientes (DCR) sem pré-configurações. Nosso servidor atua como servidor de autorização OAuth 2.1 com DCR e indicadores de recursos RFC 8707. A documentação do Cascade também cita suporte a OAuth para todos os tipos de transporte.

Para este artigo utilizei a autenticação por chave de API (initialize, get_account, list_models com uma chave bb_live_ real). Se testar OAuth e encontrar inconsistências, a opção a ajustar é oauthResource, que substitui o parâmetro resource da RFC 8707, visto que nosso endpoint requer a audiência https://bananabanana.pro/api/mcp.

Existe ainda uma razão prática para optar pela chave: são gratuitas e você pode criar várias, cada uma com seu histórico de uso (ferramenta, modelo, custo, prévia do prompt) e limite diário opcional em USD em Perfil → Chaves de API MCP. Esse limite é a melhor proteção antes de liberar gastos para um agente autônomo.

Sobre permissões: a configuração da CLI do Devin permite regras por ferramenta através de seletores mcp__<servidor>__<ferramenta>, ideal para servidores pagos.

{
  "permissions": {
    "allow": ["mcp__bananabanana__list_models", "mcp__bananabanana__get_result"],
    "ask": ["mcp__bananabanana__generate_video"]
  }
}

Consultas gratuitas rodam sem interrupções e tarefas de renderização exigem autorização explícita.

Quanto custaram as mídias de demonstração deste artigo?

Preços padrão por geração, exatamente os valores que list_models reporta ao agente:

Ambos os estados vazios foram criados na primeira tentativa — em parte por sorte, em parte porque o estilo vetorial plano é bastante tolerante. Para fotos fotorrealistas de produtos, vale a pena reservar orçamento para algumas regerações.

Se você já utiliza este servidor em outro editor, a configuração do Windsurf acima é a única novidade: mesma chave, mesmo saldo e mesmo histórico de gerações. Nossos guias para Cursor e VS Code cobrem o mesmo servidor nesses clientes. Pronto para começar? Crie uma chave e peça ao Cascade sua primeira imagem.

FAQ

O Windsurf suporta servidores MCP remotos com cabeçalho de autorização?

Sim. Servidores HTTP remotos no mcp_config.json recebem o campo serverUrl (ou url) e um objeto opcional headers. O Cascade suporta transportes stdio, Streamable HTTP e SSE. Tanto serverUrl quanto headers aceitam interpolação com ${env:VAR} e ${file:/caminho}, impedindo que a chave fique exposta em texto puro. Configuração verificada pela documentação oficial em 20 de agosto de 2026.

Qual arquivo de configuração meu agente do Windsurf lê de fato?

Depende do agente. O agente Cascade legado lê ~/.codeium/windsurf/mcp_config.json. O agente Devin Local (padrão em novas abas) lê os arquivos da CLI do Devin: ~/.config/devin/mcp_config.json, .devin/mcp_config.json ou .devin/mcp_config.local.json para chaves pessoais. Se o servidor não for reconhecido após as alterações, confira essa separação.

Preciso de uma conta em nuvem própria para gerar imagens no Windsurf?

Não. Servidores MCP locais exigem chaves de provedores externos com cotas e faturamento na sua conta. O servidor remoto processa as gerações no nosso conjunto gerenciado de chaves, exigindo apenas a chave bb_live_ do seu perfil. Novas contas começam com $0.20 de saldo inicial, suficiente para seis imagens no modelo econômico sem nenhum pagamento prévio.

O Cascade pode gerar vídeos através deste mesmo servidor?

Sim, com uma etapa de confirmação obrigatória. generate_video retorna uma cotação na primeira chamada e não debita nada; o agente precisa repetir a chamada com confirm_cost preenchido com esse valor para iniciar a renderização. Os preços variam de $0.10 por 4 segundos sem áudio em 720p no Veo 3.1 Lite até $4.40 para renderizações topo de linha no Veo 3.1 com áudio; o Omni Flash custa $0.10 por segundo com áudio obrigatório. Os clipes levam de um a dez minutos para processar, enquanto o agente consulta periodicamente get_result.

Por que meu servidor MCP apresenta erro de autenticação no Windsurf?

Em nove de cada dez casos o problema está na chave e não na configuração. Uma variável ${env:BB_API_KEY} ausente é substituída por uma string vazia sem acusar erro, enviando um token bearer vazio e recebendo 401. Certifique-se de que a variável esteja visível para o processo do Windsurf (iniciar pela interface não lê o perfil do shell) ou use ${file:~/.secrets/bb_key.txt}. Se a chave estiver correta e as ferramentas não surgirem, confira se a URL termina em /api/mcp e se uma lista de permissões da equipe não está bloqueando o Server ID.